1 <html devsite> 2 <head> 3 <title>Hardware-backed Keystore</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 <p>The availability of a trusted execution environment in a system on a chip (SoC) 27 offers an opportunity for Android devices to provide hardware-backed, strong 28 security services to the Android OS, to platform services, and even to 29 third-party apps. Developers seeking the Android-specific extensions should go 30 to <a 31 href="https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.html">android.security.keystore</a>.</p> 32 33 <p>Keystore has been <a href="features.html">significantly enhanced</a> in 34 Android 6.0 with the addition of symmetric cryptographic primitives, AES and 35 HMAC, and the addition of an access control system for hardware-backed 36 keys. Access controls are specified during key generation and enforced for the 37 lifetime of the key. Keys can be restricted to be usable only after the user has 38 authenticated, and only for specified purposes or with specified cryptographic 39 parameters. For more information, please see the <a 40 href="implementer-ref.html">Implementer's Reference</a>.</p> 41 42 <p>Before Android 6.0, Android already had a simple, hardware-backed crypto 43 services API, provided by versions 0.2 and 0.3 of the Keymaster Hardware 44 Abstraction Layer (HAL). Keystore provided digital signing and verification 45 operations, plus generation and import of asymmetric signing key pairs. This is 46 already implemented on many devices, but there are many security goals that 47 cannot easily be achieved with only a signature API. Keystore in Android 6.0 48 extends the Keystore API to provide a broader range of capabilities.</p> 49 50 <h2 id=goals>Goals</h2> 51 52 <p>The goal of the Android 6.0 Keystore API and the underlying Keymaster 1.0 HAL 53 is to provide a basic but adequate set of cryptographic primitives to allow the 54 implementation of protocols using access-controlled, hardware-backed keys.</p> 55 56 <p>In addition to expanding the range of cryptographic primitives, Keystore in 57 Android 6.0 adds the following:</p> 58 59 <ul> 60 <li>A usage control scheme to allow key usage to be limited, to mitigate the risk 61 of security compromise due to misuse of keys 62 <li>An access control scheme to enable restriction of keys to specified users, 63 clients, and a defined time range 64 </ul> 65 66 <h2 id=architecture>Architecture</h2> 67 68 <p>The Keymaster HAL is an OEM-provided, dynamically-loadable library used by the 69 Keystore service to provide hardware-backed cryptographic services. HAL 70 implementations must not perform any sensitive operations in user space, or even 71 in kernel space. Sensitive operations are delegated to a secure processor 72 reached through some kernel interface. The resulting architecture looks 73 like the following:</p> 74 75 <div align="center"> 76 <img src="/security/images/access-to-keymaster.png" alt="Access to Keymaster" id="figure1" /> 77 </div> 78 <p class="img-caption"><strong>Figure 1.</strong> Access to Keymaster</p> 79 80 <p>Within an Android device, the "client" of the Keymaster HAL consists of 81 multiple layers (e.g. app, framework, Keystore daemon), but that can be ignored 82 for the purposes of this document. This means that the described Keymaster HAL 83 API is low-level, used by platform-internal components, and not exposed to app 84 developers. The higher-level API, for API level 23, is described on the <a 85 href="https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.html">Android 86 Developer site</a>.</p> 87 88 <p>The purpose of the Keymaster HAL is not to implement the security-sensitive 89 algorithms but only to marshal and unmarshal requests to the secure world. The 90 wire format is implementation-defined.</p> 91 92 <h2 id=compatibility_with_previous_versions>Compatibility with previous versions</h2> 93 94 <p>The Keymaster v1.0 HAL is completely incompatible with the 95 previously-released HALs, e.g. Keymaster v0.2 and v0.3. To facilitate 96 interoperability on pre-Marshmallow devices that launched with the older 97 Keymaster HALs, Keystore provides an adapter that implements the 1.0 HAL with 98 calls to the existing hardware library. The result cannot provide the full range 99 of functionality in the 1.0 HAL. In particular, it will only support RSA and 100 ECDSA algorithms, and all of the key authorization enforcement will be performed 101 by the adapter, in the non-secure world.</p> 102 103 </body> 104 </html> 105
