1page.title=Authentication
2@jd:body
3
4<!--
5    Copyright 2015 The Android Open Source Project
6
7    Licensed under the Apache License, Version 2.0 (the "License");
8    you may not use this file except in compliance with the License.
9    You may obtain a copy of the License at
10
11        http://www.apache.org/licenses/LICENSE-2.0
12
13    Unless required by applicable law or agreed to in writing, software
14    distributed under the License is distributed on an "AS IS" BASIS,
15    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16    See the License for the specific language governing permissions and
17    limitations under the License.
18-->
19<div id="qv-wrapper">
20  <div id="qv">
21    <h2>In this document</h2>
22    <ol id="auto-toc">
23    </ol>
24  </div>
25</div>
26
27<h2 id=overview>Overview</h2>
28
29<p>Android 6.0 introduces the concept of user-authentication-gated cryptographic
30keys. To achieve this, two key components need to work together.
31First is the cryptographic key storage and service provider, which stores
32cryptographic keys and provides standard crypto routines on top of them. Second
33is any number of user authenticators that may attest to the user's presence
34and/or successful authentication.</p>
35
36<p>The cryptographic key storage in Android is provided by the keystore service and Keymaster.
37(Also see information about
38the <a href="https://developer.android.com/training/articles/keystore.html">Android Keystore system</a>,
39at the framework level, which is backed by the keystore service.) For Android 6.0,
40the two supported authentication components are Gatekeeper (for
41PIN/pattern/password authentication) and Fingerprint (for fingerprint
42authentication). These components communicate their authentication
43state with the keystore service via an authenticated channel.</p>
44
45<ul>
46  <li><strong>The <a href="{@docRoot}security/keystore/index.html">hardware-backed Keystore</a>.</strong>
47  Cryptographic services, including hardware-backed cryptography for key storage,
48  which might include a Trusted Execution Environment (TEE).</li>
49  <li><strong><a href="gatekeeper.html">Gatekeeper</a>.</strong> Components for PIN, pattern, and password authentication.</li>
50  <li><strong><a href="fingerprint-hal.html">Fingerprint</a>.</strong> Components for fingerprint authentication.</li>
51</ul>
52
53<h2 id=architecture>Architecture</h2>
54
55<p>The Gatekeeper and Fingerprint components work with Keystore and other
56components to support the use of hardware-backed <a href="#authentication_token_format">authentication tokens</a> (referred to below as "AuthTokens").</p>
57
58<h3 id=enrollment>Enrollment</h3>
59
60<p>Upon first boot of the device after a factory reset, all authenticators are prepared to receive
61credential enrollments from the user.</p>
62
63<p>The user must initially enroll a PIN/pattern/password with Gatekeeper. This
64initial enrollment creates a randomly generated, 64-bit User SID (user secure
65identifier, described further below) that serves as an identifier for the user
66and as a binding token for the user's cryptographic material.
67This User SID is cryptographically bound to the user's password.
68As detailed below, successful authentications to Gatekeeper result in AuthTokens that contain the User SID
69for that password.</p>
70
71<p>When a user wants to change their credential, they must present their existing
72credential. If the existing credential is verified successfully, the User SID
73associated with the existing credential is transferred to the new credential.
74This allows the user to keep accessing their keys after changing their
75credential. If a user does not present their existing credential, the new one
76is enrolled with a fully random User SID. The user can access the device but
77keys created under the old User SID are permanently lost. This is known as an
78"untrusted enroll."</p>
79
80<p>Note that an untrusted enroll will not be allowed under normal circumstances by
81the Android framework, so most users won't ever see this functionality.
82However, forcible password resets either by a device administrator or an
83attacker may cause this to occur.</p>
84
85<h3 id=authentication>Authentication</h3>
86
87<p>Now that the user has set up a credential and received a User SID, they may
88proceed to start authentication.</p>
89
90<p>In the diagram below, authentication starts when a user provides a PIN,
91pattern, password, or fingerprint. All TEE components share a secret key which
92they use to authenticate each other's messages.</p>
93
94<img src="../images/authentication-flow.png" alt="Authentication flow" id="figure1" />
95<p class="img-caption"><strong>Figure 1.</strong> Authentication flow</p>
96
97<p>The numbers in the following steps correspond to the numbers in the diagram
98above, and include reference to both the Android OS and the TEE OS: </p>
99
100<ol>
101  <li>A user provides a PIN, pattern, password, or fingerprint. The
102<code>LockSettingsService</code> or <code>FingerprintService</code> make a request via Binder to the
103Gatekeeperd or fingerprintd daemon in the Android OS. Note that fingerprint
104authentication occurs asynchronously after the fingerprint request is sent.
105  <li>This step involves <strong>either</strong> Gatekeeperd (option 1 below)
106  <strong>or</strong> fingerprintd (option 2 below),
107  depending on whether a pin/pattern/password, or fingerprint, is provided.
108  <ul>
109    <li>The Gatekeeperd daemon sends a pin, pattern, or password hash (received in step
1101) to its counterpart (Gatekeeper) in the TEE. If authentication in the TEE is
111successful, Gatekeeper in the TEE sends an AuthToken containing the
112corresponding User SID, signed with the AuthToken HMAC key, to its
113counterpart in the Android OS.
114    <li>Alternatively, the fingerprintd daemon, which listens for fingerprint events,
115sends the data (received in step 1) to its counterpart (Fingerprint) in the
116TEE. If authentication in the TEE is successful, Fingerprint in the TEE sends
117an AuthToken, signed with the AuthToken HMAC key, to its counterpart in the Android OS.
118  </ul>
119  <li>The Gatekeeperd or fingerprintd daemon receives a signed AuthToken and passes
120the AuthToken to the keystore service via an extension to
121the keystore service's Binder interface. Additionally, Gatekeeperd notifies the keystore service when
122the device is re-locked and when the device password changes.
123  <li>The keystore service passes to Keymaster the AuthTokens received from Gatekeeperd and
124fingerprintd, verifying the AuthTokens with the key shared with the Gatekeeper
125and Fingerprint trustlets. Keymaster trusts the timestamp in the token as the
126last authentication time and bases a key release decision (to allow an app to
127use the key) on the timestamp.
128</ol>
129
130<p class="note"><strong>Note:</strong> AuthTokens are invalidated whenever a device reboots.</p>
131
132<h2 id=authentication_token_format>Authentication token format</h2>
133
134<p>The AuthToken format described in the
135<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
136necessary for token sharing and compatibility across languages and
137components. See the following file:</p>
138<pre>
139hardware/libhardware/include/hardware/hw_auth_token.h
140</pre>
141
142<p>A simple serialization protocol with the required fields is defined in the
143table below. The fields are fixed size.</p>
144
145<p>Field descriptions are below the table.</p>
146<table>
147 <tr>
148    <th><strong>Field</strong></th>
149    <th><strong>Type</strong></th>
150    <th><strong>Required or Optional</strong></th>
151 </tr>
152 <tr>
153    <td>AuthToken Version</td>
154    <td>1 byte</td>
155    <td>Required</td>
156 </tr>
157 <tr>
158    <td>Challenge</td>
159    <td>64-bit unsigned integer</td>
160    <td>Optional</td>
161 </tr>
162 <tr>
163    <td>User SID</td>
164    <td>64-bit unsigned integer</td>
165    <td>Required</td>
166 </tr>
167 <tr>
168    <td>Authenticator ID</td>
169    <td>64-bit unsigned integer in network order</td>
170    <td>Optional</td>
171 </tr>
172 <tr>
173    <td>Authenticator type</td>
174    <td>32-bit unsigned integer in network order</td>
175    <td>Required</td>
176 </tr>
177 <tr>
178    <td>Timestamp</td>
179    <td>64-bit unsigned integer in network order</td>
180    <td>Required</td>
181 </tr>
182 <tr>
183    <td>AuthToken HMAC key (SHA-256)</td>
184    <td>256-bit blob</td>
185    <td>Required</td>
186 </tr>
187</table>
188
189<h3 id=field_descriptions>Field descriptions </h3>
190
191<p>This section describes the fields of the AuthToken table above.</p>
192
193<p><strong>AuthToken Version:</strong> Group tag for all fields below.</p>
194
195<p><strong>Challenge:</strong> A random integer to prevent replay attacks. Usually the ID of a requested
196crypto operation. Currently used by transactional fingerprint authorizations.
197If present, the AuthToken is valid only for crypto operations containing the
198same challenge.</p>
199
200<p><strong>User SID</strong>: Non-repeating user identifier tied cryptographically to all keys associated
201with device authentication. For more information, see the Gatekeeper page.</p>
202
203<p><strong>Authenticator ID (ASID)</strong>: Identifier used to bind to a specific authenticator policy. All
204authenticators have their own value of ASID that they can change according to
205their own requirements.</p>
206
207<p><strong>Authenticator Type</strong>: Either Gatekeeper or Fingerprint, as follows:</p>
208<table>
209 <tr>
210    <th><strong>Authenticator Type</strong></th>
211    <th><strong>Authenticator Name</strong></th>
212 </tr>
213 <tr>
214    <td>0x00</td>
215    <td>Gatekeeper</td>
216 </tr>
217 <tr>
218    <td>0x01</td>
219    <td>Fingerprint</td>
220 </tr>
221</table>
222
223<p><strong>Timestamp</strong>: Time (in milliseconds) since the most recent system boot.</p>
224
225<p><strong>AuthToken HMAC key</strong>: Keyed SHA-256 MAC of all fields except the HMAC field.</p>
226
227<h2 id=device_boot_flow>Device boot flow</h2>
228
229<p>On every boot of a device, the AuthToken HMAC key must be generated and shared
230with all TEE components (Gatekeeper, Fingerprint, and Keymaster). Thus, the HMAC key
231must be randomly generated every time the device reboots, for added protection against replay attacks.</p>
232
233<p>The protocol for sharing this HMAC key with all components is a
234platform-dependent implementation feature. The key must <strong>never</strong>
235be made available outside the TEE. Thus, if a TEE OS lacks an
236internal inter-process communication (IPC) mechanism,
237and the TEE needs to transfer the data through the untrusted OS, the transfer
238must be done via a secure key exchange protocol.</p>
239
240<p>The <a href="{@docRoot}security/trusty/index.html">Trusty</a> operating system,
241which runs next to Android, is an example of a
242TEE, but other TEEs can be used instead. Trusty uses an internal IPC system to
243communicate directly between Keymaster and Fingerprint or Gatekeeper. The HMAC
244key is kept solely in Keymaster. Fingerprint and Gatekeeper request the key
245from Keymaster for each use, and do not persist or cache the value.</p>
246
247<p>Note that no communication happens between applets in the TEE because some TEEs
248are lacking in IPC infrastructure. This also
249permits the keystore service to quickly deny requests that are bound to fail as it has
250knowledge of the authentication table in the system, saving a potentially
251costly IPC into the TEE.</p>
252