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

finish adding explicit sections to build guide

Browse Source
This commit is contained in:
Daniel Micay 2020-12-06 13:30:13 -05:00
parent f4083f40df
commit 983a1871f1
1 changed files with 143 additions and 143 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

286
static/build.html
View File

@ -287,57 +287,57 @@
for developing a feature. It's easier to port between stable tags that are known to for developing a feature. It's easier to port between stable tags that are known to
work properly than dealing with a moving target.</p> work properly than dealing with a moving target.</p>
<h4 id="development-branch"> <section id="development-branch">
<a href="#development-branch">Development branch</a> <h4><a href="#development-branch">Development branch</a></h4>
</h4>
<p>The <code>11</code> branch is the only active development branch for GrapheneOS <p>The <code>11</code> branch is the only active development branch for GrapheneOS
development. Older branches are no longer maintained. It is currently used for all development. Older branches are no longer maintained. It is currently used for all
officially supported devices and should be used for the basis of ports to other officially supported devices and should be used for the basis of ports to other
devices. Occasionally, some devices may be supported through device support branches devices. Occasionally, some devices may be supported through device support branches
to avoid impacting other devices with changes needed to support them.</p> to avoid impacting other devices with changes needed to support them.</p>
<pre>mkdir grapheneos-11 <pre>mkdir grapheneos-11
cd grapheneos-11 cd grapheneos-11
repo init -u https://github.com/GrapheneOS/platform_manifest.git -b 11 repo init -u https://github.com/GrapheneOS/platform_manifest.git -b 11
repo sync -j32</pre> repo sync -j32</pre>
<p>If your network is unreliable and <code>repo sync</code> fails, you can run the <p>If your network is unreliable and <code>repo sync</code> fails, you can run the
<code>repo sync</code> command again to continue from where it was interrupted. It <code>repo sync</code> command again to continue from where it was interrupted. It
handles connection failures robustly and you shouldn't start over from scratch.</p> handles connection failures robustly and you shouldn't start over from scratch.</p>
</section>
<h4 id="stable-release"> <section id="stable-release">
<a href="#stable-release">Stable release</a> <h4><a href="#stable-release">Stable release</a></h4>
</h4>
<p>Pick a specific release for a device from the <a href="/releases">releases page</a> <p>Pick a specific release for a device from the <a href="/releases">releases page</a>
and download the source tree. Note that some devices use different Android Open Source and download the source tree. Note that some devices use different Android Open Source
Project branches so they can end up with different tags. Make sure to use the correct Project branches so they can end up with different tags. Make sure to use the correct
tag for a device. For devices without official support, use the latest tag marked as tag for a device. For devices without official support, use the latest tag marked as
being appropriate for generic / other devices in the release notes.</p> being appropriate for generic / other devices in the release notes.</p>
<pre>mkdir grapheneos-TAG_NAME <pre>mkdir grapheneos-TAG_NAME
cd grapheneos-TAG_NAME cd grapheneos-TAG_NAME
repo init -u https://github.com/GrapheneOS/platform_manifest.git -b refs/tags/TAG_NAME</pre> repo init -u https://github.com/GrapheneOS/platform_manifest.git -b refs/tags/TAG_NAME</pre>
<p>Verify the manifest:</p> <p>Verify the manifest:</p>
<pre>gpg --recv-keys 65EEFE022108E2B708CBFCF7F9E712E59AF5F22A <pre>gpg --recv-keys 65EEFE022108E2B708CBFCF7F9E712E59AF5F22A
cd .repo/manifests cd .repo/manifests
git verify-tag $(git describe) git verify-tag $(git describe)
cd ../..</pre> cd ../..</pre>
<p>Complete the source tree download:</p> <p>Complete the source tree download:</p>
<pre>repo sync -j32</pre> <pre>repo sync -j32</pre>
<p>The manifest for the latest stable release refers to the revisions in other <p>The manifest for the latest stable release refers to the revisions in other
repositories via commit hashes rather than tag names. This avoids the need to use a repositories via commit hashes rather than tag names. This avoids the need to use a
script to verify tag signatures across all the repositories, since they simply point script to verify tag signatures across all the repositories, since they simply point
to the same commits with the same hashes.</p> to the same commits with the same hashes.</p>
<p>Note that the repo command itself takes care of updating itself and uses gpg to <p>Note that the repo command itself takes care of updating itself and uses gpg to
verify by default.</p> verify by default.</p>
</section>
</section> </section>
<section id="updating-and-switching-branches-or-tags"> <section id="updating-and-switching-branches-or-tags">
@ -580,43 +580,43 @@ cd ../..</pre>
same scripts along with the expectation of it using the same passphrase as the other same scripts along with the expectation of it using the same passphrase as the other
keys.</p> keys.</p>
<h4 id="encrypting-keys"> <section id="encrypting-keys">
<a href="#encrypting-keys">Encrypting keys</a> <h4><a href="#encrypting-keys">Encrypting keys</a></h4>
</h4>
<p>You can (re-)encrypt your signing keys using the <code>encrypt_keys</code> script, <p>You can (re-)encrypt your signing keys using the <code>encrypt_keys</code> script,
which will prompt for the old passphrase (if any) and new passphrase:</p> which will prompt for the old passphrase (if any) and new passphrase:</p>
<pre>script/encrypt_keys.sh keys/crosshatch</pre> <pre>script/encrypt_keys.sh keys/crosshatch</pre>
<p>The <code>script/decrypt_keys.sh</code> script can be used to remove encryption, <p>The <code>script/decrypt_keys.sh</code> script can be used to remove encryption,
which is not recommended. The script exists primarily for internal usage to decrypt which is not recommended. The script exists primarily for internal usage to decrypt
the keys in tmpfs to perform signing.</p> the keys in tmpfs to perform signing.</p>
</section>
<h4 id="enabling-updatable-apex-components"> <section id="enabling-updatable-apex-components">
<a href="#enabling-updatable-apex-components">Enabling updatable APEX components</a> <h4><a href="#enabling-updatable-apex-components">Enabling updatable APEX components</a></h4>
</h4>
<p>GrapheneOS disables updatable APEX components for the officially supported devices <p>GrapheneOS disables updatable APEX components for the officially supported devices
and targets inheriting from the mainline target, so APEX signing keys are not needed and targets inheriting from the mainline target, so APEX signing keys are not needed
and this section can be ignored for unmodified builds.</p> and this section can be ignored for unmodified builds.</p>
<p>GrapheneOS uses the <code>TARGET_FLATTEN_APEX := true</code> format to include APEX <p>GrapheneOS uses the <code>TARGET_FLATTEN_APEX := true</code> format to include APEX
components as part of the base OS without supporting out-of-band updates.</p> components as part of the base OS without supporting out-of-band updates.</p>
<p><strong>If you don't disable updatable APEX packages, you need to generate an APK and <p><strong>If you don't disable updatable APEX packages, you need to generate an APK and
AVB key for each APEX component and extend the GrapheneOS release.sh script to pass AVB key for each APEX component and extend the GrapheneOS release.sh script to pass
the appropriate parameters to replace the APK and AVB keys for each APEX the appropriate parameters to replace the APK and AVB keys for each APEX
component.</strong></p> component.</strong></p>
<p>APEX components that are not flattened are a signed APK (used to verify updates) <p>APEX components that are not flattened are a signed APK (used to verify updates)
with an embedded filesystem image signed with an AVB key (for verified boot). Each with an embedded filesystem image signed with an AVB key (for verified boot). Each
APEX package must have a unique set of keys. GrapheneOS has no use for these APEX package must have a unique set of keys. GrapheneOS has no use for these
out-of-band updates at this time and flattening APEX components avoids needing a bunch out-of-band updates at this time and flattening APEX components avoids needing a bunch
of extra keys and complexity.</p> of extra keys and complexity.</p>
<p>For now, consult the upstream documentation on generating these keys. It will be <p>For now, consult the upstream documentation on generating these keys. It will be
covered here in the future.</p> covered here in the future.</p>
</section>
</section> </section>
<section id="generating-signed-factory-images-and-full-update-packages"> <section id="generating-signed-factory-images-and-full-update-packages">
@ -661,26 +661,25 @@ cd ../..</pre>
Stable channel after public testing. A similar approach is recommended for derivatives Stable channel after public testing. A similar approach is recommended for derivatives
of GrapheneOS.</p> of GrapheneOS.</p>
<h4 id="generating-delta-updates"> <section id="generating-delta-updates">
<a href="#generating-delta-updates">Generating delta updates</a> <h4><a href="#generating-delta-updates">Generating delta updates</a></h4>
</h4>
<p>Incremental updates shipping only the changes between two versions can be generated <p>Incremental updates shipping only the changes between two versions can be generated
as a much more efficient way of shipping updates than a full update package containing as a much more efficient way of shipping updates than a full update package containing
the entire operating system. The GrapheneOS Updater app will automatically use a delta the entire operating system. The GrapheneOS Updater app will automatically use a delta
update if one exists for going directly from the currently installed version to the update if one exists for going directly from the currently installed version to the
latest release. In order to generate a delta update, the original signed target files latest release. In order to generate a delta update, the original signed target files
package for both the source version and target version are needed. The package for both the source version and target version are needed. The
<code>script/generate_delta.sh</code> script provides a wrapper script for generating <code>script/generate_delta.sh</code> script provides a wrapper script for generating
delta updates by passing the device, source version build number and target version delta updates by passing the device, source version build number and target version
build number. For example:</p> build number. For example:</p>
<pre>script/generate_delta.sh crosshatch 2019.09.25.00 2019.10.07.21</pre> <pre>script/generate_delta.sh crosshatch 2019.09.25.00 2019.10.07.21</pre>
<p>The script assumes that the releases are organized in the following directory <p>The script assumes that the releases are organized in the following directory
structure:</p> structure:</p>
<pre>releases <pre>releases
├── 2019.09.25.00 ├── 2019.09.25.00
│   └── release-crosshatch-2019.09.25.00 │   └── release-crosshatch-2019.09.25.00
│      ├── crosshatch-factory-2019.09.25.00.zip │      ├── crosshatch-factory-2019.09.25.00.zip
@ -698,10 +697,11 @@ cd ../..</pre>
   ├── crosshatch-target_files-2019.10.07.21.zip    ├── crosshatch-target_files-2019.10.07.21.zip
   └── crosshatch-testing</pre>    └── crosshatch-testing</pre>
<p>Incremental updates are uploaded alongside the update packages and update metadata <p>Incremental updates are uploaded alongside the update packages and update metadata
on the static web server used as an update server. The update client will on the static web server used as an update server. The update client will
automatically check for an incremental update and use it if available. No additional automatically check for an incremental update and use it if available. No additional
metadata is needed to make incremental updates work.</p> metadata is needed to make incremental updates work.</p>
</section>
</section> </section>
</section> </section>
@ -964,20 +964,19 @@ mv android-studio studio</pre>
<section id="compatibility-test-suite"> <section id="compatibility-test-suite">
<h3><a href="#compatibility-test-suite">Compatibility Test Suite</a></h3> <h3><a href="#compatibility-test-suite">Compatibility Test Suite</a></h3>
<h4 id="compatibility-test-suite-download"> <section id="compatibility-test-suite-download">
<a href="#compatibility-test-suite-download">Download</a> <h4><a href="#compatibility-test-suite-download">Download</a></h4>
</h4>
<p>Testing with the Compatibility Test Suite (CTS) can be done by either building the <p>Testing with the Compatibility Test Suite (CTS) can be done by either building the
test suite from source or using the official releases.</p> test suite from source or using the official releases.</p>
<p>Official releases of the CTS can be downloaded from <p>Official releases of the CTS can be downloaded from
<a href="https://source.android.com/compatibility/cts/downloads">the Compatibility <a href="https://source.android.com/compatibility/cts/downloads">the Compatibility
Suite Downloads page</a>. You should download the CTS for the relevant release Suite Downloads page</a>. You should download the CTS for the relevant release
(Android 11) and architecture (ARM). There's a separate zip for the main CTS, the (Android 11) and architecture (ARM). There's a separate zip for the main CTS, the
manual portion (CTS Verifier) and the CTS for Instant Apps. The latest release of the manual portion (CTS Verifier) and the CTS for Instant Apps. The latest release of the
CTS Media Files also needs to be downloaded from that section.</p> CTS Media Files also needs to be downloaded from that section.</p>
<pre>mkdir -p ~/android/cts/{arm,x86} <pre>mkdir -p ~/android/cts/{arm,x86}
cd ~/android/cts/arm cd ~/android/cts/arm
curl -O https://dl.google.com/dl/android/cts/android-cts-11_r1-linux_x86-arm.zip curl -O https://dl.google.com/dl/android/cts/android-cts-11_r1-linux_x86-arm.zip
unzip android-cts-11_r1-linux_x86-arm.zip unzip android-cts-11_r1-linux_x86-arm.zip
@ -996,66 +995,67 @@ cd ~/android/cts
curl -O https://dl.google.com/dl/android/cts/android-cts-media-1.5.zip curl -O https://dl.google.com/dl/android/cts/android-cts-media-1.5.zip
unzip android-cts-media-1.5.zip unzip android-cts-media-1.5.zip
rm android-cts-media-1.5.zip</pre> rm android-cts-media-1.5.zip</pre>
</section>
<h4 id="compatibility-test-suite-setup"> <section id="compatibility-test-suite-setup">
<a href="#compatibility-test-suite-setup">Setup</a> <h4><a href="#compatibility-test-suite-setup">Setup</a></h4>
</h4> <p>You'll need a device attached to your computer with ADB enabled along with the
<p>You'll need a device attached to your computer with ADB enabled along with the Android SDK installed. The build-tools and platform-tools packages need to be
Android SDK installed. The build-tools and platform-tools packages need to be installed and the binaries need to be added to your PATH. See the
installed and the binaries need to be added to your PATH. See the <a href="#standalone-sdk">standalone SDK installation instructions</a> above.</p>
<a href="#standalone-sdk">standalone SDK installation instructions</a> above.</p>
<p>Copy media onto the device:</p> <p>Copy media onto the device:</p>
<pre>cd android-cts-media-1.5 <pre>cd android-cts-media-1.5
./copy_images.sh ./copy_images.sh
./copy_media.sh</pre> ./copy_media.sh</pre>
<p>You also need to do some basic setup for the device. It's possible for changes from <p>You also need to do some basic setup for the device. It's possible for changes from
a baseline install to cause interference, so it can be a good idea to factory reset a baseline install to cause interference, so it can be a good idea to factory reset
the device if assorted changes have been made. The device needs to be running a user the device if assorted changes have been made. The device needs to be running a user
build for the security model to be fully intact in order to pass all the security build for the security model to be fully intact in order to pass all the security
tests. A userdebug build is expected to fail some of the tests. GrapheneOS also makes tests. A userdebug build is expected to fail some of the tests. GrapheneOS also makes
various changes intentionally deviating from the requirements expected by the CTS, so various changes intentionally deviating from the requirements expected by the CTS, so
there will always be some expected failures. A few of the tests are also known to be there will always be some expected failures. A few of the tests are also known to be
quite flaky or broken even with the stock OS and/or AOSP. These will be documented quite flaky or broken even with the stock OS and/or AOSP. These will be documented
here at some point.</p> here at some point.</p>
<ul> <ul>
<li>Must be connected to a WiFi network with IPv6 internet access</li> <li>Must be connected to a WiFi network with IPv6 internet access</li>
<li>Must have a working SIM card with mobile data with IPv6 internet access</li> <li>Must have a working SIM card with mobile data with IPv6 internet access</li>
<li>Disable SIM lock</li> <li>Disable SIM lock</li>
<li>Enable Bluetooth</li> <li>Enable Bluetooth</li>
<li>Enable NFC</li> <li>Enable NFC</li>
<li>Open / close Chromium to deal with initial setup</li> <li>Open / close Chromium to deal with initial setup</li>
<li>Prop up with a good object to focus on and good lighting for Camera tests. <li>Prop up with a good object to focus on and good lighting for Camera tests.
Both the front and rear cameras will be used, so ensure this is true for both the Both the front and rear cameras will be used, so ensure this is true for both the
front and the rear cameras.</li> front and the rear cameras.</li>
<li>Bluetooth beacons for Bluetooth tests</li> <li>Bluetooth beacons for Bluetooth tests</li>
<li>Must have a great GPS/GNSS signal for location tests</li> <li>Must have a great GPS/GNSS signal for location tests</li>
<li>SIM card with carrier privilege rules</li> <li>SIM card with carrier privilege rules</li>
<li>Secure element applet installed on the embedded secure element or SIM <li>Secure element applet installed on the embedded secure element or SIM
card</li> card</li>
<li>At least one Wi-Fi RTT access point powered up but not connected to any <li>At least one Wi-Fi RTT access point powered up but not connected to any
network</li> network</li>
<li>The screen lock must be disabled.</li> <li>The screen lock must be disabled.</li>
</ul> </ul>
</section>
<h4 id="compatibility-test-suite-run-modules"> <section id="compatibility-test-suite-run-modules">
<a href="#compatibility-test-suite-run-modules">Run modules</a> <h4><a href="#compatibility-test-suite-run-modules">Run modules</a></h4>
</h4>
<p>Run the test harness:</p> <p>Run the test harness:</p>
<pre>./android-cts/tools/cts-tradefed</pre> <pre>./android-cts/tools/cts-tradefed</pre>
<p>Note that <code>_JAVA_OPTIONS</code> being set will break the version detection.</p> <p>Note that <code>_JAVA_OPTIONS</code> being set will break the version detection.</p>
<p>To obtain a list of CTS modules:</p> <p>To obtain a list of CTS modules:</p>
<pre>list modules</pre> <pre>list modules</pre>
<p>To run a specific module and avoid wasting time capturing device information:</p> <p>To run a specific module and avoid wasting time capturing device information:</p>
<pre>run cts --skip-device-info --module CtsModuleName</pre> <pre>run cts --skip-device-info --module CtsModuleName</pre>
<p>To speed up initialization after running some initial tests:</p> <p>To speed up initialization after running some initial tests:</p>
<pre>run cts --skip-device-info --skip-preconditions --module CtsModuleName</pre> <pre>run cts --skip-device-info --skip-preconditions --module CtsModuleName</pre>
<p>It's possible to run the whole standard CTS plan with a single command, but running <p>It's possible to run the whole standard CTS plan with a single command, but running
specific modules is recommended, especially if you don't have everything set up for specific modules is recommended, especially if you don't have everything set up for
the entire test suite.</p> the entire test suite.</p>
</section>
</section> </section>
</section> </section>