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.
53
54### 9.11.1\. Secure Lock Screen and Authentication
55
56The AOSP implementation follows a tiered authentication model where a
57knowledge-factory based primary authentication can be backed by either a
58secondary strong biometric, or by weaker tertiary modalities.
59
60Device implementations:
61
62*    [C-SR] Are STRONGLY RECOMMENDED to set only one of the following as the primary authentication
63method:
64     *     A numerical PIN
65     *     An alphanumerical password
66     *     A swipe pattern on a grid of exactly 3x3 dots
67
68Note that the above authentication methods are referred as the recommended
69primary authentication methods in this document.
70
71If device implementations add or modify the recommended primary authentication
72methods and use a new authentication method as a secure way to lock the screen,
73the new authentication method:
74
75*    [C-2-1] MUST be the user authentication method as described in
76     [Requiring User Authentication For Key Use](
77     https://developer.android.com/training/articles/keystore.html#UserAuthentication).
78*    [C-2-2] MUST unlock all keys for a third-party developer app to use when
79     the user unlocks the secure lock screen. For example, all keys MUST be
80     available for a third-party developer app through relevant APIs, such as
81     [`createConfirmDeviceCredentialIntent`](
82     https://developer.android.com/reference/android/app/KeyguardManager.html#createConfirmDeviceCredentialIntent%28java.lang.CharSequence, java.lang.CharSequence%29)
83     and [`setUserAuthenticationRequired`](
84     https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder.html#setUserAuthenticationRequired%28boolean%29).
85
86If device implementations add or modify the authentication methods to unlock
87the lock screen if based on a known secret and use a new authentication
88method to be treated as a secure way to lock the screen:
89
90*    [C-3-1] The entropy of the shortest allowed length of inputs MUST be
91     greater than 10 bits.
92*    [C-3-2] The maximum entropy of all possible inputs MUST be greater than
93     18 bits.
94*    [C-3-3] The new authentication method MUST NOT replace any of the
95     recommended primary authentication methods (i.e. PIN, pattern, password)
96     implemented and provided in AOSP.
97*    [C-3-4] The new authentication method MUST be disabled when the Device
98     Policy Controller (DPC) application has set the password quality policy
99     via the
100     [`DevicePolicyManager.setPasswordQuality()`](
101     https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setPasswordQuality%28android.content.ComponentName,%20int%29)
102     method with a more restrictive quality constant than
103    `PASSWORD_QUALITY_SOMETHING`.
104*    [C-3-5] New authentication methods MUST either fall back to the
105     recommended primary authentication methods (i.e. PIN, pattern,
106     password) once every 72 hours or less OR clearly disclose to the
107     user that some data will not be backed up in order to preserve
108     the privacy of their data.
109
110If device implementations add or modify the recommended primary authentication
111methods to unlock the lock screen and use a new authentication method that is
112based on biometrics to be treated as a secure way to lock the screen, the new
113method:
114
115*    [C-4-1] MUST meet all requirements described in [section
116     7.3.10](#7_3_10_biometric_sensors) for **Convenience**.
117*    [C-4-2] MUST have a fall-back mechanism to use one of the recommended
118     primary authentication methods which is based on a known secret.
119*    [C-4-3] MUST be disabled and only allow the recommended primary
120     authentication to unlock the screen when the Device Policy Controller (DPC)
121     application has set the keyguard feature policy by calling the method
122     [`DevicePolicyManager.setKeyguardDisabledFeatures()`](
123     http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setKeyguardDisabledFeatures%28android.content.ComponentName,%20int%29)
124     , with any of the associated biometric flags (i.e.
125     `KEYGUARD_DISABLE_BIOMETRICS`, `KEYGUARD_DISABLE_FINGERPRINT`,
126     `KEYGUARD_DISABLE_FACE`, or `KEYGUARD_DISABLE_IRIS`).
127
128If the biometric authentication methods do not meet the requirements
129for **Strong** as described in [section 7.3.10](#7_3_10_biometric_sensors):
130
131*    [C-5-1] The methods MUST be disabled if the Device Policy Controller (DPC)
132     application has set the password quality policy via the [`DevicePolicyManager.setPasswordQuality()`](
133     https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html\#setPasswordQuality%28android.content.ComponentName,%20int%29)
134     method with a more restrictive quality constant than
135     `PASSWORD_QUALITY_BIOMETRIC_WEAK`.
136*    [C-5-2] The user MUST be challenged for the recommended primary
137     authentication (eg: PIN, pattern, password) after any 4-hour idle timeout
138     period. The idle timeout period is reset after any successful confirmation
139     of the device credentials.
140*    [C-5-3] The methods MUST NOT be treated as a secure lock screen, and MUST
141     meet the requirements that start with C-8 in this section below.
142
143If device implementations add or modify the authentication methods to unlock
144the lock screen and a new authentication method is based on a physical token
145or the location:
146
147*    [C-6-1] They MUST have a fall-back mechanism to use one of the recommended
148     primary authentication methods which is based on a known secret and meet
149     the requirements to be treated as a secure lock screen.
150*    [C-6-2] The new method MUST be disabled and only allow one of the
151     recommended primary authentication methods to unlock the screen when the
152     Device Policy Controller (DPC) application has set the policy with either
153     the
154     [`DevicePolicyManager.setKeyguardDisabledFeatures(KEYGUARD_DISABLE_TRUST_AGENTS)`](
155     http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setKeyguardDisabledFeatures%28android.content.ComponentName,%20int%29)
156     method or the
157     [`DevicePolicyManager.setPasswordQuality()`](
158     https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setPasswordQuality%28android.content.ComponentName,%20int%29)
159     method with a more restrictive quality constant than
160     `PASSWORD_QUALITY_UNSPECIFIED`.
161*    [C-6-3] The user MUST be challenged for one of the recommended primary
162     authentication methods (e.g.PIN, pattern, password) at least once every 4
163     hours or less.
164*    [C-6-4] The new method MUST NOT be treated as a secure lock screen and MUST
165     follow the constraints listed in C-8 below.
166
167If device implementations have a secure lock screen and include one or more
168trust agent, which implements the `TrustAgentService` System API, they:
169
170*    [C-7-1] MUST have clear indication in the settings menu and on the lock
171     screen when device lock is deferred or can be unlocked by trust agent(s).
172     For example, AOSP meets this requirement by showing a text description for
173     the "Automatically lock setting" and "Power button instantly locks" in the
174     settings menu and a distinguishable icon on the lock screen.
175*    [C-7-2] MUST respect and fully implement all trust agent APIs in the
176     `DevicePolicyManager` class, such as the
177     [`KEYGUARD_DISABLE_TRUST_AGENTS`](
178     https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#KEYGUARD&lowbarDISABLE&lowbarTRUST&lowbarAGENTS)
179     constant.
180*    [C-7-3] MUST NOT fully implement the `TrustAgentService.addEscrowToken()`
181     function on a device that is used as a primary personal device
182     (e.g. handheld) but MAY fully implement the function on device
183     implementations that are typically shared (e.g. Android Television or
184     Automotive device).
185*    [C-7-4] MUST encrypt all stored tokens added by
186     `TrustAgentService.addEscrowToken()`.
187*    [C-7-5] MUST NOT store the encryption key or escrow token on the
188     same device where the key is used. For example, it is allowed for
189     a key stored on a phone to unlock a user account on a TV.
190*    [C-7-6] MUST inform the user about the security implications before
191     enabling the escrow token to decrypt the data storage.
192*    [C-7-7] MUST have a fall-back mechanism to use one of the recommended
193     primary authentication methods.
194*    [C-7-8] The user MUST be challenged for one of the recommended primary
195     authentication (eg: PIN, pattern, password) methods at least once every 72
196     hours or less.
197*    [C-7-9] The user MUST be challenged for one of the recommended primary
198     authentication (eg: PIN, pattern, password) methods after any 4-hour idle
199     timeout period. The idle timeout period is reset after any successful
200     confirmation of the device credentials.
201*    [C-7-10] MUST NOT be treated as a secure lock screen and MUST follow the
202     constraints listed in C-8 below.
203*    [C-7-11] MUST NOT allow TrustAgents on primary personal devices
204     (e.g: handheld) to unlock the device, and can only use them to
205     keep an already unlocked device in the unlocked state for up to a
206     maximum of 4 hours. The default implementation of
207     TrustManagerService in AOSP meets this requirement.
208*    [C-7-12] MUST use a cryptographically secure (e.g UKEY2)
209     communication channel to pass the escrow token from the storage
210     device to the target device.
211
212If device implementations add or modify the authentication methods to unlock
213the lock screen that is not a secure lock screen as described above, and use
214a new authentication method to unlock the keyguard:
215
216*    [C-8-1] The new method MUST be disabled when the Device Policy Controller
217     (DPC) application has set the password quality policy via the
218     [`DevicePolicyManager.setPasswordQuality()`](
219     https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setPasswordQuality%28android.content.ComponentName,%20int%29)
220     method with a more restrictive quality constant than
221     `PASSWORD_QUALITY_UNSPECIFIED`.
222*    [C-8-2] They MUST NOT reset the password expiration timers set by
223     [`DevicePolicyManager.setPasswordExpirationTimeout()`](
224     http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setPasswordExpirationTimeout%28android.content.ComponentName,%20long%29).
225*    [C-8-3] They MUST NOT expose an API for use by third-party apps to
226     determine the lock state.
227
228### 9.11.2\. StrongBox
229
230The [Android Keystore System](
231https://developer.android.com/training/articles/keystore.html) allows
232app developers to store cryptographic keys in a dedicated secure processor as
233well as the isolated execution environment described above.  Such a
234dedicated secure processor is called "StrongBox".  Requirements C-1-3
235through C-1-11 below define the requirements a device must meet to
236qualify as a StrongBox.
237
238Device implementations that have a dedicated secure processor:
239
240*    [C-SR] Are STRONGLY RECOMMENDED to support StrongBox. StrongBox will
241     likely become a requirement in a future release.
242
243If device implementations support StrongBox, they:
244
245*    [C-1-1] MUST declare [FEATURE_STRONGBOX_KEYSTORE](
246https://developer.android.com/reference/kotlin/android/content/pm/PackageManager#FEATURE_STRONGBOX_KEYSTORE%3Akotlin.String).
247
248*    [C-1-2] MUST provide dedicated secure hardware that is used to back
249keystore and secure user authentication.  The dedicated secure
250hardware may be used for other purposes as well.
251
252*    [C-1-3] MUST have a discrete CPU that shares no cache, DRAM, coprocessors
253or other core resources with the application processor (AP).
254
255*    [C-1-4] MUST ensure that any peripherals shared with the AP cannot alter
256StrongBox processing in any way, or obtain any information from the StrongBox.
257The AP MAY disable or block access to StrongBox.
258
259*    [C-1-5] MUST have an internal clock with reasonable accuracy (+-10%)
260that is immune to manipulation by the AP.
261
262*    [C-1-6] MUST have a true random number generator that produces
263uniformly-distributed and unpredictable output.
264
265*    [C-1-7] MUST have tamper resistance, including resistance against
266physical penetration, and glitching.
267
268*    [C-1-8] MUST have side-channel resistance, including resistance against
269leaking information via power, timing, electromagnetic radiation, and thermal
270radiation side channels.
271
272*    [C-1-9] MUST have secure storage which ensures confidentiality,
273integrity, authenticity, consistency, and freshness of the
274contents. The storage MUST NOT be able to be read or altered, except
275as permitted by the StrongBox APIs.
276
277*    To validate compliance with [C-1-3] through [C-1-9], device
278     implementations:
279
280    *    [C-1-10] MUST include the hardware that is certified against the
281         Secure IC Protection Profile [BSI-CC-PP-0084-2014](
282         https://www.commoncriteriaportal.org/files/ppfiles/pp0084b_pdf.pdf) or
283         evaluated by a nationally accredited testing laboratory incorporating
284         High attack potential vulnerability assessment according to the
285         [Common Criteria Application of Attack Potential to Smartcards](
286       https://www.commoncriteriaportal.org/files/supdocs/CCDB-2013-05-002.pdf).
287    *    [C-1-11] MUST include the firmware that is evaluated by a
288         nationally accredited testing laboratory incorporating High attack
289         potential vulnerability assessment according to the
290         [Common Criteria Application of Attack Potential to Smartcards](
291         https://www.commoncriteriaportal.org/files/supdocs/CCDB-2013-05-002.pdf).
292    *    [C-SR] Are STRONGLY RECOMMENDED to include the hardware that is
293         evaluated using a Security Target, Evaluation Assurance Level
294         (EAL) 5, augmented by AVA_VAN.5.  EAL 5 certification will likely
295         become a requirement in a future release.
296
297*    [C-SR] are STRONGLY RECOMMENDED to provide insider attack resistance (IAR),
298which means that an insider with access to firmware signing keys cannot produce
299firmware that causes the StrongBox to leak secrets, to bypass functional
300security requirements or otherwise enable access to sensitive user data. The
301recommended way to implement IAR is to allow firmware updates only when the
302primary user password is provided via the IAuthSecret HAL. IAR will likely
303become a requirement in a future release.
304