Skip to content

Commit

Permalink
Documentation on UTIs and macOS security.
Browse files Browse the repository at this point in the history
  • Loading branch information
@rhwood
rhwood committed Sep 10, 2018
1 parent 39d3b51 commit 478a681
Show file tree
Hide file tree
Showing 3 changed files with 91 additions and 10 deletions.
3 changes: 2 additions & 1 deletion help/en/html/doc/Technical/AppPreferences.shtml
View file
Expand Up @@ -38,7 +38,8 @@
<h1 id="preference-spaces">Preference Spaces</h1>
<h2 id="the-current-profile">The Current Profile</h2>
<p>Most preferences are stored together within a single <em>Profile</em>. There are two spaces within a <em>Profile</em>, the <strong>shared</strong> space and the <strong>private</strong> space.</p>
<p>A profile has a location, a name, and an identity. The identity is formed of two parts, a "safe" version of the name that can be used in file or directory names, and a random number (8 hexidecimal digits) to ensure uniqueness.</p>
<p>A Profile has a location, a name, and an identity. The identity is formed of two parts, a "safe" version of the name that can be used in file or directory names, and a random number (8 hexidecimal digits) to ensure uniqueness.</p>
<p>It is recommended that Profile locations have the extension <code>.jmri</code> to allow Profiles to be assigned a Uniform Type Identifier (UTI) in iOS and macOS. JMRI applications default to including the extension in the Profile location when creating one, but use of this extension is not enforced. See <a href="StartUpScripts.shtml">Startup Scripts</a> for more details on UTIs and their use.</p>
<h3 id="shared">Shared</h3>
<p>Shared preferences are preferences within a single profile that are shared across multiple computers running that profile. An example of a shared preference is the use of the LocoNet connection "LocoNet".</p>
<p>Shared preferences are stored in the root of the <code>profile</code> directory within the Profile.</p>
Expand Down
4 changes: 3 additions & 1 deletion help/en/html/doc/Technical/AppPreferences.txt
View file
Expand Up @@ -13,7 +13,9 @@ There are two APIs, *PreferencesManager* and *PreferencesPanel* that implement t

Most preferences are stored together within a single *Profile*. There are two spaces within a *Profile*, the **shared** space and the **private** space.

A profile has a location, a name, and an identity. The identity is formed of two parts, a "safe" version of the name that can be used in file or directory names, and a random number (8 hexidecimal digits) to ensure uniqueness.
A Profile has a location, a name, and an identity. The identity is formed of two parts, a "safe" version of the name that can be used in file or directory names, and a random number (8 hexidecimal digits) to ensure uniqueness.

It is recommended that Profile locations have the extension `.jmri` to allow Profiles to be assigned a Uniform Type Identifier (UTI) in iOS and macOS. JMRI applications default to including the extension in the Profile location when creating one, but use of this extension is not enforced. See [Startup Scripts](StartUpScripts.shtml) for more details on UTIs and their use.

### Shared

Expand Down
94 changes: 86 additions & 8 deletions help/en/html/doc/Technical/StartUpScripts.shtml
View file
Expand Up @@ -271,17 +271,95 @@
<h2 id="macosx">macOS</h2>

JMRI distributions for macOS contain application bundles for each of the
main applications: DecoderPro, PanelPro, etc. These provide familiar
main applications: DecoderPro, PanelPro, and SoundPro. These provide familiar
application icons for the user.

<p>To register the bundles with macOS, they need to be
copied from the distributed disk image onto the user's disk
drive.</p>
<p>The applications are registered with macOS when copied from the
distributed disk image onto the user's disk drive, however, no mechanism
within the JMRI applications takes advantage of this registration.</p>

<h3>Script Details</h3>Each bundle has a startup bash shell
script in the Contents/MacOSX directory what does the actual
startup. This is the same script as used for Linux, see
please see <a href="#linux">that section</a> for details.
<h3>Script Details</h3>

<p>Each bundle has a startup bash shell script in the Contents/MacOSX
directory that performs the actual startup. This is the same script as
used for Linux, see <a href="#linux">that section</a> for details.</p>

<h3>Uniform Type Identifiers</h3>

<p><a href="https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/understanding_utis/understand_utis_intro/understand_utis_intro.html#//apple_ref/doc/uid/TP40001319">Uniform Type Identifiers</a>
(UTIs) are a mechanism that iOS, macOS, and tvOS use to identify file
and URL types to ensure that the correct application is used to open a
file or handle a URL. UTIs allow these operating systems to support
Packages, or directories that are represented to a user as a single file,
and Bundles, which are Packages with executable content.</p>

<p><a href="https://developer.apple.com/library/archive/documentation/Security/Conceptual/AppSandboxDesignGuide/AppSandboxInDepth/AppSandboxInDepth.html#//apple_ref/doc/uid/TP40011183-CH3-SW16">Application Sandboxes</a>
are a security and privacy control in iOS and macOS that limit
applications to accessing data the user has explictly granted the application
access to, or is contained within the sandbox. In iOS, users can only
grant access to files, while in macOS, users can grant access to files
and directories. When requesting access, applications request the operating
system prompt the user to grant access to file types identified by UTI.</p>

<p>Since the JMRI applications are not subject to application sandboxes,
JMRI applications do not export any UTIs that would allow other applications
subject to sandboxes to request permission from the user to view or edit
JMRI Configuration Profiles.</p>

<p>To allow other macOS applications or any iOS app to request permission
from a user to view or edit a JMRI Configuration Profile if the Profile
is in a directory with the <code>.jmri</code> extension, add the following
UTI and document type to that application's Info.plist file:</p>

<code><pre>
&lt;key&gt;UTImportedTypeDeclarations&lt;/key&gt;
&lt;array&gt;
&lt;dict&gt;
&lt;key&gt;UTTypeConformsTo&lt;/key&gt;
&lt;array&gt;
&lt;string&gt;com.apple.package&lt;/string&gt;
&lt;/array&gt;
&lt;key&gt;UTTypeIconFiles&lt;/key&gt;
&lt;array/&gt;
&lt;key&gt;UTTypeIdentifier&lt;/key&gt;
&lt;string&gt;org.jmri.profile&lt;/string&gt;
&lt;key&gt;UTTypeDescription&lt;/key&gt;
&lt;string&gt;JMRI Configuration Profile&lt;/string&gt;
&lt;key&gt;UTTypeTagSpecification&lt;/key&gt;
&lt;dict&gt;
&lt;key&gt;public.filename-extension&lt;/key&gt;
&lt;string&gt;jmri&lt;/string&gt;
&lt;/dict&gt;
&lt;/dict&gt;
&lt;/array&gt;
&lt;key&gt;CFBundleDocumentTypes&lt;/key&gt;
&lt;array&gt;
&lt;dict&gt;
&lt;key&gt;CFBundleTypeName&lt;/key&gt;
&lt;string&gt;JMRI Configuration Profile&lt;/string&gt;
&lt;key&gt;CFBundleTypeIconFiles&lt;/key&gt;
&lt;array/&gt;
&lt;key&gt;LSItemContentTypes&lt;/key&gt;
&lt;array&gt;
&lt;string&gt;org.jmri.profile&lt;/string&gt;
&lt;/array&gt;
&lt;/dict&gt;
&lt;/array&gt;
</pre></code>

<p>Note that you will want to provide icons for these documents; the example
does not. Note also that if, and when, the JMRI applications include the
UTIs, they need to <em>export</em> the UTIs instead of <em>importing</em>
the UTIs, as other non-JMRI applications should.</p>

<p>Note that a UTI is only present for Configuration Profiles, not for Rosters
or User Files, since most users store those within a Configuration Profile.
Rosters also have a structure that is not conducive to defining a UTI for it
(the roster index (<code>roster.xml</code>) is stored adjacent to the
<code>roster</code> directory that contains the individual roster entries,
images, and icons. User files are, if not contained within a Configuration
Profile, in an arbitrary directory, and likely would need individual
access from different applications for editing outside of JMRI.</p>

<h2 id="windows">Windows</h2>
Upto and including JMRI version 2.3.2, the
Expand Down

0 comments on commit 478a681

Please sign in to comment.