diff options
Diffstat (limited to 'static/usage.html')
| -rw-r--r-- | static/usage.html | 157 |
1 files changed, 113 insertions, 44 deletions
diff --git a/static/usage.html b/static/usage.html index 031f7571..58d5116b 100644 --- a/static/usage.html +++ b/static/usage.html @@ -226,58 +226,127 @@ <p>GrapheneOS inherits the same baseline approach to storage access as modern Android and extends it with our Storage Scopes feature as a fully compatible - alternative to the standard Android storage permissions. This section provides a - brief high level overview of the standard approach to storage access primarily to - provide context for explaining Storage Scopes.</p> + alternative to standard Android storage permissions. This section provides an + overview of the standard approach to storage access primarily to provide context + for explaining Storage Scopes.</p> - <p>By default, Android apps can only access their own sandboxed storage (internal - storage) and their own scoped directory within the <code>Android/data</code> - directory in the user's home directory (external storage).</p> + <p>There are two types of app-accessible storage:</p> - <p>Android apps can open the system file picker interface to have the user store - or load one or more files/directories on their behalf. Using this approach gives - the user control over where files are stored in their home directory and which - files/directories can be used by the app. This is based on the Storage Access - Framework (SAF) introduced in Android 4.4. SAF allows the user to grant access to - the files/directories in their home directory, external drives and also app-based - storage providers such as network shares, cloud storage, an encrypted volume, an - external drive with a filesystem the OS doesn't support for external drives, etc. + <ul> + <li>app-private ("internal") storage: + <ul> + <li>inaccessible to other apps</li> + <li>doesn't require any permission for full access</li> + <li>cleared when the app is uninstalled</li> + </ul> + </li> + <li>shared ("external") storage: + <ul> + <li>shared with other apps</li> + <li>access is regulated with permissions</li> + <li>files persist after uninstallation</li> + </ul> + Android/data/ and Android/obb/ directories aren't considered to be parts + of shared storage. + </li> + </ul> + + <p>For modern apps, access to the shared storage is controlled in the following way:</p> + + <ul> + <li>Without any storage permission, an app is allowed to: + <ul> + <li>create media files in standard directories (audio in Music/, + Ringtones/, etc, images in Pictures/ and DCIM/, videos in DCIM/ + and Movies/)</li> + <li>create files of any type (both media and non-media) in Documents/ + and Download/</li> + <li>create new directories inside standard directories</li> + <li>rename/delete files that were created by the app itself</li> + <li>rename/delete directories if it can rename/delete all files within + those directories</li> + </ul> + </li> + <li>Media access permission ("Allow access to media only", + <code>READ_EXTERNAL_STORAGE</code>) allows the app to read media files + that were created by other apps. Non-media files remain invisible to it.</li> + <li>Media management special access permission ("Allow app to manage media", + <code>MANAGE_MEDIA</code>) allows the app to delete and to rename media + files created by other apps.</li> + <li>"All files access" special access permission (<code>MANAGE_EXTERNAL_STORAGE</code>) + allows the app to read, create, rename and delete files and directories + of any type in any directory of the shared storage (including the root + directory).</li> + </ul> + + <p>For legacy apps (those that target Android 9 or lower and those that target + Android 10 and request legacy storage mode), storage access permissions have + a different meaning:</p> + <ul> + <li>Without a storage permission, app is not allowed any type of access to + any files or directories inside the shared storage.</li> + <li><code>READ_EXTERNAL_STORAGE</code> permission allows the app to read both + media and non-media files in any directory.</li> + <li><code>WRITE_EXTERNAL_STORAGE</code> permission allows the app to create, + rename and delete files (of any type) and directories in any directory of + shared storage (including the root directory).</li> + </ul> + + <p>Additionally, both modern and legacy Android apps can open the system file + picker interface to have the user store or load one or more files/directories on + their behalf. This type of access doesn't require any of the permissions listed + above. + Using this approach gives the user control over where files are stored in their + home directory and which files/directories can be used by the app. This is based on + the Storage Access Framework (SAF) introduced in Android 4.4. SAF allows the user + to grant access to files/directories in their home directory, external drives + and also app-based storage providers such as network shares, cloud storage, an + encrypted volume, an external drive with a filesystem the OS doesn't support for + external drives, etc. This is the only way to use those app-based storage providers and modern Android has removed the legacy approach for accessing external drives.</p> - <p>The more traditional approach to accessing files outside of the app's storage - directories is requesting storage permissions to obtain broad access to the user's - home directory. The traditional Storage permission toggle was renamed to Files and - Media for legacy apps and Media for modern apps. For legacy apps, it gives access - to most of the user's home directory other than certain special areas. For modern - apps, it only gives access to files created by the app and indexed media. Media is - indexed and placed into the standard media collections if it's in one of the - standard media directories without a file called <code>.nomedia</code> in the - directory hierarchy. Apps can also add their files to the media store index - themselves. You can see the indexed media collections via the categories for - Photos, etc. in the system file manager. These aren't directories themselves but - rather all of the indexed media from all directories in the user's home directory. - These are not the same thing as the standard top-level directories for Pictures, - etc.</p> + <h3>Storage Scopes</h3> + + <p>GrapheneOS provides the Storage Scopes feature as a fully compatible alternative + to the standard Android storage permissions. + Storage Scopes can be enabled only if the app doesn't have any storage permission. + Enabling Storage Scopes makes the app assume that is has all of storage permissions + that were requested by it, despite not actually having any of them.</p> + + <p>This means that the app can't see any of the files that were created by other apps. + The app is still allowed to create files and directories, same as any other modern + app that doesn't have any storage access permission.</p> + + <p>Apps that would normally use the legacy storage mode are switched to the + modern storage mode when Storage Scopes is enabled.</p> + + <p>If the app requests the "All files access" permission (or is a legacy app + that requests <code>WRITE_EXTERNAL_STORAGE</code> permission), then the write + restrictions that are normally applied to apps that don't have a storage access + permission are relaxed to provide the same write access that the app would have if + it was granted the "All files access" permission. + This is done to ensure compatibility with apps that, for example, create a new + directory in the root of shared storage, or write a text file (eg lyrics.txt) to + the Music/ directory (normally, only audio files can be placed there). + No additional read access is granted to such apps, they still can see only their + own files. + </p> - <p>Since the Storage permission became a limited Media permission for apps built - for modern Android, a separate "All files access" special access permission was - added for file management. As a special access permission, it can't be directly - requested via a dialog and is listed in a dedicated section rather than a toggle - with the other permissions. This gives full management access to nearly all of the - user's home directory.</p> + <p>For all other apps, enabling Storage Scopes doesn't grant any additional + storage access beyond what a modern app that doesn't have any storage permission + already has.</p> - <p>The media management special access permission can be granted to apps with the - Files and Media / Media permission or All files access in order to grant further - access beyond the home directory to media on connected storage devices.</p> + <p>Optionally, users can specify which of the files created by other apps the app + can access. Access can be granted to a specific file or to all files in + a directory. The standard SAF picker is used for this purpose in a special mode + where it shows only shared storage files/directories.</p> - <p>GrapheneOS provides Storage Scopes as a fully compatible alternative to the - standard Android storage permissions. Instead of granting storage permissions, - users can enable Storage Scopes to grant the requested permissions in a highly - restricted mode where the app can create files/directories in the user's home - directory but can only access the files it has created itself. Users can then - optionally add files and directories as storage scopes to permit the app to access - files created by other apps.</p> + <p>The most significant limitation of Storage Scopes is the fact that the app + will lose access to files that it created if it's uninstalled and then installed + again, same as any other app that doesn't have a storage access permission. + As a workaround, users can manually grant access to these files/directories via + SAF picker.</p> </section> <section id="accessibility"> |