1 ## 9.11\. Keys and Credentials 2 3 The [Android Keystore System](https://developer.android.com/training/articles/keystore.html) 4 allows app developers to store cryptographic keys in a container and use them in 5 cryptographic operations through the [KeyChain API](https://developer.android.com/reference/android/security/KeyChain.html) 6 or the [Keystore API](https://developer.android.com/reference/java/security/KeyStore.html). 7 Device implementations: 8 9 * [C-0-1] MUST at least allow more than 8,192 keys to be imported. 10 * [C-0-2] The lock screen authentication MUST rate-limit attempts and MUST 11 have an exponential backoff algorithm. Beyond 150 failed attempts, the delay 12 MUST be at least 24 hours per attempt. 13 * SHOULD not limit the number of keys that can be generated 14 15 When the device implementation supports a secure lock screen, it: 16 17 * [C-1-1] MUST back up the keystore implementation with secure hardware. 18 * [C-1-2] MUST have implementations of RSA, AES, ECDSA and HMAC cryptographic 19 algorithms and MD5, SHA1, and SHA-2 family hash functions to properly support 20 the Android Keystore system's supported algorithms in an area that is securely 21 isolated from the code running on the kernel and above. Secure isolation MUST 22 block all potential mechanisms by which kernel or userspace code might access 23 the internal state of the isolated environment, including DMA. The upstream 24 Android Open Source Project (AOSP) meets this requirement by using the 25 [Trusty](https://source.android.com/security/trusty/) implementation, but 26 another ARM TrustZone-based solution or a third-party reviewed secure 27 implementation of a proper hypervisor-based isolation are alternative options. 28 * [C-1-3] MUST perform the lock screen authentication in the isolated 29 execution environment and only when successful, allow the authentication-bound 30 keys to be used. The upstream Android Open Source Project provides the 31 [Gatekeeper Hardware Abstraction Layer (HAL)](http://source.android.com/devices/tech/security/authentication/gatekeeper.html) 32 and Trusty, which can be used to satisfy this requirement. 33 * [C-1-4] MUST support key attestation where the attestation signing key is 34 protected by secure hardware and signing is performed in secure hardware. The 35 attestation signing keys MUST be shared across large enough number of devices to 36 prevent the keys from being used as device identifiers. One way of meeting this 37 requirement is to share the same attestation key unless at least 100,000 units 38 of a given SKU are produced. If more than 100,000 units of an SKU are produced, 39 a different key MAY be used for each 100,000 units. 40 41 Note that if a device implementation is already launched on an earlier Android 42 version, such a device is exempted from the requirement to have a 43 hardware-backed keystore, unless it declares the `android.hardware.fingerprint` 44 feature which requires a hardware-backed keystore. 45 46 ### 9.11.1\. Secure Lock Screen 47 48 If device implementations have a secure lock screen and include one or more 49 trust agent, which implements the `TrustAgentService` System API, then they: 50 51 * [C-1-1] MUST indicate the user in the Settings and Lock screen user 52 interface of situations where either the screen auto-lock is deferred or the 53 screen lock can be unlocked by the trust agent. The AOSP meets the requirement 54 by showing a text description for the "Automatically lock setting" and 55 "Power button instantly locks setting" menus and a distinguishable icon on 56 the lock screen. 57 * [C-1-2] MUST respect and fully implement all trust agent APIs in the 58 `DevicePolicyManager` class, such as the [`KEYGUARD_DISABLE_TRUST_AGENTS`](https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#KEYGUARD&lowbarDISABLE&lowbarTRUST&lowbarAGENTS) 59 constant. 60 * [C-1-3] MUST NOT fully implement the `TrustAgentService.addEscrowToken()` 61 function on a device that is used as the primary personal device 62 (e.g. handheld) but MAY fully implement the function on device implementations 63 typically shared. 64 * [C-1-4] MUST encrypt the tokens added by `TrustAgentService.addEscrowToken()` 65 before storing them on the device. 66 * [C-1-5] MUST NOT store the encryption key on the device. 67 * [C-1-6] MUST inform the user about the security implications before 68 enabling the escrow token to decrypt the data storage. 69 70 If device implementations add or modify the authentication methods to unlock 71 the lock screen, then for such an authentication method to be treated as a 72 secure way to lock the screen, they: 73 74 * [C-2-1] MUST be the user authentication method as described in 75 [Requiring User Authentication For Key Use](https://developer.android.com/training/articles/keystore.html#UserAuthentication). 76 * [C-2-2] MUST unlock all keys for a third-party developer app to use when 77 the user unlocks the secure lock screen. For example, all keys MUST be available 78 for a third-party developer app through relevant APIs, such as 79 [`createConfirmDeviceCredentialIntent`](https://developer.android.com/reference/android/app/KeyguardManager.html#createConfirmDeviceCredentialIntent%28java.lang.CharSequence, java.lang.CharSequence%29) 80 and [`setUserAuthenticationRequired`](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder.html#setUserAuthenticationRequired%28boolean%29). 81 82 If device implementations add or modify the authentication methods to unlock 83 the lock screen if based on a known secret then for such an authentication 84 method to be treated as a secure way to lock the screen, they: 85 86 * [C-3-1] The entropy of the shortest allowed length of inputs MUST be 87 greater than 10 bits. 88 * [C-3-2] The maximum entropy of all possible inputs MUST be greater than 89 18 bits. 90 * [C-3-3] MUST not replace any of the existing authentication methods 91 (PIN,pattern, password) implemented and provided in AOSP. 92 * [C-3-4] MUST be disabled when the Device Policy Controller (DPC) 93 application has set the password quality policy via the 94 [`DevicePolicyManager.setPasswordQuality()`](https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setPasswordQuality%28android.content.ComponentName,%20int%29) 95 method with a more restrictive quality constant than 96 `PASSWORD_QUALITY_SOMETHING`. 97 98 If device implementations add or modify the authentication methods to unlock 99 the lock screen if based on a physical token or the location, then for such an 100 authentication method to be treated as a secure way to lock the screen, they: 101 102 * [C-4-1] MUST have a fall-back mechanism to use one of the primary 103 authentication methods which is based on a known secret and meets the 104 requirements to be treated as a secure lock screen. 105 * [C-4-2] MUST be disabled and only allow the primary authentication to 106 unlock the screen when the Device Policy Controller (DPC) application has set 107 the policy with either the [`DevicePolicyManager.setKeyguardDisabledFeatures(KEYGUARD_DISABLE_TRUST_AGENTS)`](http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setKeyguardDisabledFeatures%28android.content.ComponentName,%20int%29) 108 method or the [`DevicePolicyManager.setPasswordQuality()`](https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setPasswordQuality%28android.content.ComponentName,%20int%29) 109 method with a more restrictive quality constant than 110 `PASSWORD_QUALITY_UNSPECIFIED`. 111 * [C-4-3] The user MUST be challenged for the primary authentication 112 (e.g.PIN, pattern, password) at least once every 72 hours or less. 113 114 If device implementations add or modify the authentication methods to unlock 115 the lock screen based on biometrics, then for such an authentication method to 116 be treated as a secure way to lock the screen, they: 117 118 * [C-5-1] MUST have a fall-back mechanism to use one of the primary 119 authentication methods which is based on a known secret and meets the 120 requirements to be treated as a secure lock screen. 121 * [C-5-2] MUST be disabled and only allow the primary authentication to 122 unlock the screen when the Device Policy Controller (DPC) application has set 123 the keguard feature policy by calling the method 124 [`DevicePolicyManager.setKeyguardDisabledFeatures(KEYGUARD_DISABLE_FINGERPRINT)`](http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setKeyguardDisabledFeatures%28android.content.ComponentName,%20int%29). 125 * [C-5-3] MUST have a false acceptance rate that is equal or stronger than 126 what is required for a fingerprint sensor as described in section 7.3.10, or 127 otherwise MUST be disabled and only allow the primary authentication to unlock 128 the screen when the Device Policy Controller (DPC) application has set the 129 password quality policy via the [`DevicePolicyManager.setPasswordQuality()`](https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html\#setPasswordQuality%28android.content.ComponentName,%20int%29) 130 method with a more restrictive quality constant than 131 `PASSWORD_QUALITY_BIOMETRIC_WEAK`. 132 * [C-5-4] The user MUST be challenged for the primary authentication 133 (e.g.PIN, pattern, password) at least once every 72 hours or less. 134 135 If device implementations add or modify the authentication methods to unlock 136 the lock screen and if such an authentication method will be used to unlock 137 the keyguard, but will not be treated as a secure lock screen, then they: 138 139 * [C-6-1] MUST return `false` for both the [`KeyguardManager.isKeyguardSecure()`](http://developer.android.com/reference/android/app/KeyguardManager.html#isKeyguardSecure%28%29) 140 and the [`KeyguardManager.isDeviceSecure()`](https://developer.android.com/reference/android/app/KeyguardManager.html#isDeviceSecure%28%29) 141 methods. 142 * [C-6-2] MUST be disabled when the Device Policy Controller (DPC) 143 application has set the password quality policy via the [`DevicePolicyManager.setPasswordQuality()`](https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setPasswordQuality%28android.content.ComponentName,%20int%29) 144 method with a more restrictive quality constant than 145 `PASSWORD_QUALITY_UNSPECIFIED`. 146 * [C-6-3] MUST NOT reset the password expiration timers set by 147 [`DevicePolicyManager.setPasswordExpirationTimeout()`](http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setPasswordExpirationTimeout%28android.content.ComponentName,%20long%29). 148 * [C-6-4] MUST NOT authenticate access to keystores if the application has 149 called [`KeyGenParameterSpec.Builder.setUserAuthenticationRequired(true)`](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder.html#setUserAuthenticationRequired%28boolean%29)).
