add usage guide section on sandboxed Play services

1 files changed, 68 insertions, 0 deletions

diff --git a/static/usage.html b/static/usage.html
index 69e1f8d5..7c9d8b61 100644
--- a/static/usage.html
+++ b/static/usage.html
@@ -87,6 +87,7 @@
                         </ul>
                     </li>
                     <li><a href="#lte-only-mode">LTE-only mode</a></li>
+                    <li><a href="#sandboxed-play-services">Sandboxed Play services (experimental preview)</a></li>
                 </ul>
             </nav>
 
@@ -672,6 +673,73 @@
                 itself. The intention of the LTE-only feature is only hardening against remote
                 exploitation by disabling an enormous amount of legacy code.</p>
             </section>
+
+            <section id="sandboxed-play-services">
+                <h2><a href="#sandboxed-play-services">Sandboxed Play services (experimental preview)</a></h2>
+
+                <p>This feature is currently only available in experimental preview releases of
+                GrapheneOS but will become available in the stable releases as an experimental
+                feature in the near future.</p>
+
+                <p>GrapheneOS has experimental support for installing the official releases of
+                com.android.vending (Google Play Store), com.google.android.gms (Google Play
+                services), com.google.android.gsf (Google Services Framework) as regular sandboxed
+                apps in a specific profile. These receive no special privileges and the OS itself
+                doesn't include any of the usual integration to make use of them itself to provide
+                services offered by the OS. They run as unprivileged, sandboxed apps like any
+                others and GrapheneOS implements shims to make them work without the many
+                privileged permissions and SELinux policy extensions these apps usually
+                require.</p>
+
+                <p>You should install all 3 apps including the Play Store rather than only Play
+                services or there will be missing functionality. Play Store is not simply a user
+                facing app.</p>
+
+                <p>You can obtain the apps from the apps.grapheneos.org repository. We don't yet
+                have a client app for our repository so you'll need to install the APKs manually.
+                The Play Store APK has multiple split APKs which need to be installed together
+                rather than separately, so you'll need to use an app providing split APK
+                installation support. Once we have a client app for our repository, you'll be able
+                to install these and receive automatic updates through the app. Fully automatic
+                updates without user interaction won't be supported until Android 12 which adds
+                support for unattended upgrades of API 29+ apps by the app responsible for the
+                initial installation if it supports the feature.</p>
+
+                <ul>
+                    <li><a href="https://apps.grapheneos.org/packages/com.android.vending/">com.android.vending</a></li>
+                    <li><a href="https://apps.grapheneos.org/packages/com.google.android.gms/">com.google.android.gms</a></li>
+                    <li><a href="https://apps.grapheneos.org/packages/com.google.android.gsf/">com.google.android.gsf</a></li>
+                </ul>
+
+                <p>Secondary user support has not yet been implemented so this currently won't
+                work in secondary profiles. This will be a crucial part of the functionality and
+                is currently the top priority for improving the feature and bringing it closer to
+                being ready for production usage.</p>
+
+                <p>The Play Store app cannot install and update apps as it normally would since it
+                depends entirely on privileged permissions for unattended app installation,
+                updates and removal. GrapheneOS currently includes partial shims to make this
+                partially work. It's currently unclear if we'll flesh this out and include it in
+                the production version of this feature or whether we'll drop it and simply have
+                people use Aurora Store with the Play Store only installed to provide APIs used by
+                apps using Play services.</p>
+
+                <p>The core functionality and APIs are almost entirely supported already since
+                GrapheneOS largely only has to coerce these apps into continuing to run without
+                being able to use any of the usual invasive OS integration. Certain important
+                functionality. Certain functionality is not yet supported. Play Store feature
+                delivery and Play services functionality delivered via dynamite modules are not
+                yet functionality. Shims will be required to make this work without depending on
+                weakening SELinux MAC and MLS policies to permit it like the stock OS.</p>
+
+                <p>Play Store won't be able to install apps due to lack of the unattended app
+                install / upgrade permissions. We have experimental support for making it able to
+                install apps with user interaction but it isn't included in the initial releases
+                and it's unclear if we'll be including it. It would need to be more complete and
+                robust, and it may be difficult to implement and maintain. Our priority is adding
+                support for secondary profiles and getting more of the functionality working along
+                with fixing rough edges.</p>
+            </section>
         </main>
         <footer>
             <a href="/"><img src="/mask-icon.svg" width="512" height="512" alt=""/>GrapheneOS</a>