diff options
19 files changed, 662 insertions, 606 deletions
diff --git a/en/_index.yaml b/en/_index.yaml index ba6f2f4a..bb165dd0 100644 --- a/en/_index.yaml +++ b/en/_index.yaml @@ -7,10 +7,10 @@ landing_page: path: /source/downloading rows: - items: - - heading: Android 8.0 updates + - heading: 8.0 interfaces and architecture description: > - Port the latest Android platform to create compelling - devices for your customers. + Port the latest Android platform using simple HIDL interfaces to create + compelling devices for your customers. <style> .devsite-feedback-button { display: none; @@ -21,8 +21,8 @@ landing_page: } </style> buttons: - - label: Update now - path: /devices/ + - label: Learn Treble + path: /devices/architecture/treble image_path: /images/landing_icon-porting.png - heading: Securing Android is essential description: > @@ -30,7 +30,7 @@ landing_page: implement the latest features. image_path: /images/landing_icon-security.png buttons: - - label: Learn more + - label: Implement Security path: /security/ - heading: Get compatible, get apps description: > @@ -38,7 +38,7 @@ landing_page: get the ability to include more apps. image_path: /images/landing_icon-compatibility.png buttons: - - label: Test devices + - label: Test Devices path: /compatibility/ - classname: devsite-landing-row-large-headings devsite-landing-row-no-image-background tf-about-row devsite-landing-row-75 background: grey @@ -60,32 +60,32 @@ landing_page: image_path: /images/android_stack.png - heading: News items: - - heading: Android 8.0 Documentation + - heading: China Site Availability description: > - Android 8.0 has been released! We've got you covered with complete - documentation on new features, improvements, and enhancements. + This site has been released in China at source.android.google.cn. All + non-reference materials have also been translated into Simplified + Chinese for ease of use. buttons: - - label: August 21st, 2017 - path: /source/site-updates - - heading: Project Treble + - label: September 14th, 2017 + path: https://source.android.google.cn/ + - heading: September Security Bulletin description: > - Treble is a major re-architect of the Android OS framework that makes it - easier, faster, and less costly to update devices to new versions of - Android. + The September 2017 Android Security Bulletin has been published along + with links to associated fixes and new build numbers to support the + September security release. buttons: - - label: August 21st, 2017 - path: /devices/architecture/treble - - heading: HIDL Reference + - label: September 13th, 2017 + path: /security/bulletin/2017-09-01 + - heading: Bluetooth Documentation Suite description: > - The Reference section now includes details on the HAL Interface - Description Language (HIDL) that specifies the interface between a HAL - and its users. + Bluetooth documentation has been greatly expanded to include + descriptions of services, low energy advertising, debugging, and more. buttons: - - label: August 21st, 2017 - path: /reference/hidl/index + - label: August 29th, 2017 + path: /devices/bluetooth/ - classname: devsite-landing-row-100 tf-row-centered items: - buttons: - classname: button button-primary label: More Updates - path: https://android.googlesource.com/platform/docs/source.android.com/+log/master?no-merges + path: /source/site-updates diff --git a/en/_translation.yaml b/en/_translation.yaml new file mode 100644 index 00000000..cf395ffe --- /dev/null +++ b/en/_translation.yaml @@ -0,0 +1,17 @@ +ignore_paths: +- /compatibility/... +- /devices/... +- /images/... +- /reference/... +- /security/... +- /source/... +enable_continuous_translation: True +title: Android Open Source Project +description: Translations for source.android.com +language: +- zh-CN +cc: +- sac-doc-leads+translation@google.com +reviewer: +- daroberts +product: Android diff --git a/en/compatibility/_translation.yaml b/en/compatibility/_translation.yaml new file mode 100644 index 00000000..e8b4b182 --- /dev/null +++ b/en/compatibility/_translation.yaml @@ -0,0 +1,27 @@ +ignore_paths: +- /1.6/... +- /2.1/... +- /2.2/... +- /2.3/... +- /4.0/... +- /4.1/... +- /4.2/... +- /4.3/... +- /4.4/... +- /5.0/... +- /5.1/... +- /6.0/... +- /7.0/... +- /7.1/... +- /8.0/... +- /images/... +enable_continuous_translation: True +title: Android Open Source Project Compatibility tab +description: Translations for SAC compatibility tab +language: +- zh-CN +cc: +- sac-doc-leads+translation@google.com +reviewer: +- daroberts@google.com +product: Android diff --git a/en/compatibility/cts/images/video-verifier.png b/en/compatibility/cts/images/video-verifier.png Binary files differindex b8498779..77ee7fb5 100644 --- a/en/compatibility/cts/images/video-verifier.png +++ b/en/compatibility/cts/images/video-verifier.png diff --git a/en/compatibility/cts/verifier.html b/en/compatibility/cts/verifier.html index 212b2bf0..5483e0da 100644 --- a/en/compatibility/cts/verifier.html +++ b/en/compatibility/cts/verifier.html @@ -23,84 +23,94 @@ -<p>The Android Compatibility Test Suite Verifier (CTS Verifier) is a supplement to - the Compatibility Test Suite (CTS). While CTS checks those APIs and functions - that can be automated, CTS Verifier provides tests for those APIs and functions - that cannot be tested on a stationary device without manual input, like audio - quality, touchscreen, accelerometer, camera, etc.</p> -<h2 id=test_preparation>Test preparation</h2> -<p>The device must have verified Android API compatibility by successfully passing - the Compatibility Test Suite.</p> -<h3 id=hardware_requirements>Hardware requirements</h3> +<p>The Android Compatibility Test Suite Verifier (CTS Verifier) supplements the +Compatibility Test Suite (CTS). While CTS checks APIs and functions that can be +automated, CTS Verifier provides tests for APIs and functions that cannot be +tested on a stationary device without manual input, such as audio quality, +touchscreen, accelerometer, camera, etc.</p> + +<h2 id=test_preparation>Requirements</h2> +<p>Before running CTS Verifier, ensure you have the following equipment:</p> <ul> - <li> A Linux computer with USB 2.0 compatible port - <li> A second Android device with a known compatible Bluetooth, Wi-Fi direct, and - NFC Host Card Emulation (HCE) implementation +<li>Android device that has verified Android API compatibility by successfully +passing the CTS. This will be the device-under-test (DUT).</li> +<li>Linux computer with USB 2.0 compatible port. All connections to the DUT will +be through this port.</li> +<li>Second Android device with a known compatible Bluetooth, Wi-Fi direct, and +NFC Host Card Emulation (HCE) implementation.</li> </ul> -<h3 id=setup>Setup</h3> + +<h2 id=setup>Setting up</h2> +<p>To setup the CTS Verifier testing environment:</p> +<ol> +<li>On the Linux computer: <ul> - <li>Install the <a href="http://developer.android.com/sdk/index.html">Android -SDK</a> on the Linux computer <li>Download the appropriate <a -href="downloads.html">CTS Verifier.apk</a> for the -version of Android under test. - <li>Install CTS Verifier.apk to the <em>Device Under Test</em> (DUT). - <pre class="devsite-terminal devsite-click-to-copy">adb install -r -g CtsVerifier.apk</pre> - <li>Ensure that the device has its system data and time set correctly. +<li>Install the <a href="http://developer.android.com/sdk/index.html">Android +SDK</a>.</li> +<li>Download the +<a href="/compatibility/cts/downloads.html">CTS Verifier APK</a> for the +version of Android to test.</li> </ul> -<h2 id=cts_test_procedure>CTS Verifier test procedure</h2> -<ol> - <li>After the CTS Verifier.apk has been installed, launch the CTS Verifier - application: - -<img src="/compatibility/cts/images/cts-verifier-icon.png" alt="CTS Verifier icon in launcher" id="figure1" /> -<p class="img-caption"> - <strong>Figure 1.</strong> CTS Verifier icon -</p> - - <li>Once opened, the CTS Verifier displays a list of all test sets available for - manual verification: - -<img src="/compatibility/cts/images/cts-verifier-menu.png" alt="CTS Verifier menu of tests" id="figure2" /> -<p class="img-caption"> - <strong>Figure 2.</strong> CTS Verifier menu of tests -</p> - - <li>Each test contains a set of common elements (in some tests, Pass/Fail is - determined automatically): - <ul> - <li><em>Info</em>—a set of instructions to run the test. This will appear as a popup the first - time each test is opened or whenever the <strong>Info</strong> button (？) is pressed. - <li><em>Pass</em>—If the DUT meets the test requirements per the instructions from Info, press - the <strong>Pass</strong> button (✓). - <li><em>Fail</em>—If the DUT does not meet the test requirements per the instructions from Info, - press the <strong>Fail</strong> button (！). - </ul> - -<img src="/compatibility/cts/images/video-verifier.png" alt="Streaming video quality verifier" id="figure3" /> -<p class="img-caption"> - <strong>Figure 3.</strong> Video quality verifier -</p> - +</li> +<li>Connect the DUT to the Linux computer. +<li>From a terminal on the Linux computer, install <code>CtsVerifier.apk</code> +on the DUT. +<pre class="devsite-terminal devsite-click-to-copy"> +adb install -r -g CtsVerifier.apk +</pre> +</li> +<li>Ensure the DUT has the system data and time set correctly.</li> </ol> -<h2 id=specific_test_requirements>Specific test requirements</h2> -<h3 id=usb_accessory>USB Accessory</h3> -<p>In order to run the USB Accessory test, you need a Linux computer to run the - USB desktop machine (host) program.</p> +<h2 id=cts_test_procedure>Running</h2> +<p>Launch the CTS Verifier application by tapping the CTS icon on the DUT:</p> +<img src="/compatibility/cts/images/cts-verifier-icon.png" alt="CTS Verifier +icon in launcher" id="figure1" /> +<figcaption><strong>Figure 1.</strong> CTS Verifier icon</figcaption> + +<p>The app displays several test sets available for manual verification:</p> +<img src="/compatibility/cts/images/cts-verifier-menu.png" alt="CTS Verifier +menu of tests" id="figure2" /> +<figcaption><strong>Figure 2.</strong> CTS Verifier menu of tests.</figcaption> + +<p>Each test contains a set of common elements (Info, Pass, Fail):</p> +<img src="/compatibility/cts/images/video-verifier.png" alt="Streaming video +quality verifier" id="figure3" /> +<figcaption><strong>Figure 3.</strong> Test elements.</figcaption> + +<ul> +<li><strong>Info</strong> (?). Tap to display test instructions. Also appears +automatically the first time a test is opened.</li> +<li><strong>Pass</strong> (✓). Tap if the DUT meets the test requirements per +the Info instructions.</li> +<li><strong>Fail</strong> (!). Tap if the DUT does not meet the test +requirements per the Info instructions.</li> +</ul> + +<aside class="note"><strong>Note:</strong> In some tests, Pass/Fail is +determined automatically.</aside> + +<p>Some tests, such as the USB accessory mode and camera calibration test, +require additional test setup and instructions as detailed in the following +sections.</p> + +<h3 id=usb_accessory>Testing USB accessory mode</h3> +<p>The USB Accessory test requires a Linux computer to run the USB desktop +machine (host) program.</p> <ol> - <li>Connect the DUT to a computer. - <li>Execute the cts-usb-accessory program on the computer found in the CTS Verifier - package. - <pre class="devsite-terminal devsite-click-to-copy">./cts-usb-accessory</pre> - <li>A popup message will appear on the DUT. Select <strong>OK</strong> and go into the USB Accessory Test in the CTS Verifier application. -<br> -<img src="/compatibility/cts/images/screen-lock-test.png" alt="CTS Verifier screen lock test" id="figure4" /> -<p class="img-caption"> - <strong>Figure 4.</strong> Screen lock test -</p> - - <li>Output similar to below will appear on the computer’s console. -</ol> +<li>Connect the DUT to the Linux computer.</li> +<li>On the computer, execute the <code>cts-usb-accessory</code> program from the +CTS Verifier package: +<pre class="devsite-terminal devsite-click-to-copy">./cts-usb-accessory</pre> +</li> +<li>Wait for a popup message to appear on the DUT, then select +<strong>OK</strong>.<br> +<img src="/compatibility/cts/images/screen-lock-test.png" alt="CTS Verifier +usb accessory test" id="figure4" /> +<figcaption><strong>Figure 4.</strong> USB accessory test.</figcaption> +</li> +<li>Go to the USB Accessory Test in the CTS Verifier application.</li> +<li>On the computer, review the output from the console. Example output: <pre class="devsite-click-to-copy"> CTS USB Accessory Tester Found possible Android device (413c:2106) - attempting to switch to accessory @@ -130,92 +140,106 @@ Found Android device in accessory mode (18d1:2d01)... [RECV] Message from Android device #10 [SENT] Message from Android accessory #10 </pre> -<h3 id=camera_field_of_view_calibration>Camera field of view calibration</h3> -<p>This field of view calibration procedure is designed to be a quick way to - determine the device field of view with moderate accuracy. -<p><strong>Setup</strong> - Print the <a -href="/compatibility/calibration-pattern.pdf">calibration-pattern.pdf</a> -target file and mount it on a rigid backing. Print on 11” x 17” or A3. Orient -the camera device and the printed target as shown in the diagram below:</p> - -<img src="/compatibility/cts/images/camera-printed-target.png" alt="Camera printed target" id="figure5" /> -<p class="img-caption"> - <strong>Figure 5.</strong> Camera printed target -</p> - -<p><strong>Setting the target width</strong> - Measure the distance between the -solid lines on the target pattern in centimeters to account for printing -inaccuracies (~38 cm).</p> +</li> +</ol> + +<h3 id=camera_field_of_view_calibration>Calibrating camera field of view</h3> +<p>Use the field of view calibration procedure to quickly determine the device +field of view with moderate accuracy.</p> + <ol> - <li>Start the calibration application. - <li>Press the setup button and select “Marker distance” to enter the distance. - <li>Measure and enter the distance to the target pattern (~100 cm). - <li>Press the back button to return to the calibration preview. +<li>Setup the test environment: +<ol> +<li>Print the +<a href="/compatibility/calibration-pattern.pdf">calibration-pattern.pdf</a> +target file on 11” x 17” or A3 size paper.</li> +<li>Mount the printed pattern on a rigid backing.</li> +<li>Orient the camera device and the printed target as shown below:<br> +<img src="/compatibility/cts/images/camera-printed-target.png" alt="Camera +printed target" id="figure5" /> +<figcaption><strong>Figure 5.</strong> Camera printed target</figcaption> +</li> </ol> -<p><strong>Calibration process</strong> - Verify that the device and target are -placed as shown in the figure and the correct distances have been entered into -the setup dialog.The preview will display the image with a vertical line -overlaid onto it. This line should align with the center line of the target -pattern. The transparent grid can be used with the other vertical lines to -ensure that the optical axis is orthogonal to the target.</p> +</li> +<li>Set the target width: <ol> - <li>Select an image resolution to test from the selector at the bottom left. - <li>Tap the screen to take a photo and enter the calibration mode (described - below). - <li>Hit the back button and repeat for all supported image resolutions. +<li>Measure the distance (in centimeters) between the solid lines on the target +pattern to account for printing inaccuracies (~38 cm).</li> +<li>Start the calibration application.</li> +<li>Press the setup button and select <em>Marker distance</em>.</li> +<li>Measure and enter the distance to the target pattern (~100 cm).</li> +<li>Press the back button to return to the calibration preview.</li> +</ol> +</li> +<li>Verify the device and target are placed as shown in the figure and the +correct distances have been entered into the setup dialog. The preview will +display the image with a vertical line overlaid onto it; this line should align +with the center line of the target pattern. The transparent grid can be used +with the other vertical lines to ensure that the optical axis is orthogonal to +the target.</li> +<li>Run the calibration test: +<ol> +<li>Select an image resolution (using selector at the bottom left), then tap the +screen to take a photo. The test enters calibration mode and displays the photo +with two vertical lines overlaid onto the image.</li> +<li>Determine accuracy: +<ul> +<li>If the lines align with the vertical lines on the target pattern within a +few pixels, the reported field of view for the selected resoultion is accurate. +</li> +<li>If the lines do not align, the reported field of view is inaccurate. To +correct, adjust the slider at the bottom of the screen until the overlay aligns +with the target pattern as closely as possible. When the overlay and the target +pattern image are aligned, the displayed field of view will be a close +approximation to the correct value. The reported field of view should be +within +/-1 degree of the calibration value.</li> +</ul> +</li> +<li>Press back button and repeat the calibration test for all image resolutions +supported by the DUT.</li> </ol> -<p><strong>Calibration test (per resolution)</strong> In the calibration mode, the photo will be displayed with two vertical lines - overlaid onto the image.These lines should align with the vertical lines on the target pattern within a - few pixels. If they do not, then the reported field of view for that mode is - inaccurate (assuming the setup is correct).Adjust the slider at the bottom of the screen until the overlay aligns with the - target pattern as closely as possible. The displayed field of view will be a - close approximation to the correct value when the overlay and the target - pattern image are aligned. The reported field of view should be within +/-1 - degree of the calibration value.</p> -<h2 id=exporting_test_reports>Exporting test reports</h2> +</li> +</ol> + +<h2 id=exporting_test_reports>Exporting results</h2> +<p>After all tests complete, you can save the results as a report and download +to a computer. Report names are automatically time-stamped based on the DUT +system time.</p> + <ol> - <li> - After all tests are completed, tap the <strong>Save (disk)</strong> icon. - <br> - <img src="/compatibility/cts/images/verifier-save-icon.png" alt="CTS Verifier Save icon" id="figure6" /> - <p class="img-caption"> - <strong>Figure 6.</strong> CTS Verifier Save icon. <em>Note:</em> In - Android 7.0 and later, the preview feature is removed: - <img src="/compatibility/cts/images/verifier-preview-icon.png" width="24" height="24"> - </p> - </li> - <li> - A path to the saved report will be displayed in pop-up (e.g. - <code>/sdcard/verifierReports/ctsVerifierReport-date-time.zip</code>). - Record the path. - <br> - <img src="images/path-saved-report.png" alt="CTS Verifier path to saved report " id="figure7" /> - <p class="img-caption"> - <strong>Figure 7.</strong> CTS Verifier path to saved report - </p> - </li> - <li> - Connect the device via USB to a computer with the SDK installed. - </li> - <li> - From the computer’s SDK installation, run - <code>adb pull CTSVerifierReportPath</code> to download the report from the device. - <ul> - <li> - To download all reports run: - <pre class="devsite-terminal devsite-click-to-copy">adb pull /sdcard/verifierReports</pre> - For Android 6.0 and earlier, run: - <pre class="devsite-terminal devsite-click-to-copy">adb pull /mnt/sdcard/ctsVerifierReports/</pre> - </li> - <li> - The name of the reports are time-stamped based on the DUT’s system time. - </li> - <li> - To clear results after they have been selected, select - <strong>Menu > Clear</strong>. This will clear the Pass/Fail results. - </li> - </ul> - </li> +<li>Tap the <strong>Save (disk)</strong> icon.<br> +<img src="/compatibility/cts/images/verifier-save-icon.png" alt="CTS Verifier +Save icon" id="figure6" /> +<figcaption><strong>Figure 6.</strong> CTS Verifier Save icon.</figcaption> +<aside class="note"><strong>Note:</strong> Android 7.0 and higher do not include +the preview feature.</aside> +</li> +<li>Wait for the popup message to display the path to the saved report (e.g. +<code>/sdcard/verifierReports/ctsVerifierReport-date-time.zip</code>), then +record the path.<br> +<img src="images/path-saved-report.png" alt="CTS Verifier path to saved report" +id="figure7" /> +<figcaption><strong>Figure 7.</strong> CTS Verifier path to saved +report.</figcaption> +</li> +<li>Connect the DUT to the Linux computer.</li> +<li>From the Android SDK installation on the Linux computer, download reports +from the connected device using <code>adb pull CTSVerifierReportPath</code>. +<ul> +<li>For Android 7.x and later, download all reports using: +<pre class="devsite-terminal devsite-click-to-copy"> +adb pull /sdcard/verifierReports +</pre> +</li> +<li>For Android 6.0 and earlier, download all reports using: +<pre class="devsite-terminal devsite-click-to-copy"> +adb pull /mnt/sdcard/ctsVerifierReports/ +</pre> +</li> +</ul> +</li> +<li>To clear Pass/Fail results, select the results in the CTS Verifier app and +select <em>Menu > Clear</em>.</li> </ol> </body> diff --git a/en/devices/_translation.yaml b/en/devices/_translation.yaml new file mode 100644 index 00000000..64e32fca --- /dev/null +++ b/en/devices/_translation.yaml @@ -0,0 +1,10 @@ +enable_continuous_translation: True +title: Android Open Source Project Devices tab +description: Translations for SAC devices tab +language: +- zh-CN +cc: +- sac-doc-leads+translation@google.com +reviewer: +- daroberts +product: Android diff --git a/en/devices/architecture/kernel/config.html b/en/devices/architecture/kernel/config.html index 14d2ee17..afc36f82 100644 --- a/en/devices/architecture/kernel/config.html +++ b/en/devices/architecture/kernel/config.html @@ -22,27 +22,28 @@ --> - <p>Use the following configuration settings as a base for an Android kernel -configuration. Settings are organized into <code>android-base</code> and -<code>android-recommended</code> .cfg files: +configuration. Settings are organized into <code>android-base</code>, +<code>android-base-<arch></code>, and <code>android-recommended</code> +.cfg files:</p> <ul> <li><code>android-base</code>. These options enable core Android features and -should be enabled by all devices.</li> - +should be configured as specified by all devices.</li> +<li><code>android-base-<arch></code>. These options enable core Android +features and should be configured as specified by all devices of architecture +<arch>. Not all architectures have a corresponding file of +architecture-specific required options. If your architecture does not have a +file, it does not have any additional architecture-specific kernel configuration +requirements for Android.</li> <li><code>android-recommended</code>. These options enable advanced Android features and are optional for devices.</li> </ul> -<p>Both the android-base.cfg and android-recommended.cfg files are located in -the android-common kernel repo at -<a href="https://android.googlesource.com/kernel/common/">https://android.googlesource.com/kernel/common/</a>. -<p>In version 4.8 of the upstream Linux kernel, a new location (kernel/configs) -was designated for kernel configuration fragments. The android base and -recommended config fragments are located in that directory for branches based on -4.8 or later. For kernel branches based on releases prior to 4.8, the config -fragments are located in the android/ directory.</p> +<p>These configuration files are located in the +<code><a href="https://android.googlesource.com/kernel/configs/">kernel/configs</a></code> +repo. Use the set of configuration files that corresponds to the version of the +kernel you are using.</p> <p>For details on controls already undertaken to strengthen the kernel on your devices, see <a href="/security/overview/kernel-security.html">System @@ -51,15 +52,15 @@ and Kernel Security</a>. For details on required settings, see the Document (CDD)</a>.</p> <h2 id="generating">Generating kernel config</h2> -<p>For devices that have a minimalist defconfig, you can use the following to -enable options:</p> +<p>For devices that have a minimalist defconfig, you can use the +<code>merge_config.sh</code> script in the kernel tree to enable options:</p> <pre class="devsite-click-to-copy"> -ARCH=<em>arch</em> scripts/kconfig/merge_config.sh <em>path</em>/<em>device</em>_defconfig android/configs/android-base.cfg android/configs/android-recommended.cfg +ARCH=<arch> scripts/kconfig/merge_config.sh <...>/device_defconfig <...>/android-base.cfg <...>/android-base-<arch>.cfg <...>/android-recommended.cfg </pre> -<p>This generates a .config file you can use to save a new defconfig or -compile a new kernel with Android features enabled.</p> +<p>This generates a <code>.config</code> file you can use to save a new +defconfig or compile a new kernel with Android features enabled.</p> <h2 id="usb">Enabling USB host mode options</h2> diff --git a/en/devices/audio/data_formats.html b/en/devices/audio/data_formats.html index 382c9567..dbd993c4 100644 --- a/en/devices/audio/data_formats.html +++ b/en/devices/audio/data_formats.html @@ -162,7 +162,7 @@ The primary advantages of floating-point include: <ul> <li>Greater <a href="https://en.wikipedia.org/wiki/Headroom_(audio_signal_processing)">headroom</a> and <a href="https://en.wikipedia.org/wiki/Dynamic_range">dynamic range</a>; - floating-point arithmetic tolerates exceeeding nominal ranges + floating-point arithmetic tolerates exceeding nominal ranges during intermediate computation, and only clamps values at the end </li> <li>Support for special values such as infinities and NaN</li> diff --git a/en/security/_translation.yaml b/en/security/_translation.yaml new file mode 100644 index 00000000..66072b4f --- /dev/null +++ b/en/security/_translation.yaml @@ -0,0 +1,13 @@ +ignore_paths: +- /bulletin/... +enable_continuous_translation: True +title: Android Open Source Project Security tab +description: Translations for SAC Security tab +language: +- zh-CN +cc: +- daroberts@google.com +- sac-doc-leads+translation@google.com +reviewer: +- daroberts +product: Android diff --git a/en/security/authentication/fingerprint-hal.html b/en/security/authentication/fingerprint-hal.html index 1d27f89c..02ee3e4b 100644 --- a/en/security/authentication/fingerprint-hal.html +++ b/en/security/authentication/fingerprint-hal.html @@ -21,155 +21,148 @@ limitations under the License. --> +<p>On devices with a fingerprint sensor, users can enroll one or more +fingerprints and use those fingerprints to unlock the device and perform +other tasks. Android uses the Fingerprint Hardware Abstraction Layer (HAL) to +connect to a vendor-specific library and fingerprint hardware, e.g. a +fingerprint sensor.</p> +<p>To implement the Fingerprint HAL, you must +<a href="#fingerprint_hal_functions">implement the major functions</a> of +<code>/hardware/libhardware/include/hardware/fingerprint.h</code> in a +vendor-specific library.</p> -<h2 id=overview>Overview</h2> +<h2 id=fingerprint_matching>Fingerprint matching</h2> -<p>If a device has a fingerprint sensor, a user can enroll one or more -fingerprints and then use their fingerprints to unlock the device and perform -other tasks.</p> - -<p>Android uses the Fingerprint Hardware Abstraction Layer (HAL) to connect to a -vendor-specific library and fingerprint hardware, e.g. a fingerprint sensor.</p> - -<p>To implement the Fingerprint HAL, you must implement -<a href="#major_functions_in_the_fingerprint_hal">functions</a> -in <code>fingerprint.h</code> (<code>/hardware/libhardware/include/hardware/fingerprint.h</code>) -in a vendor-specific library; please see the comments in -the <a href="https://android.googlesource.com/platform/hardware/libhardware/+/master/include/hardware/fingerprint.h"><code>fingerprint.h</code></a> file.</p> - -<h3 id=fingerprint_matching_flow>Fingerprint matching flow</h3> - -<p>The following is a high-level flow for fingerprint matching. This flow assumes -that a fingerprint already has been enrolled on the device, i.e. the -vendor-specific library already has enrolled a template for the fingerprint. -Also see <a href="index.html">Authentication</a>.</p> - -<p>The fingerprint sensor of a device generally is idle. But in response to a call -to the <code>authenticate</code> or <code>enroll</code> function, the fingerprint -sensor listens for a touch (and perhaps the screen -wakes up when a user touches the fingerprint sensor).</p> +<p>The fingerprint sensor of a device is generally idle. However, in response to +a call to the <code>authenticate</code> or <code>enroll</code> function, the +fingerprint sensor listens for a touch (the screen might also wake when a user +touches the fingerprint sensor). The high-level flow of fingerprint matching +includes the following steps:</p> <ol> - <li>The user places a finger on the fingerprint sensor, and the vendor-specific -library determines if there is a match based on the current set of enrolled -templates. - <li>The result of step 1 is passed to the Fingerprint HAL, which notifies -<code>fingerprintd</code> (the Fingerprint daemon) of a fingerprint authentication. + <li>User places a finger on the fingerprint sensor.</li> + <li>The vendor-specific library determines if there is a fingerprint match + in the current set of enrolled fingerprint templates.</li> + <li>Matching results are passed to the Fingerprint HAL, which notifies + <code>fingerprintd</code> (the Fingerprint daemon) of a fingerprint + authentication (or non-authentication).</li> </ol> -<p>Note that as more templates are stored on a single device, the time needed for -matching is increased.</p> +<p>This flow assumes a fingerprint has already been enrolled on the device, i.e. +the vendor-specific library has enrolled a template for the fingerprint (for +details, see <a href="index.html">Authentication</a>).</p> + +<aside class="note"><strong>Note:</strong> The more fingerprint templates stored +on a device, the more time required for fingerprint matching.</aside> <h2 id=architecture>Architecture</h2> -<p>The <strong>Fingerprint HAL</strong> interacts with the following components:</p> +<p>The Fingerprint HAL interacts with the following components:</p> +<img src="../images/fingerprint-data-flow.png" alt="Data flow for fingerprint +authentication" id="figure1" /> +<figcaption><strong>Figure 1.</strong> High-level data flow for fingerprint +authentication.</figcaption> <ul> - <li><strong>FingerprintManager API</strong>. Interacts directly with an app in an app process. - <ul> - <li>Each app has an instance of FingerprintManager. - <li>FingerprintManager is a wrapper that communicates with FingerprintService. - </ul> - <li><strong>FingerprintService</strong>. A singleton service that operates in the system - process, which handles -communication with <code>fingerprintd</code>. - <li><strong>fingerprintd (Fingerprint daemon)</strong>. A C/C++ implementation of the - binder interface from FingerprintService. The -<code>fingerprintd</code> daemon operates in its own process and wraps the Fingerprint HAL -vendor-specific library. - <li><strong>Fingerprint HAL vendor-specific library</strong>. A hardware vendor's - implementation of the Fingerprint HAL. The -vendor-specific library communicates with the device-specific hardware. - <li><strong>Keystore API and Keymaster</strong>. These components provide hardware-backed cryptography - for secure key storage - in a Trusted Execution Environment (TEE). + <li><code>FingerprintManager</code> API. Interacts directly with an app in + an app process. Each app has an instance of <code>FingerprintManager</code>, + a wrapper that communicates with <code>FingerprintService</code>.</li> + <li><code>FingerprintService</code>. Singleton service that operates in + the system process, which handles communication with + <code>fingerprintd</code>. + <li><code>fingerprintd</code>. C/C++ implementation of the binder interface + from FingerprintService. The <code>fingerprintd</code> daemon operates in its + own process and wraps the Fingerprint HAL vendor-specific library.</li> + <li><strong>Fingerprint HAL vendor-specific library</strong>. Hardware + vendor's implementation of the Fingerprint HAL. The vendor-specific library + communicates with the device-specific hardware.</li> + <li><strong>Keystore API and Keymaster</strong>. Components that provide + hardware-backed cryptography for secure key storage in a Trusted Execution + Environment (TEE). + </li> </ul> -<p>As shown in the following diagram, a vendor-specific HAL implementation needs -to use the communication protocol required by a TEE.</p> - -<img src="../images/fingerprint-data-flow.png" alt="Data flow for fingerprint authentication" id="figure1" /> +<p>A vendor-specific HAL implementation must use the communication protocol +required by a TEE. Thus, raw images and processed fingerprint features must not +be passed in untrusted memory. All such biometric data needs to be secured +within sensor hardware or trusted memory. (Memory inside the TEE is considered +trusted; memory outside the TEE is considered untrusted.) Rooting must +<strong>not</strong> compromise biometric data.</p> -<p class="img-caption"><strong>Figure 1.</strong> High-level data flow for fingerprint authentication</p> +<p><code>fingerprintd</code> makes calls through the Fingerprint HAL to the +vendor-specific library to enroll fingerprints and perform other operations:</p> -<p>Thus, raw images and processed fingerprint features must not be passed in -untrusted memory. All such biometric data needs to be secured within sensor -hardware or trusted memory. (Memory inside the TEE is considered as trusted -memory; memory outside the TEE is considered untrusted.)</p> +<img src="../images/fingerprint-daemon.png" alt="Interaction with fingerprintd" +id="figure2" /> +<figcaption><strong>Figure 2.</strong> Interaction of the fingerprint daemon +with the fingerprint vendor-specific library.</p> -<p>Rooting must not compromise biometric data.</p> - -<p>As shown in the following diagram, <code>fingerprintd</code> makes calls through the -Fingerprint HAL to the vendor-specific library to enroll fingerprints and -perform other operations.</p> - -<img src="../images/fingerprint-daemon.png" alt="Interaction with fingerprintd" id="figure2" /> -<p class="img-caption"><strong>Figure 2.</strong> Interaction of the -fingerprint daemon (<code>fingerprintd</code>) with the fingerprint vendor-specific library</p> - -<h2 id=fingerprint_implementation_guidelines>Fingerprint implementation guidelines</h2> - -<p>The guidelines in this section are intended to ensure the following:</p> - -<ul> - <li>Fingerprint data is not leaked - <li>Fingerprint data is removed when a user is removed from a device -</ul> +<h2 id=implementation_guidelines>Implementation guidelines</h2> -<p>Here are the guidelines:</p> +<p>The following Fingerprint HAL guidelines are designed to ensure that +fingerprint data is <strong>not leaked</strong> and is <strong>removed</strong> +when a user is removed from a device:</p> <ol> - <li>Raw fingerprint data or derivatives (e.g. templates) must never be accessible -from outside the sensor driver or Trusted Execution Environment (TEE). Hardware -access must be limited to the TEE, if the hardware supports it, and must be protected by -an SELinux policy. That is, the Serial Peripheral Interface (SPI) channel must -be accessible only to the TEE, and there must be an explicit SELinux policy on -all device files. - <li>Fingerprint acquisition, enrollment and recognition must occur inside the TEE. + <li>Raw fingerprint data or derivatives (e.g. templates) must never be + accessible from outside the sensor driver or TEE. If the hardware supports it, + hardware access must be limited to the TEE and protected by an SELinux policy. + The Serial Peripheral Interface (SPI) channel must be accessible only to the + TEE and there must be an explicit SELinux policy on all device files.</li> + <li>Fingerprint acquisition, enrollment, and recognition must occur inside the + TEE.</li> <li>Only the encrypted form of the fingerprint data can be stored on the file -system, even if the file system itself is encrypted. - <li>Fingerprint templates must be signed with a private, device-specific key, for -example with AES, with at least the absolute file-system path, group and finger -ID such that template files are inoperable on another device or for anyone -other than the user that enrolled them on the same device. For example, copying -the fingerprint data from a different user on the same device, or from another -device, must not work. + system, even if the file system itself is encrypted.</li> + <li>Fingerprint templates must be signed with a private, device-specific key. + For Advanced Encryption Standard (AES), at a minimum a template must be signed + with the absolute file-system path, group, and finger ID such that template + files are inoperable on another device or for anyone other than the user that + enrolled them on the same device. For example, copying fingerprint data from a + different user on the same device or from another device must not work.</li> <li>Implementations must either use the file system path provided by the - <code>set_active_group()</code> function or provide a way to erase all user template data when the user -is removed. It is strongly recommended that fingerprint template files -be stored as encrypted in the path provided. If this is infeasible due to TEE -storage requirements, then the implementer must add hooks to ensure removal of -the data when the user is removed. + <code>set_active_group()</code> function or provide a way to erase all user + template data when the user is removed. It is strongly recommended that + fingerprint template files be stored as encrypted in the path provided. If + this is infeasible due to TEE storage requirements, the implementer must add + hooks to ensure removal of the data when the user is removed.</li> </ol> -<h2 id=major_functions_in_the_fingerprint_hal>Major functions in the Fingerprint HAL</h2> +<h2 id=fingerprint_hal_functions>Fingerprint HAL functions</h2> -<p>Below are the major functions in the <code>/hardware/libhardware/include/hardware/fingerprint.h</code> file; see the detailed descriptions in that -file.</p> +<p>The Fingerprint HAL contains the following major functions in +<code>/hardware/libhardware/include/hardware/fingerprint.h</code>:</p> <ul> - <li><strong>enroll.</strong> Switches the HAL state machine to start the collection and storage of a -fingerprint template. As soon as enrollment is complete, or after a timeout, -the HAL state machine is returned to the idle state. - <li><strong>pre_enroll.</strong> Generates a unique token to indicate the start of a fingerprint enrollment. -Provides a token to the <code>enroll</code> function to ensure there was prior authentication, e.g. using a password. The -token is wrapped and, for example, HMAC'd, once the device credential is -confirmed, to prevent tampering. The token must be checked during enrollment to -verify that the token is still valid. - <li><strong>get_authenticator_id.</strong> Returns a token associated with the current fingerprint set. - <li><strong>cancel.</strong> Cancels any pending enroll or authenticate operations. The HAL state machine -is returned to the idle state. - <li><strong>enumerate.</strong> Synchronous call for enumerating all known fingerprint templates. - <li><strong>remove.</strong> Deletes a fingerprint template. - <li><strong>set_active_group.</strong> Restricts a HAL operation to a set of fingerprints that belong to a specified -group (identified by a group identifier, or GID). - <li><strong>authenticate.</strong> Authenticates a fingerprint-related operation (identified by an operation ID). - <li><strong>set_notify.</strong> Registers a user function that will get notifications from the HAL. If the HAL -state machine is in a busy state, the function is blocked until the HAL leaves -the busy state. +<li><code>enroll</code>. Switches the HAL state machine to start the + collection and storage of a fingerprint template. When enrollment is complete, + or after a timeout, the HAL state machine returns to the idle state.</li> + <li><code>pre_enroll</code>. Generates a unique token to indicate the + start of a fingerprint enrollment. Provides a token to the <code>enroll</code> + function to ensure there was prior authentication, e.g. using a password. To + prevent tampering, the token is wrapped (e.g. HMAC'd) after the device + credential is confirmed. The token must be checked during enrollment to verify + the token is still valid.</li> + <li><code>get_authenticator_id</code>. Returns a token associated with the + current fingerprint set.</li> + <li><code>cancel</code>. Cancels pending enroll or authenticate operations. + The HAL state machine is returned to the idle state.</li> + <li><code>enumerate</code>. Synchronous call for enumerating all known + fingerprint templates.</li> + <li><code>remove</code>. Deletes a fingerprint template.</li> + <li><code>set_active_group</code>. Restricts a HAL operation to a set of + fingerprints that belong to a specified group, identified by a group + identifier (GID).</li> + <li><code>authenticate</code>. Authenticates a fingerprint-related operation + (identified by an operation ID).</li> + <li><code>set_notify</code>. Registers a user function that receives + notifications from the HAL. If the HAL state machine is in a busy state, the + function is blocked until the HAL leaves the busy state.</li> </ul> +<p>For details on these functions, refer to the comments in +<a href="https://android.googlesource.com/platform/hardware/libhardware/+/master/include/hardware/fingerprint.h" class="external"><code>fingerprint.h</code></a>. +</p> </body> </html> diff --git a/en/security/authentication/gatekeeper.html b/en/security/authentication/gatekeeper.html index 692212c5..a27882bd 100644 --- a/en/security/authentication/gatekeeper.html +++ b/en/security/authentication/gatekeeper.html @@ -21,10 +21,6 @@ limitations under the License. --> - - -<h2 id=overview>Overview</h2> - <p>The Gatekeeper subsystem performs device pattern/password authentication in a Trusted Execution Environment (TEE). Gatekeeper enrolls and verifies passwords via an HMAC with a hardware-backed secret key. Additionally, Gatekeeper @@ -33,8 +29,8 @@ requests based on a given timeout and a given number of consecutive failed attempts.</p> <p>When users verify their passwords, Gatekeeper uses the TEE-derived shared -secret to sign an authentication attestation to -send to the <a href="/security/keystore/index.html">hardware-backed Keystore</a>. That is, a +secret to sign an authentication attestation to send to the +<a href="/security/keystore/index.html">hardware-backed Keystore</a>. That is, a Gatekeeper attestation notifies Keystore that authentication-bound keys (for example, keys that apps have created) can be released for use by apps.</p> @@ -43,156 +39,146 @@ example, keys that apps have created) can be released for use by apps.</p> <p>Gatekeeper involves three main components:</p> <ul> - <li><strong>gatekeeperd (Gatekeeper daemon)</strong>. - A C++ binder service containing platform-independent logic and corresponding -to the <code>GateKeeperService</code> Java interface. - <li><strong>Gatekeeper Hardware Abstraction Layer (HAL)</strong>. - The HAL interface in <code>hardware/libhardware/include/hardware/gatekeeper.h</code>, - and the implementing module. - <li><strong>Gatekeeper (TEE)</strong>. - The TEE counterpart of <code>gatekeeperd</code>. A TEE-based implementation of Gatekeeper. + <li><code>gatekeeperd</code> (Gatekeeper daemon). A C++ binder service + containing platform-independent logic and corresponding to the + <code>GateKeeperService</code> Java interface.</li> + <li><strong>Gatekeeper Hardware Abstraction Layer (HAL)</strong>. The HAL + interface in <code>hardware/libhardware/include/hardware/gatekeeper.h</code>, + and the implementing module.</li> + <li><strong>Gatekeeper (TEE)</strong>. The TEE counterpart of + <code>gatekeeperd</code>. A TEE-based implementation of Gatekeeper.</li> </ul> -<p>To implement Gatekeeper:</p> +<p>Gatekeeper requires implementation of the +<a href="#hal_implementation">Gatekeeper HAL</a> (specifically the functions in +<code>hardware/libhardware/include/hardware/gatekeeper.h</code>) and the +<a href="#trusty_and_other_implementations">TEE-specific Gatekeeper +component</a> (based in part on the +<code>system/gatekeeper/include/gatekeeper/gatekeeper.h</code> header file that +includes pure virtual functions for creating/accessing keys and computing +signatures). -<ul> - <li>Implement the Gatekeeper HAL, specifically the functions in <code>gatekeeper.h</code> - (<code>hardware/libhardware/include/hardware/gatekeeper.h</code>). - See <a href="#hal_implementation">HAL Implementation</a>. - <li>Implement the TEE-specific Gatekeeper component, in part based on the following -header file: <code>system/gatekeeper/include/gatekeeper/gatekeeper.h</code>. This -header file includes pure virtual functions for creating and accessing -keys, as well as for computing signatures. -See <a href="#trusty_and_other_implementations">Trusty and other implementations</a>. -</ul> - -<p>As shown in the following diagram, the <code>LockSettingsService</code> makes a request (via -Binder) that reaches the <code>gatekeeperd</code> daemon in the Android OS. -The <code>gatekeeperd</code> -daemon makes a request that reaches its counterpart (Gatekeeper) in the TEE.</p> +<p>The <code>LockSettingsService</code> makes a request (via Binder) that +reaches the <code>gatekeeperd</code> daemon in the Android OS. The +<code>gatekeeperd</code> daemon then makes a request that reaches its +counterpart (Gatekeeper) in the TEE:</p> <img src="../images/gatekeeper-flow.png" alt="Gatekeeper flow" id="figure1" /> -<p class="img-caption"><strong>Figure 1.</strong> High-level data flow for authentication by GateKeeper</p> +<figcaption><strong>Figure 1.</strong> High-level data flow for authentication +by GateKeeper</figcaption> -<p>The <code>gatekeeperd</code> daemon gives the Android framework APIs access to the HAL, and -participates in reporting device <a href="index.html">authentications</a> to Keystore. -The <code>gatekeeperd</code> daemon runs in its own process, separate from the system -server.</p> +<p>The <code>gatekeeperd</code> daemon gives the Android framework APIs access +to the HAL, and participates in reporting device +<a href="/security/authentication/index.html">authentications</a> to Keystore. +The <code>gatekeeperd</code> daemon runs in its own process and is separate from +the system server.</p> -<h2 id=hal_implementation>HAL Implementation</h2> +<h2 id=hal_implementation>HAL implementation</h2> <p>The <code>gatekeeperd</code> daemon uses the HAL to interact -with the <code>gatekeeperd</code> daemon's TEE -counterpart for password authentication. The HAL implementation must be able to -sign (enroll) and verify blobs. All implementations are expected to adhere to -the standard format for the authentication token (AuthToken) generated on each -successful password verification. The contents and semantics of the AuthToken -are described in <a href="index.html">Authentication</a>.</p> - -<p>Specifically, an implementation of the <code>gatekeeper.h</code> header file (in the -<code>hardware/libhardware/include/hardware</code> folder) needs to implement the -<code>enroll</code> and <code>verify</code> functions.</p> +with the <code>gatekeeperd</code> daemon's TEE counterpart for +password authentication. The HAL implementation must be able to sign (enroll) +and verify blobs. All implementations are expected to adhere to the standard +format for the authentication token (AuthToken) generated on each successful +password verification. For details on the content and semantic of the AuthToken, +see <a href="/security/authentication/index.html#authtoken_format">AuthToken +format</a>.</p> + +<p>Implementations of the +<code>hardware/libhardware/include/hardware/gatekeeper.h</code> header file +must implement the <code>enroll</code> and <code>verify</code> functions:</p> -<p>The <code>enroll</code> function takes a password blob, signs it, and returns the signature -as a handle. The returned blob (from a call to <code>enroll</code>) must have the structure -shown in <code>system/gatekeeper/include/gatekeeper/password_handle.h</code>.</p> - -<p>The <code>verify</code> function needs to compare the signature produced -by the provided password and -ensure that it matches the enrolled password handle.</p> +<ul> +<li>The <code>enroll</code> function takes a password blob, signs it, and +returns the signature as a handle. The returned blob (from a call to +<code>enroll</code>) must have the structure shown in +<code>system/gatekeeper/include/gatekeeper/password_handle.h</code>.</li> +<li>The <code>verify</code> function must compare the signature produced by the +provided password and ensure it matches the enrolled password handle.</li> +</ul> -<p>The key used to enroll and verify must never change, and should be re-derivable -at every device boot.</p> +<p>The key used to enroll and verify must never change, and should be +re-derivable at every device boot.</p> <h2 id=trusty_and_other_implementations>Trusty and other implementations</h2> <p>The <a href="/security/trusty/index.html">Trusty</a> operating system is -Google's open source trusted OS for TEE -environments. Trusty contains an approved implementation of GateKeeper. However, -<strong>any TEE OS</strong> can be used for the implementation of Gatekeeper. -The TEE <strong>must</strong> have access to a hardware-backed key as well as a secure, -monotonic clock <strong>that ticks in suspend</strong>.</p> +Google's open source trusted OS for TEE environments and contains an approved +implementation of GateKeeper. However, you can use <strong>any TEE OS</strong> +to implement Gatekeeper as long as the TEE has access to a hardware-backed key +and a secure, monotonic clock <strong>that ticks in suspend</strong>.</p> <p>Trusty uses an internal IPC system to communicate a shared secret directly -between Keymaster and the Trusty implementation of Gatekeeper ("Trusty -Gatekeeper"). This shared secret is used for signing AuthTokens that will be -sent to Keystore, providing attestations of password verification. Trusty -Gatekeeper requests the key from Keymaster for each use and does not persist -or cache the value. Implementations are free to share this secret in any way -that does not compromise security.</p> - -<p>The HMAC key, used to enroll and verify passwords, is derived and kept solely +between Keymaster and the Trusty implementation of Gatekeeper (the <em>Trusty +Gatekeeper</em>). This shared secret is used for signing AuthTokens sent to +Keystore to provide attestations of password verification. Trusty Gatekeeper +requests the key from Keymaster for each use and does not persist or cache the +value. Implementations are free to share this secret in any way that does not +compromise security.</p> + +<p>The HMAC key used to enroll and verify passwords is derived and kept solely in GateKeeper.</p> -<p>The Android tree provides a generic C++ implementation of GateKeeper, requiring +<p>Android provides a generic C++ implementation of GateKeeper that requires only the addition of device-specific routines to be complete. To implement a -TEE Gatekeeper with device-specific code for your TEE, please refer to the -functions and comments in the following file:</p> -<pre class="devsite-click-to-copy"> -system/gatekeeper/include/gatekeeper/gatekeeper.h -</pre> - -<p>For the TEE GateKeeper, the primary responsibilities of a compliant -implementation are:</p> +TEE Gatekeeper with device-specific code for your TEE, refer to the functions +and comments in <code>system/gatekeeper/include/gatekeeper/gatekeeper.h</code>. +For the TEE GateKeeper, the primary responsibilities of a compliant +implementation include:</p> <ul> - <li>Adherence to the Gatekeeper HAL - <li>Returned AuthTokens must be formatted according to the AuthToken specification -(described in <a href="index.html">Authentication</a>) - <li>The TEE Gatekeeper must be able to share an HMAC key with Keymaster, either by -requesting the key through a TEE IPC on demand or maintaining a valid cache of -the value at all times + <li>Adherence to the Gatekeeper HAL.</li> + <li>Returned AuthTokens must be formatted according to the AuthToken + specification (described in + <a href="/security/authentication/index.html">Authentication</a>).</li> + <li>The TEE Gatekeeper must be able to share an HMAC key with Keymaster, + either by requesting the key through a TEE IPC on demand or maintaining a + valid cache of the value at all times.</li> </ul> -<h2 id=user_sids>User SIDs</h2> +<h2 id=user_sids>User Secure IDs (SIDs)</h2> -<p>A User Secure ID (User SID) is the TEE representation of a user. -The User SID has no strong connection to an Android user ID.</p> +<p>A User SID is the TEE representation of a user (with no strong connection to +an Android user ID). The SID is generated with a cryptographic pseudorandom +number generator (PRNG) whenever a user enrolls a new password without providing +a previous one. This is known as an <em>untrusted</em> re-enroll and is not +allowed by the Android framework in normal circumstances. A <em>trusted</em> +re-enroll occurs when a user provides a valid, previous password; in this case, +the User SID is migrated to the new password handle, conserving the keys that +were bound to it.</p> -<p>A User SID is generated with a cryptographic -PRNG whenever a user enrolls a new password without providing a previous one. -This is known as an "untrusted" re-enroll. -A "trusted" re-enroll occurs when a user provides a valid, previous password. -In this case, the User SID is migrated to the new password handle, -conserving the keys that were bound to it. -The Android framework does not allow for an "untrusted" re-enroll under regular circumstances.</p> - -<p>The User SID is HMAC'ed along with the password in the password handle when the -password is enrolled.</p> +<p>The User SID is HMAC'ed along with the password in the password handle when +the password is enrolled.</p> <p>User SIDs are written into the AuthToken returned by the <code>verify</code> -function and associated to all authentication-bound Keystore keys. For -information about the AuthToken format and Keystore, see -<a href="index.html">Authentication</a>. -Since an untrusted call to the <code>enroll</code> function -will change the User SID, the call will render the keys bound to that password useless.</p> - -<p>Attackers can change the password for the device if they control the Android -OS, but they will destroy root-protected, sensitive keys in the process.</p> +function and associated to all authentication-bound Keystore keys (for details +on the AuthToken format and Keystore, see +<a href="/security/authentication/index.html">Authentication</a>). As an +untrusted call to the <code>enroll</code> function will change the User SID, the +call will render the keys bound to that password useless. Attackers can change +the password for the device if they control the Android OS, but they will +destroy root-protected, sensitive keys in the process.</p> <h2 id=request_throttling>Request throttling</h2> <p>GateKeeper must be able to securely throttle brute-force attempts on a user -credential. As shown in the <code>gatekeeper.h</code> -file (in <code>hardware/libhardware/include/hardware</code>), -the HAL provides for returning a timeout in milliseconds. The timeout -informs the client not to call GateKeeper again until after the timeout has -elapsed. GateKeeper should not service requests if there is a pending timeout.</p> +credential. As shown in +<code>hardware/libhardware/include/hardware/gatekeeper.h</code>, the HAL +provides for returning a timeout in milliseconds. The timeout informs the client +not to call GateKeeper again until after the timeout has elapsed; GateKeeper +should not service requests if there is a pending timeout.</p> <p>GateKeeper must write a failure counter before verifying a user password. If the password verification succeeds, the failure counter should be cleared. This prevents attacks that prevent throttling by disabling the embedded MMC (eMMC) -after issuing a <code>verify</code> call. The <code>enroll</code> function also verifies -the user password (if provided) and so must be throttled in the same way.</p> +after issuing a <code>verify</code> call. The <code>enroll</code> function also +verifies the user password (if provided) and must be throttled in the same way. +</p> <p>If supported by the device, it is highly recommended that the failure counter be written to secure storage. If the device does not support -file-based encryption, or if secure storage is too slow, implementations may -use RPMB directly.</p> - - - - +file-based encryption, or if secure storage is too slow, implementations may use +Replay Protected Memory Block (RPMB) directly.</p> </body> </html> diff --git a/en/security/authentication/index.html b/en/security/authentication/index.html index 27eed8a2..e1436b8f 100644 --- a/en/security/authentication/index.html +++ b/en/security/authentication/index.html @@ -21,233 +21,192 @@ limitations under the License. --> - - -<h2 id=overview>Overview</h2> - -<p>Android 6.0 introduces the concept of user-authentication-gated cryptographic -keys. To achieve this, two key components need to work together. -First is the cryptographic key storage and service provider, which stores -cryptographic keys and provides standard crypto routines on top of them. Second -is any number of user authenticators that may attest to the user's presence -and/or successful authentication.</p> - -<p>The cryptographic key storage in Android is provided by the keystore service and Keymaster. -(Also see information about -the <a href="https://developer.android.com/training/articles/keystore.html">Android Keystore system</a>, -at the framework level, which is backed by the keystore service.) For Android 6.0, -the two supported authentication components are Gatekeeper (for -PIN/pattern/password authentication) and Fingerprint (for fingerprint -authentication). These components communicate their authentication -state with the keystore service via an authenticated channel.</p> +<p>Android uses the concept of user-authentication-gated cryptographic keys that +requires the following components:</p> <ul> - <li>The <strong><a href="/security/keystore/index.html">hardware-backed Keystore</a>.</strong> - Cryptographic services, including hardware-backed cryptography for key storage, - which might include a Trusted Execution Environment (TEE).</li> - <li><strong><a href="gatekeeper.html">Gatekeeper</a>.</strong> Components for PIN, pattern, and password authentication.</li> - <li><strong><a href="fingerprint-hal.html">Fingerprint</a>.</strong> Components for fingerprint authentication.</li> +<li><strong>Cryptographic key storage and service provider</strong>. Stores +cryptographic keys and provides standard crypto routines on top of those keys. +Android supports a <a href="/security/keystore/index.html">hardware-backed +Keystore</a> and Keymaster for cryptographic services, including hardware-backed +cryptography for key storage that might include a Trusted Execution Environment +(TEE).</li> +<li><strong>User authenticators</strong>. Attest to the user's presence and/or +successful authentication. Android supports +<a href="gatekeeper.html">Gatekeeper</a> for PIN/pattern/password authentication +and <a href="fingerprint-hal.html">Fingerprint</a> for fingerprint +authentication. These components communicate their authentication state with the +keystore service via an authenticated channel. (The +<a href="https://developer.android.com/training/articles/keystore.html" class="external">Android +Keystore system</a> at the framework level is also backed by the keystore +service.)</li> </ul> -<h2 id=architecture>Architecture</h2> - -<p>The Gatekeeper and Fingerprint components work with Keystore and other -components to support the use of hardware-backed <a href="#authentication_token_format">authentication tokens</a> (referred to below as "AuthTokens").</p> - -<h3 id=enrollment>Enrollment</h3> - -<p>Upon first boot of the device after a factory reset, all authenticators are prepared to receive -credential enrollments from the user.</p> - -<p>The user must initially enroll a PIN/pattern/password with Gatekeeper. This -initial enrollment creates a randomly generated, 64-bit User SID (user secure -identifier, described further below) that serves as an identifier for the user -and as a binding token for the user's cryptographic material. -This User SID is cryptographically bound to the user's password. -As detailed below, successful authentications to Gatekeeper result in AuthTokens that contain the User SID -for that password.</p> - -<p>When a user wants to change their credential, they must present their existing -credential. If the existing credential is verified successfully, the User SID -associated with the existing credential is transferred to the new credential. -This allows the user to keep accessing their keys after changing their -credential. If a user does not present their existing credential, the new one -is enrolled with a fully random User SID. The user can access the device but -keys created under the old User SID are permanently lost. This is known as an -"untrusted enroll."</p> - -<p>Note that an untrusted enroll will not be allowed under normal circumstances by -the Android framework, so most users won't ever see this functionality. -However, forcible password resets either by a device administrator or an -attacker may cause this to occur.</p> - -<h3 id=authentication>Authentication</h3> - -<p>Now that the user has set up a credential and received a User SID, they may -proceed to start authentication.</p> - -<p>In the diagram below, authentication starts when a user provides a PIN, +<p>Gatekeeper and Fingerprint components work with Keystore and other components +to support the use of hardware-backed <a href="#authtoken_format">authentication +tokens</a> (AuthTokens).</p> + +<h2 id=enrollment>Enrollment</h2> + +<p>On first boot of the device after a factory reset, all authenticators are +prepared to receive credential enrollments from the user. A user must initially +enroll a PIN/pattern/password with Gatekeeper. This initial enrollment creates a +randomly generated, 64-bit User SID (user secure identifier) that serves as an +identifier for the user and as a binding token for the user's cryptographic +material. This User SID is cryptographically bound to the user's password; +successful authentications to Gatekeeper result in AuthTokens that contain the +User SID for that password.</p> + +<p>A user who wants to change a credential must present an existing credential. +If an existing credential is verified successfully, the User SID associated with +the existing credential is transferred to the new credential, enabling the user +to keep accessing keys after changing a credential. If a user does not present +an existing credential, the new credential is enrolled with a fully random User +SID. The user can access the device, but keys created under the old User SID are +permanently lost. This is known as an <em>untrusted enroll</em>.</p> + +<p>Under normal circumstances, the Android framework does not allow an untrusted +enroll, so most users won't ever see this functionality. However, forcible +password resets, either by a device administrator or an attacker, may +cause this to occur.</p> + +<h2 id=authentication>Authentication</h2> + +<p>After a user has set up a credential and received a User SID, they may +proceed to start authentication, which begins when a user provides a PIN, pattern, password, or fingerprint. All TEE components share a secret key which they use to authenticate each other's messages.</p> -<img src="../images/authentication-flow.png" alt="Authentication flow" id="figure1" /> -<p class="img-caption"><strong>Figure 1.</strong> Authentication flow</p> - -<p>The numbers in the following steps correspond to the numbers in the diagram -above, and include reference to both the Android OS and the TEE OS: </p> +<img src="../images/authentication-flow.png" alt="Authentication flow" +id="figure1" /> +<figcaption><strong>Figure 1.</strong> Authentication flow.</figcaption> <ol> <li>A user provides a PIN, pattern, password, or fingerprint. The -<code>LockSettingsService</code> or <code>FingerprintService</code> make a request via Binder to the -Gatekeeperd or fingerprintd daemon in the Android OS. Note that fingerprint -authentication occurs asynchronously after the fingerprint request is sent. - <li>This step involves <strong>either</strong> Gatekeeperd (option 1 below) - <strong>or</strong> fingerprintd (option 2 below), - depending on whether a pin/pattern/password, or fingerprint, is provided. - <ul> - <li>The Gatekeeperd daemon sends a pin, pattern, or password hash (received in step -1) to its counterpart (Gatekeeper) in the TEE. If authentication in the TEE is -successful, Gatekeeper in the TEE sends an AuthToken containing the -corresponding User SID, signed with the AuthToken HMAC key, to its -counterpart in the Android OS. - <li>Alternatively, the fingerprintd daemon, which listens for fingerprint events, -sends the data (received in step 1) to its counterpart (Fingerprint) in the -TEE. If authentication in the TEE is successful, Fingerprint in the TEE sends -an AuthToken, signed with the AuthToken HMAC key, to its counterpart in the Android OS. + <code>LockSettingsService</code> or <code>FingerprintService</code> makes a + request via Binder to appropriate daemon (<code>gatekeeperd</code> or + <code>fingerprintd</code>); fingerprint authentication occurs asynchronously + after the fingerprint request is sent.</li> + <li>The daemon sends data to its counterpart, which generates an AuthToken: + <ul> + <li>For PIN/pattern/password authentication, <code>gatekeeperd</code> sends + the PIN, pattern, or password hash to Gatekeeper in the TEE. If + authentication in the TEE is successful, Gatekeeper in the TEE sends an + AuthToken containing the corresponding User SID (signed with the AuthToken + HMAC key) to its counterpart in the Android OS. + <li>For fingerprint authentication, <code>fingerprintd</code> listens for + fingerprint events and sends the data to Fingerprint in the TEE. If + authentication in the TEE is successful, Fingerprint in the TEE sends an + AuthToken (signed with the AuthToken HMAC key) to its counterpart in the + Android OS.</li> </ul> - <li>The Gatekeeperd or fingerprintd daemon receives a signed AuthToken and passes -the AuthToken to the keystore service via an extension to -the keystore service's Binder interface. Additionally, Gatekeeperd notifies the keystore service when -the device is re-locked and when the device password changes. - <li>The keystore service passes to Keymaster the AuthTokens received from Gatekeeperd and -fingerprintd, verifying the AuthTokens with the key shared with the Gatekeeper -and Fingerprint trustlets. Keymaster trusts the timestamp in the token as the -last authentication time and bases a key release decision (to allow an app to -use the key) on the timestamp. + </li> + <li>The daemon receives a signed AuthToken and passes it to the keystore + service via an extension to the keystore service's Binder interface. + (<code>gatekeeperd</code> also notifies the keystore service when the device + is re-locked and when the device password changes.) + <li>The keystore service passes the AuthTokens to Keymaster, verifying them + using the key shared with the Gatekeeper and Fingerprint trustlets. Keymaster + trusts the timestamp in the token as the last authentication time and bases a + key release decision (to allow an app to use the key) on the timestamp.</li> </ol> -<p class="note"><strong>Note:</strong> AuthTokens are invalidated whenever a device reboots.</p> - -<h2 id=authentication_token_format>Authentication token format</h2> +<aside class="note"><strong>Note:</strong> AuthTokens are invalidated when a +device reboots.</aside> -<p>The AuthToken format described in the -<a href="https://android.googlesource.com/platform/hardware/libhardware/+/master/include/hardware/hw_auth_token.h"><code>hw_auth_token.h</code></a> file is -necessary for token sharing and compatibility across languages and -components. See the following file:</p> -<pre> -hardware/libhardware/include/hardware/hw_auth_token.h -</pre> +<h2 id=authtoken_format>AuthToken format</h2> -<p>A simple serialization protocol with the required fields is defined in the -table below. The fields are fixed size.</p> +<p>To ensure token sharing and compatibility across languages and components, +the AuthToken format is described in +<a href="https://android.googlesource.com/platform/hardware/libhardware/+/master/include/hardware/hw_auth_token.h" class="external"><code>hw_auth_token.h</code></a>. +The format is a simple serialization protocol with fixed size fields:</p> -<p>Field descriptions are below the table.</p> <table> <tr> - <th><strong>Field</strong></th> - <th><strong>Type</strong></th> - <th><strong>Required or Optional</strong></th> + <th width="15%">Field</th> + <th width="20%">Type</th> + <th width="10%">Required</th> + <th>Description</th> </tr> <tr> <td>AuthToken Version</td> <td>1 byte</td> - <td>Required</td> + <td>Yes</td> + <td>Group tag for all fields below.</td> </tr> <tr> <td>Challenge</td> <td>64-bit unsigned integer</td> - <td>Optional</td> + <td>No</td> + <td>A random integer to prevent replay attacks. Usually the ID of a + requested crypto operation. Currently used by transactional fingerprint + authorizations. If present, the AuthToken is valid only for crypto + operations containing the same challenge.</td> </tr> <tr> <td>User SID</td> <td>64-bit unsigned integer</td> - <td>Required</td> + <td>Yes</td> + <td>Non-repeating user identifier tied cryptographically to all keys + associated with device authentication. For details, see + <a href="/security/authentication/gatekeeper.html">Gatekeeper</a>.</td> </tr> <tr> - <td>Authenticator ID</td> + <td>Authenticator ID (ASID)</td> <td>64-bit unsigned integer in network order</td> - <td>Optional</td> + <td>No</td> + <td>Identifier used to bind to a specific authenticator policy. All + authenticators have their own value of ASID that they can change according + to their own requirements.</td> </tr> <tr> <td>Authenticator type</td> <td>32-bit unsigned integer in network order</td> - <td>Required</td> - </tr> + <td>Yes</td> + <td><ul> + <li>0x00 is Gatekeeper.</li> + <li>0x01 is Fingerprint.</li> + </ul> + </td> + </tr> <tr> <td>Timestamp</td> <td>64-bit unsigned integer in network order</td> - <td>Required</td> + <td>Yes</td> + <td>Time (in milliseconds) since the most recent system boot.</td> </tr> <tr> <td>AuthToken HMAC key (SHA-256)</td> <td>256-bit blob</td> - <td>Required</td> + <td>Yes</td> + <td>Keyed SHA-256 MAC of all fields except the HMAC field.</td> </tr> </table> -<h3 id=field_descriptions>Field descriptions </h3> - -<p>This section describes the fields of the AuthToken table above.</p> - -<p><strong>AuthToken Version:</strong> Group tag for all fields below.</p> - -<p><strong>Challenge:</strong> A random integer to prevent replay attacks. Usually the ID of a requested -crypto operation. Currently used by transactional fingerprint authorizations. -If present, the AuthToken is valid only for crypto operations containing the -same challenge.</p> - -<p><strong>User SID</strong>: Non-repeating user identifier tied cryptographically to all keys associated -with device authentication. For more information, see the Gatekeeper page.</p> - -<p><strong>Authenticator ID (ASID)</strong>: Identifier used to bind to a specific authenticator policy. All -authenticators have their own value of ASID that they can change according to -their own requirements.</p> - -<p><strong>Authenticator Type</strong>: Either Gatekeeper or Fingerprint, as follows:</p> -<table> - <tr> - <th><strong>Authenticator Type</strong></th> - <th><strong>Authenticator Name</strong></th> - </tr> - <tr> - <td>0x00</td> - <td>Gatekeeper</td> - </tr> - <tr> - <td>0x01</td> - <td>Fingerprint</td> - </tr> -</table> - -<p><strong>Timestamp</strong>: Time (in milliseconds) since the most recent system boot.</p> - -<p><strong>AuthToken HMAC key</strong>: Keyed SHA-256 MAC of all fields except the HMAC field.</p> - <h2 id=device_boot_flow>Device boot flow</h2> -<p>On every boot of a device, the AuthToken HMAC key must be generated and shared -with all TEE components (Gatekeeper, Fingerprint, and Keymaster). Thus, the HMAC key -must be randomly generated every time the device reboots, for added protection against replay attacks.</p> +<p>On every boot of a device, the AuthToken HMAC key must be generated and +shared with all TEE components (Gatekeeper, Fingerprint, and Keymaster). Thus, +for added protection against replay attacks, the HMAC key must be randomly +generated every time the device reboots.</p> <p>The protocol for sharing this HMAC key with all components is a platform-dependent implementation feature. The key must <strong>never</strong> -be made available outside the TEE. Thus, if a TEE OS lacks an -internal inter-process communication (IPC) mechanism, -and the TEE needs to transfer the data through the untrusted OS, the transfer -must be done via a secure key exchange protocol.</p> +be made available outside the TEE. If a TEE OS lacks an internal inter-process +communication (IPC) mechanism and needs to transfer the data through the +untrusted OS, the transfer must be done via a secure key exchange protocol.</p> <p>The <a href="/security/trusty/index.html">Trusty</a> operating system, -which runs next to Android, is an example of a -TEE, but other TEEs can be used instead. Trusty uses an internal IPC system to -communicate directly between Keymaster and Fingerprint or Gatekeeper. The HMAC -key is kept solely in Keymaster. Fingerprint and Gatekeeper request the key -from Keymaster for each use, and do not persist or cache the value.</p> - -<p>Note that no communication happens between applets in the TEE because some TEEs -are lacking in IPC infrastructure. This also -permits the keystore service to quickly deny requests that are bound to fail as it has -knowledge of the authentication table in the system, saving a potentially -costly IPC into the TEE.</p> +which runs next to Android, is an example of a TEE, but other TEEs can be used +instead. Trusty uses an internal IPC system to communicate directly between +Keymaster and Fingerprint or Gatekeeper. The HMAC key is kept solely in +Keymaster; Fingerprint and Gatekeeper request the key from Keymaster for each +use and do not persist or cache the value.</p> + +<p>As some TEEs lack an IPC infrastructure, no communication occurs between +applets in the TEE. This also permits the keystore service to quickly deny +requests that are bound to fail as it has knowledge of the authentication table +in the system, saving a potentially costly IPC into the TEE.</p> </body> </html> diff --git a/en/security/bulletin/_translation.yaml b/en/security/bulletin/_translation.yaml new file mode 100644 index 00000000..53f84959 --- /dev/null +++ b/en/security/bulletin/_translation.yaml @@ -0,0 +1,16 @@ +enable_continuous_translation: True +title: Android Security Bulletins +description: Translations for Android Security Bulletins +language: +- ja +- ko +- ru +- zh-CN +- zh-TW +cc: +- daroberts@google.com +- sac-doc-leads+translation@google.com +- shaileshs@google.com +reviewer: +- daroberts +product: Android diff --git a/en/security/images/access-to-keymaster.png b/en/security/images/access-to-keymaster.png Binary files differindex 8269c30b..1901b3b5 100644 --- a/en/security/images/access-to-keymaster.png +++ b/en/security/images/access-to-keymaster.png diff --git a/en/security/images/authentication-flow.png b/en/security/images/authentication-flow.png Binary files differindex 1c136e48..179977e8 100644 --- a/en/security/images/authentication-flow.png +++ b/en/security/images/authentication-flow.png diff --git a/en/security/images/fingerprint-daemon.png b/en/security/images/fingerprint-daemon.png Binary files differindex a57a7a4d..4d443abb 100644 --- a/en/security/images/fingerprint-daemon.png +++ b/en/security/images/fingerprint-daemon.png diff --git a/en/security/images/fingerprint-data-flow.png b/en/security/images/fingerprint-data-flow.png Binary files differindex bc3ff36b..8634f4c3 100644 --- a/en/security/images/fingerprint-data-flow.png +++ b/en/security/images/fingerprint-data-flow.png diff --git a/en/security/images/gatekeeper-flow.png b/en/security/images/gatekeeper-flow.png Binary files differindex 693ebec9..afff81a3 100644 --- a/en/security/images/gatekeeper-flow.png +++ b/en/security/images/gatekeeper-flow.png diff --git a/en/source/_translation.yaml b/en/source/_translation.yaml new file mode 100644 index 00000000..33538a7a --- /dev/null +++ b/en/source/_translation.yaml @@ -0,0 +1,10 @@ +enable_continuous_translation: True +title: Android Open Source Project Source tab +description: Translations for SAC source tab +language: +- zh-CN +cc: +- sac-doc-leads+translation@google.com +reviewer: +- daroberts +product: Android |
