1 <html devsite> 2 <head> 3 <title>Gatekeeper</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>The Gatekeeper subsystem performs device pattern/password authentication in a 29 Trusted Execution Environment (TEE). Gatekeeper enrolls and verifies passwords 30 via an HMAC with a hardware-backed secret key. Additionally, Gatekeeper 31 throttles consecutive failed verification attempts and must refuse to service 32 requests based on a given timeout and a given number of consecutive failed 33 attempts.</p> 34 35 <p>When users verify their passwords, Gatekeeper uses the TEE-derived shared 36 secret to sign an authentication attestation to 37 send to the <a href="/security/keystore/index.html">hardware-backed Keystore</a>. That is, a 38 Gatekeeper attestation notifies Keystore that authentication-bound keys (for 39 example, keys that apps have created) can be released for use by apps.</p> 40 41 <h2 id=architecture>Architecture</h2> 42 43 <p>Gatekeeper involves three main components:</p> 44 45 <ul> 46 <li><strong>gatekeeperd (Gatekeeper daemon)</strong>. 47 A C++ binder service containing platform-independent logic and corresponding 48 to the <code>GateKeeperService</code> Java interface. 49 <li><strong>Gatekeeper Hardware Abstraction Layer (HAL)</strong>. 50 The HAL interface in <code>hardware/libhardware/include/hardware/gatekeeper.h</code>, 51 and the implementing module. 52 <li><strong>Gatekeeper (TEE)</strong>. 53 The TEE counterpart of <code>gatekeeperd</code>. A TEE-based implementation of Gatekeeper. 54 </ul> 55 56 <p>To implement Gatekeeper:</p> 57 58 <ul> 59 <li>Implement the Gatekeeper HAL, specifically the functions in <code>gatekeeper.h</code> 60 (<code>hardware/libhardware/include/hardware/gatekeeper.h</code>). 61 See <a href="#hal_implementation">HAL Implementation</a>. 62 <li>Implement the TEE-specific Gatekeeper component, in part based on the following 63 header file: <code>system/gatekeeper/include/gatekeeper/gatekeeper.h</code>. This 64 header file includes pure virtual functions for creating and accessing 65 keys, as well as for computing signatures. 66 See <a href="#trusty_and_other_implementations">Trusty and other implementations</a>. 67 </ul> 68 69 <p>As shown in the following diagram, the <code>LockSettingsService</code> makes a request (via 70 Binder) that reaches the <code>gatekeeperd</code> daemon in the Android OS. 71 The <code>gatekeeperd</code> 72 daemon makes a request that reaches its counterpart (Gatekeeper) in the TEE.</p> 73 74 <img src="../images/gatekeeper-flow.png" alt="Gatekeeper flow" id="figure1" /> 75 <p class="img-caption"><strong>Figure 1.</strong> High-level data flow for authentication by GateKeeper</p> 76 77 <p>The <code>gatekeeperd</code> daemon gives the Android framework APIs access to the HAL, and 78 participates in reporting device <a href="index.html">authentications</a> to Keystore. 79 The <code>gatekeeperd</code> daemon runs in its own process, separate from the system 80 server.</p> 81 82 <h2 id=hal_implementation>HAL Implementation</h2> 83 84 <p>The <code>gatekeeperd</code> daemon uses the HAL to interact 85 with the <code>gatekeeperd</code> daemon's TEE 86 counterpart for password authentication. The HAL implementation must be able to 87 sign (enroll) and verify blobs. All implementations are expected to adhere to 88 the standard format for the authentication token (AuthToken) generated on each 89 successful password verification. The contents and semantics of the AuthToken 90 are described in <a href="index.html">Authentication</a>.</p> 91 92 <p>Specifically, an implementation of the <code>gatekeeper.h</code> header file (in the 93 <code>hardware/libhardware/include/hardware</code> folder) needs to implement the 94 <code>enroll</code> and <code>verify</code> functions.</p> 95 96 <p>The <code>enroll</code> function takes a password blob, signs it, and returns the signature 97 as a handle. The returned blob (from a call to <code>enroll</code>) must have the structure 98 shown in <code>system/gatekeeper/include/gatekeeper/password_handle.h</code>.</p> 99 100 <p>The <code>verify</code> function needs to compare the signature produced 101 by the provided password and 102 ensure that it matches the enrolled password handle.</p> 103 104 <p>The key used to enroll and verify must never change, and should be re-derivable 105 at every device boot.</p> 106 107 <h2 id=trusty_and_other_implementations>Trusty and other implementations</h2> 108 109 <p>The <a href="/security/trusty/index.html">Trusty</a> operating system is 110 Google's open source trusted OS for TEE 111 environments. Trusty contains an approved implementation of GateKeeper. However, 112 <strong>any TEE OS</strong> can be used for the implementation of Gatekeeper. 113 The TEE <strong>must</strong> have access to a hardware-backed key as well as a secure, 114 monotonic clock <strong>that ticks in suspend</strong>.</p> 115 116 <p>Trusty uses an internal IPC system to communicate a shared secret directly 117 between Keymaster and the Trusty implementation of Gatekeeper ("Trusty 118 Gatekeeper"). This shared secret is used for signing AuthTokens that will be 119 sent to Keystore, providing attestations of password verification. Trusty 120 Gatekeeper requests the key from Keymaster for each use and does not persist 121 or cache the value. Implementations are free to share this secret in any way 122 that does not compromise security.</p> 123 124 <p>The HMAC key, used to enroll and verify passwords, is derived and kept solely 125 in GateKeeper.</p> 126 127 <p>The Android tree provides a generic C++ implementation of GateKeeper, requiring 128 only the addition of device-specific routines to be complete. To implement a 129 TEE Gatekeeper with device-specific code for your TEE, please refer to the 130 functions and comments in the following file:</p> 131 <pre class="devsite-click-to-copy"> 132 system/gatekeeper/include/gatekeeper/gatekeeper.h 133 </pre> 134 135 <p>For the TEE GateKeeper, the primary responsibilities of a compliant 136 implementation are:</p> 137 138 <ul> 139 <li>Adherence to the Gatekeeper HAL 140 <li>Returned AuthTokens must be formatted according to the AuthToken specification 141 (described in <a href="index.html">Authentication</a>) 142 <li>The TEE Gatekeeper must be able to share an HMAC key with Keymaster, either by 143 requesting the key through a TEE IPC on demand or maintaining a valid cache of 144 the value at all times 145 </ul> 146 147 <h2 id=user_sids>User SIDs</h2> 148 149 <p>A User Secure ID (User SID) is the TEE representation of a user. 150 The User SID has no strong connection to an Android user ID.</p> 151 152 <p>A User SID is generated with a cryptographic 153 PRNG whenever a user enrolls a new password without providing a previous one. 154 This is known as an "untrusted" re-enroll. 155 A "trusted" re-enroll occurs when a user provides a valid, previous password. 156 In this case, the User SID is migrated to the new password handle, 157 conserving the keys that were bound to it. 158 The Android framework does not allow for an "untrusted" re-enroll under regular circumstances.</p> 159 160 <p>The User SID is HMAC'ed along with the password in the password handle when the 161 password is enrolled.</p> 162 163 <p>User SIDs are written into the AuthToken returned by the <code>verify</code> 164 function and associated to all authentication-bound Keystore keys. For 165 information about the AuthToken format and Keystore, see 166 <a href="index.html">Authentication</a>. 167 Since an untrusted call to the <code>enroll</code> function 168 will change the User SID, the call will render the keys bound to that password useless.</p> 169 170 <p>Attackers can change the password for the device if they control the Android 171 OS, but they will destroy root-protected, sensitive keys in the process.</p> 172 173 <h2 id=request_throttling>Request throttling</h2> 174 175 <p>GateKeeper must be able to securely throttle brute-force attempts on a user 176 credential. As shown in the <code>gatekeeper.h</code> 177 file (in <code>hardware/libhardware/include/hardware</code>), 178 the HAL provides for returning a timeout in milliseconds. The timeout 179 informs the client not to call GateKeeper again until after the timeout has 180 elapsed. GateKeeper should not service requests if there is a pending timeout.</p> 181 182 <p>GateKeeper must write a failure counter before verifying a user password. If 183 the password verification succeeds, the failure counter should be cleared. This 184 prevents attacks that prevent throttling by disabling the embedded MMC (eMMC) 185 after issuing a <code>verify</code> call. The <code>enroll</code> function also verifies 186 the user password (if provided) and so must be throttled in the same way.</p> 187 188 <p>If supported by the device, it is highly recommended that the failure counter 189 be written to secure storage. If the device does not support 190 file-based encryption, or if secure storage is too slow, implementations may 191 use RPMB directly.</p> 192 193 194 195 196 197 </body> 198 </html> 199
