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