1## 9.11\. Keys and Credentials 2 3The [Android Keystore System](https://developer.android.com/training/articles/keystore.html) 4allows app developers to store cryptographic keys in a container and use them in 5cryptographic operations through the [KeyChain API](https://developer.android.com/reference/android/security/KeyChain.html) 6or the [Keystore API](https://developer.android.com/reference/java/security/KeyStore.html). 7Device implementations: 8 9* [C-0-1] MUST allow at least 8,192 keys to be imported or generated. 10* [C-0-2] The lock screen authentication MUST rate-limit attempts and MUST 11have an exponential backoff algorithm. Beyond 150 failed attempts, the delay 12MUST be at least 24 hours per attempt. 13* SHOULD not limit the number of keys that can be generated 14 15When the device implementation supports a secure lock screen, it: 16 17* [C-1-1] MUST back up the keystore implementation with an isolated 18 execution environment. 19* [C-1-2] MUST have implementations of RSA, AES, ECDSA and HMAC cryptographic 20algorithms and MD5, SHA1, and SHA-2 family hash functions to properly support 21the Android Keystore system's supported algorithms in an area that is securely 22isolated from the code running on the kernel and above. Secure isolation MUST 23block all potential mechanisms by which kernel or userspace code might access 24the internal state of the isolated environment, including DMA. The upstream 25Android Open Source Project (AOSP) meets this requirement by using the 26[Trusty](https://source.android.com/security/trusty/) implementation, but 27another ARM TrustZone-based solution or a third-party reviewed secure 28implementation of a proper hypervisor-based isolation are alternative options. 29* [C-1-3] MUST perform the lock screen authentication in the isolated 30execution environment and only when successful, allow the authentication-bound 31keys to be used. Lock screen credentials MUST be stored in a 32way that allows only the isolated execution environment to perform lock screen 33authentication. The upstream Android Open Source Project provides the 34[Gatekeeper Hardware Abstraction Layer (HAL)](http://source.android.com/devices/tech/security/authentication/gatekeeper.html) 35and Trusty, which can be used to satisfy this requirement. 36* [C-1-4] MUST support key attestation where the attestation signing key is 37protected by secure hardware and signing is performed in secure hardware. The 38attestation signing keys MUST be shared across large enough number of devices to 39prevent the keys from being used as device identifiers. One way of meeting this 40requirement is to share the same attestation key unless at least 100,000 units 41of a given SKU are produced. If more than 100,000 units of an SKU are produced, 42a different key MAY be used for each 100,000 units. 43 44Note that if a device implementation is already launched on an earlier Android 45version, such a device is exempted from the requirement to have a keystore 46backed by an isolated execution environment and support the key attestation, 47unless it declares the `android.hardware.fingerprint` feature which requires a 48keystore backed by an isolated execution environment. 49 50* [C-1-5] MUST allow the user to choose the Sleep timeout for transition from 51 the unlocked to the locked state, with a minimum allowable timeout up to 52 15 seconds. Automotive devices, that lock the screen whenever the head unit 53 is turned off or the user is switched, MAY NOT have the Sleep timeout 54 configuration. 55 56### 9.11.1\. Secure Lock Screen and Authentication 57 58The AOSP implementation follows a tiered authentication model where a 59knowledge-factory based primary authentication can be backed by either a 60secondary strong biometric, or by weaker tertiary modalities. 61 62Device implementations: 63 64* [C-SR] Are STRONGLY RECOMMENDED to set only one of the following as the primary authentication 65method: 66 * A numerical PIN 67 * An alphanumerical password 68 * A swipe pattern on a grid of exactly 3x3 dots 69 70Note that the above authentication methods are referred as the recommended 71primary authentication methods in this document. 72 73If device implementations add or modify the recommended primary authentication 74methods and use a new authentication method as a secure way to lock the screen, 75the new authentication method: 76 77* [C-2-1] MUST be the user authentication method as described in 78 [Requiring User Authentication For Key Use]( 79 https://developer.android.com/training/articles/keystore.html#UserAuthentication). 80 81If device implementations add or modify the authentication methods to unlock 82the lock screen if based on a known secret and use a new authentication 83method to be treated as a secure way to lock the screen: 84 85* [C-3-1] The entropy of the shortest allowed length of inputs MUST be 86 greater than 10 bits. 87* [C-3-2] The maximum entropy of all possible inputs MUST be greater than 88 18 bits. 89* [C-3-3] The new authentication method MUST NOT replace any of the 90 recommended primary authentication methods (i.e. PIN, pattern, password) 91 implemented and provided in AOSP. 92* [C-3-4] The new authentication method MUST be disabled when the Device 93 Policy Controller (DPC) application has set the password quality policy 94 via the 95 [`DevicePolicyManager.setPasswordQuality()`]( 96 https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setPasswordQuality%28android.content.ComponentName,%20int%29) 97 method with a more restrictive quality constant than 98 `PASSWORD_QUALITY_SOMETHING`. 99* [C-3-5] New authentication methods MUST either fall back to the 100 recommended primary authentication methods (i.e. PIN, pattern, 101 password) once every 72 hours or less OR clearly disclose to the 102 user that some data will not be backed up in order to preserve 103 the privacy of their data. 104 105If device implementations add or modify the recommended primary authentication 106methods to unlock the lock screen and use a new authentication method that is 107based on biometrics to be treated as a secure way to lock the screen, the new 108method: 109 110* [C-4-1] MUST meet all requirements described in [section 111 7.3.10](#7_3_10_biometric_sensors) for **Class 1** (formerly 112 **Convenience**). 113* [C-4-2] MUST have a fall-back mechanism to use one of the recommended 114 primary authentication methods which is based on a known secret. 115* [C-4-3] MUST be disabled and only allow the recommended primary 116 authentication to unlock the screen when the Device Policy Controller (DPC) 117 application has set the keyguard feature policy by calling the method 118 [`DevicePolicyManager.setKeyguardDisabledFeatures()`]( 119 http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setKeyguardDisabledFeatures%28android.content.ComponentName,%20int%29) 120 , with any of the associated biometric flags (i.e. 121 `KEYGUARD_DISABLE_BIOMETRICS`, `KEYGUARD_DISABLE_FINGERPRINT`, 122 `KEYGUARD_DISABLE_FACE`, or `KEYGUARD_DISABLE_IRIS`). 123 124If the biometric authentication methods do not meet the requirements 125for **Class 3** (formerly **Strong**) as described in 126[section 7.3.10](#7_3_10_biometric_sensors): 127 128* [C-5-1] The methods MUST be disabled if the Device Policy Controller (DPC) 129 application has set the password quality policy via the [`DevicePolicyManager.setPasswordQuality()`]( 130 https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html\#setPasswordQuality%28android.content.ComponentName,%20int%29) 131 method with a more restrictive quality constant than 132 `PASSWORD_QUALITY_BIOMETRIC_WEAK`. 133* [C-5-2] The user MUST be challenged for the recommended primary 134 authentication (eg: PIN, pattern, password) as described in [C-1-7] and 135 [C-1-8] in [section 7.3.10](#7_3_10_biometric_sensors). 136* [C-5-3] The methods MUST NOT be treated as a secure lock screen, and MUST 137 meet the requirements that start with C-8 in this section below. 138 139If device implementations add or modify the authentication methods to unlock 140the lock screen and a new authentication method is based on a physical token 141or the location: 142 143* [C-6-1] They MUST have a fall-back mechanism to use one of the recommended 144 primary authentication methods which is based on a known secret and meet 145 the requirements to be treated as a secure lock screen. 146* [C-6-2] The new method MUST be disabled and only allow one of the 147 recommended primary authentication methods to unlock the screen when the 148 Device Policy Controller (DPC) application has set the policy with either 149 the 150 [`DevicePolicyManager.setKeyguardDisabledFeatures(KEYGUARD_DISABLE_TRUST_AGENTS)`]( 151 http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setKeyguardDisabledFeatures%28android.content.ComponentName,%20int%29) 152 method or the 153 [`DevicePolicyManager.setPasswordQuality()`]( 154 https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setPasswordQuality%28android.content.ComponentName,%20int%29) 155 method with a more restrictive quality constant than 156 `PASSWORD_QUALITY_UNSPECIFIED`. 157* [C-6-3] The user MUST be challenged for one of the recommended primary 158 authentication methods (e.g.PIN, pattern, password) at least once every 4 159 hours or less. 160* [C-6-4] The new method MUST NOT be treated as a secure lock screen and MUST 161 follow the constraints listed in C-8 below. 162 163If device implementations have a secure lock screen and include one or more 164trust agent, which implements the `TrustAgentService` System API, they: 165 166* [C-7-1] MUST have clear indication in the settings menu and on the lock 167 screen when device lock is deferred or can be unlocked by trust agent(s). 168 For example, AOSP meets this requirement by showing a text description for 169 the "Automatically lock setting" and "Power button instantly locks" in the 170 settings menu and a distinguishable icon on the lock screen. 171* [C-7-2] MUST respect and fully implement all trust agent APIs in the 172 `DevicePolicyManager` class, such as the 173 [`KEYGUARD_DISABLE_TRUST_AGENTS`]( 174 https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#KEYGUARD&lowbarDISABLE&lowbarTRUST&lowbarAGENTS) 175 constant. 176* [C-7-3] MUST NOT fully implement the `TrustAgentService.addEscrowToken()` 177 function on a device that is used as a primary personal device 178 (e.g. handheld) but MAY fully implement the function on device 179 implementations that are typically shared (e.g. Android Television or 180 Automotive device). 181* [C-7-4] MUST encrypt all stored tokens added by 182 `TrustAgentService.addEscrowToken()`. 183* [C-7-5] MUST NOT store the encryption key or escrow token on the 184 same device where the key is used. For example, it is allowed for 185 a key stored on a phone to unlock a user account on a TV. 186 For Automotive devices, it is not allowed for the escrow token to be stored 187 on any part of the vehicle. 188* [C-7-6] MUST inform the user about the security implications before 189 enabling the escrow token to decrypt the data storage. 190* [C-7-7] MUST have a fall-back mechanism to use one of the recommended 191 primary authentication methods. 192* [C-7-8] The user MUST be challenged for one of the recommended primary 193 authentication (eg: PIN, pattern, password) methods at least once every 72 194 hours or less. 195* [C-7-9] The user MUST be challenged for one of the recommended primary 196 authentication (eg: PIN, pattern, password) methods as described in 197 [C-1-7] and [C-1-8] in [section 7.3.10](#7_3_10_biometric_sensors). 198* [C-7-10] MUST NOT be treated as a secure lock screen and MUST follow the 199 constraints listed in C-8 below. 200* [C-7-11] MUST NOT allow TrustAgents on primary personal devices 201 (e.g: handheld) to unlock the device, and can only use them to 202 keep an already unlocked device in the unlocked state for up to a 203 maximum of 4 hours. The default implementation of 204 TrustManagerService in AOSP meets this requirement. 205* [C-7-12] MUST use a cryptographically secure (e.g UKEY2) 206 communication channel to pass the escrow token from the storage 207 device to the target device. 208 209If device implementations add or modify the authentication methods to unlock 210the lock screen that is not a secure lock screen as described above, and use 211a new authentication method to unlock the keyguard: 212 213* [C-8-1] The new method MUST be disabled when the Device Policy Controller 214 (DPC) application has set the password quality policy via the 215 [`DevicePolicyManager.setPasswordQuality()`]( 216 https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setPasswordQuality%28android.content.ComponentName,%20int%29) 217 method with a more restrictive quality constant than 218 `PASSWORD_QUALITY_UNSPECIFIED`. 219* [C-8-2] They MUST NOT reset the password expiration timers set by 220 [`DevicePolicyManager.setPasswordExpirationTimeout()`]( 221 http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setPasswordExpirationTimeout%28android.content.ComponentName,%20long%29). 222* [C-8-3] They MUST NOT expose an API for use by third-party apps to 223 determine the lock state. 224 225### 9.11.2\. StrongBox 226 227The [Android Keystore System]( 228https://developer.android.com/training/articles/keystore.html) allows 229app developers to store cryptographic keys in a dedicated secure processor as 230well as the isolated execution environment described above. Such a 231dedicated secure processor is called "StrongBox". Requirements C-1-3 232through C-1-11 below define the requirements a device must meet to 233qualify as a StrongBox. 234 235Device implementations that have a dedicated secure processor: 236 237* [C-SR] Are STRONGLY RECOMMENDED to support StrongBox. StrongBox will 238 likely become a requirement in a future release. 239 240If device implementations support StrongBox, they: 241 242* [C-1-1] MUST declare [FEATURE_STRONGBOX_KEYSTORE]( 243https://developer.android.com/reference/kotlin/android/content/pm/PackageManager#FEATURE_STRONGBOX_KEYSTORE%3Akotlin.String). 244 245* [C-1-2] MUST provide dedicated secure hardware that is used to back 246keystore and secure user authentication. The dedicated secure 247hardware may be used for other purposes as well. 248 249* [C-1-3] MUST have a discrete CPU that shares no cache, DRAM, coprocessors 250or other core resources with the application processor (AP). 251 252* [C-1-4] MUST ensure that any peripherals shared with the AP cannot alter 253StrongBox processing in any way, or obtain any information from the StrongBox. 254The AP MAY disable or block access to StrongBox. 255 256* [C-1-5] MUST have an internal clock with reasonable accuracy (+-10%) 257that is immune to manipulation by the AP. 258 259* [C-1-6] MUST have a true random number generator that produces 260uniformly-distributed and unpredictable output. 261 262* [C-1-7] MUST have tamper resistance, including resistance against 263physical penetration, and glitching. 264 265* [C-1-8] MUST have side-channel resistance, including resistance against 266leaking information via power, timing, electromagnetic radiation, and thermal 267radiation side channels. 268 269* [C-1-9] MUST have secure storage which ensures confidentiality, 270integrity, authenticity, consistency, and freshness of the 271contents. The storage MUST NOT be able to be read or altered, except 272as permitted by the StrongBox APIs. 273 274* To validate compliance with [C-1-3] through [C-1-9], device 275 implementations: 276 277 * [C-1-10] MUST include the hardware that is certified against the 278 Secure IC Protection Profile [BSI-CC-PP-0084-2014]( 279 https://www.commoncriteriaportal.org/files/ppfiles/pp0084b_pdf.pdf) or 280 evaluated by a nationally accredited testing laboratory incorporating 281 High attack potential vulnerability assessment according to the 282 [Common Criteria Application of Attack Potential to Smartcards]( 283 https://www.commoncriteriaportal.org/files/supdocs/CCDB-2013-05-002.pdf). 284 * [C-1-11] MUST include the firmware that is evaluated by a 285 nationally accredited testing laboratory incorporating High attack 286 potential vulnerability assessment according to the 287 [Common Criteria Application of Attack Potential to Smartcards]( 288 https://www.commoncriteriaportal.org/files/supdocs/CCDB-2013-05-002.pdf). 289 * [C-SR] Are STRONGLY RECOMMENDED to include the hardware that is 290 evaluated using a Security Target, Evaluation Assurance Level 291 (EAL) 5, augmented by AVA_VAN.5. EAL 5 certification will likely 292 become a requirement in a future release. 293 294* [C-SR] are STRONGLY RECOMMENDED to provide insider attack resistance (IAR), 295which means that an insider with access to firmware signing keys cannot produce 296firmware that causes the StrongBox to leak secrets, to bypass functional 297security requirements or otherwise enable access to sensitive user data. The 298recommended way to implement IAR is to allow firmware updates only when the 299primary user password is provided via the IAuthSecret HAL. IAR will likely 300become a requirement in a future release. 301 302### 9.11.3\. Identity Credential 303 304The Identity Credential System is defined and achieved by implementing all 305APIs in the 306[`android.security.identity.*`](https://developer.android.com/reference/android/security/identity/package-summary) 307package. These APIs allows app developers to store and retrieve user identity 308documents. Device implementations: 309 310* [C-SR] are STRONGLY RECOMMENDED to implement the Identity Credential 311System. 312 313If device implementations implement the Identity Credential System, they: 314 315* [C-0-1] MUST return non-null for the [IdentityCredentialStore#getInstance()]( 316 https://developer.android.com/reference/android/security/identity/IdentityCredentialStore#getInstance%28android.content.Context%29) 317 method. 318 319* [C-0-2] MUST implement the Identity Credential System (e.g. the 320 `android.security.identity.*` APIs) with code communicating with a trusted 321 application in an area that is securely isolated from the code running on 322 the kernel and above. Secure isolation MUST block all potential mechanisms 323 by which kernel or userspace code might access the internal state of the 324 isolated environment, including DMA. 325 326* [C-0-3] The cryptographic operations needed to implement the Identity 327 Credential System (e.g. the `android.security.identity.*` APIs) MUST be 328 performed entirely in the trusted application and private key material MUST 329 never leave the isolated execution environment unless specifically required 330 by higher-level APIs (e.g. the 331 [createEphemeralKeyPair()](https://developer.android.com/reference/android/security/identity/IdentityCredential#createEphemeralKeyPair%28%29) 332 method). 333 334* [C-0-4] The trusted application MUST be implemented in a way such that its 335 security properties are not affected (e.g. credential data is not released unless access 336 control conditions are satisfied, MACs can't be produced for arbitrary 337 data) even if Android is misbehaving or compromised. 338