security/hakurei.app
security/hakurei.app
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 4 Wiki Activity

Update "Storage access" usage guide section

Browse Source
This commit is contained in:
Dmitry Muhomor 2022-07-15 13:18:34 +03:00 committed by Daniel Micay
parent c574abb552
commit 7d48d91c50
1 changed files with 113 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

157
static/usage.html
View File

@ -226,58 +226,127 @@
<p>GrapheneOS inherits the same baseline approach to storage access as modern <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 Android and extends it with our Storage Scopes feature as a fully compatible
alternative to the standard Android storage permissions. This section provides a alternative to standard Android storage permissions. This section provides an
brief high level overview of the standard approach to storage access primarily to overview of the standard approach to storage access primarily to provide context
provide context for explaining Storage Scopes.</p> for explaining Storage Scopes.</p>
<p>By default, Android apps can only access their own sandboxed storage (internal <p>There are two types of app-accessible storage:</p>
storage) and their own scoped directory within the <code>Android/data</code>
directory in the user's home directory (external storage).</p>
<p>Android apps can open the system file picker interface to have the user store <ul>
or load one or more files/directories on their behalf. Using this approach gives <li>app-private ("internal") storage:
the user control over where files are stored in their home directory and which <ul>
files/directories can be used by the app. This is based on the Storage Access <li>inaccessible to other apps</li>
Framework (SAF) introduced in Android 4.4. SAF allows the user to grant access to <li>doesn't require any permission for full access</li>
the files/directories in their home directory, external drives and also app-based <li>cleared when the app is uninstalled</li>
storage providers such as network shares, cloud storage, an encrypted volume, an </ul>
external drive with a filesystem the OS doesn't support for external drives, etc. </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 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> has removed the legacy approach for accessing external drives.</p>
<p>The more traditional approach to accessing files outside of the app's storage <h3>Storage Scopes</h3>
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>
<p>Since the Storage permission became a limited Media permission for apps built <p>GrapheneOS provides the Storage Scopes feature as a fully compatible alternative
for modern Android, a separate "All files access" special access permission was to the standard Android storage permissions.
added for file management. As a special access permission, it can't be directly Storage Scopes can be enabled only if the app doesn't have any storage permission.
requested via a dialog and is listed in a dedicated section rather than a toggle Enabling Storage Scopes makes the app assume that is has all of storage permissions
with the other permissions. This gives full management access to nearly all of the that were requested by it, despite not actually having any of them.</p>
user's home directory.</p>
<p>The media management special access permission can be granted to apps with the <p>This means that the app can't see any of the files that were created by other apps.
Files and Media / Media permission or All files access in order to grant further The app is still allowed to create files and directories, same as any other modern
access beyond the home directory to media on connected storage devices.</p> app that doesn't have any storage access permission.</p>
<p>GrapheneOS provides Storage Scopes as a fully compatible alternative to the <p>Apps that would normally use the legacy storage mode are switched to the
standard Android storage permissions. Instead of granting storage permissions, modern storage mode when Storage Scopes is enabled.</p>
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 <p>If the app requests the "All files access" permission (or is a legacy app
directory but can only access the files it has created itself. Users can then that requests <code>WRITE_EXTERNAL_STORAGE</code> permission), then the write
optionally add files and directories as storage scopes to permit the app to access restrictions that are normally applied to apps that don't have a storage access
files created by other apps.</p> 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>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>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>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>
<section id="accessibility"> <section id="accessibility">