fuquan/allwinner_a64
1
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

upload android base code part8

Browse source
This commit is contained in:
August 2018-08-08 20:10:12 +08:00
parent 841ae54672
commit 5425409085
57075 changed files with 9846578 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

175
android/docs/source.android.com/en/security/authentication/fingerprint-hal.html Normal file
View file

@ -0,0 +1,175 @@
<html devsite>
<head>
<title>Fingerprint HAL</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
<!--
Copyright 2017 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<h2 id=overview>Overview</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>
<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.
</ol>
<p>Note that as more templates are stored on a single device, the time needed for
matching is increased.</p>
<h2 id=architecture>Architecture</h2>
<p>The <strong>Fingerprint HAL</strong> interacts with the following components:</p>
<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).
</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 class="img-caption"><strong>Figure 1.</strong> High-level data flow for fingerprint authentication</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>
<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>
<p>Here are the guidelines:</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>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.
<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.
</ol>
<h2 id=major_functions_in_the_fingerprint_hal>Major functions in the Fingerprint HAL</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>
<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.
</ul>
</body>
</html>

198
android/docs/source.android.com/en/security/authentication/gatekeeper.html Normal file
View file

@ -0,0 +1,198 @@
<html devsite>
<head>
<title>Gatekeeper</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
<!--
Copyright 2017 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
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
throttles consecutive failed verification attempts and must refuse to service
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
Gatekeeper attestation notifies Keystore that authentication-bound keys (for
example, keys that apps have created) can be released for use by apps.</p>
<h2 id=architecture>Architecture</h2>
<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.
</ul>
<p>To implement Gatekeeper:</p>
<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>
<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>
<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>
<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>
<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>
<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>
<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
in GateKeeper.</p>
<p>The Android tree provides a generic C++ implementation of GateKeeper, requiring
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>
<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
</ul>
<h2 id=user_sids>User 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 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>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>
<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>
<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>
<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>
</body>
</html>

253
android/docs/source.android.com/en/security/authentication/index.html Normal file
View file

@ -0,0 +1,253 @@
<html devsite>
<head>
<title>Authentication</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
<!--
Copyright 2017 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
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>
<ul>
<li><strong>The <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>
</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,
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>
<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.
</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.
</ol>
<p class="note"><strong>Note:</strong> AuthTokens are invalidated whenever a device reboots.</p>
<h2 id=authentication_token_format>Authentication token format</h2>
<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>
<p>A simple serialization protocol with the required fields is defined in the
table below. The fields are fixed size.</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>
</tr>
<tr>
<td>AuthToken Version</td>
<td>1 byte</td>
<td>Required</td>
</tr>
<tr>
<td>Challenge</td>
<td>64-bit unsigned integer</td>
<td>Optional</td>
</tr>
<tr>
<td>User SID</td>
<td>64-bit unsigned integer</td>
<td>Required</td>
</tr>
<tr>
<td>Authenticator ID</td>
<td>64-bit unsigned integer in network order</td>
<td>Optional</td>
</tr>
<tr>
<td>Authenticator type</td>
<td>32-bit unsigned integer in network order</td>
<td>Required</td>
</tr>
<tr>
<td>Timestamp</td>
<td>64-bit unsigned integer in network order</td>
<td>Required</td>
</tr>
<tr>
<td>AuthToken HMAC key (SHA-256)</td>
<td>256-bit blob</td>
<td>Required</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>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>
<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>
</body>
</html>