| <html devsite> |
| <head> |
| <title>Hardware-backed Keystore</title> |
| <meta name="project_path" value="/_project.yaml" /> |
| <meta name="book_path" value="/_book.yaml" /> |
| </head> |
| <body> |
| <!-- |
| Copyright 2017 The Android Open Source Project |
| |
| Licensed under the Apache License, Version 2.0 (the "License"); |
| you may not use this file except in compliance with the License. |
| You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| |
| |
| <p>The availability of a trusted execution environment in a system on a chip (SoC) |
| offers an opportunity for Android devices to provide hardware-backed, strong |
| security services to the Android OS, to platform services, and even to |
| third-party apps. Developers seeking the Android-specific extensions should go |
| to <a |
| href="https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.html">android.security.keystore</a>.</p> |
| |
| <p>Before Android 6.0, Android already had a simple, hardware-backed crypto |
| services API, provided by versions 0.2 and 0.3 of the Keymaster Hardware |
| Abstraction Layer (HAL). Keystore provided digital signing and verification |
| operations, plus generation and import of asymmetric signing key pairs. This is |
| already implemented on many devices, but there are many security goals that |
| cannot easily be achieved with only a signature API. Keystore in Android 6.0 |
| extends the Keystore API to provide a broader range of capabilities.</p> |
| |
| <p>In Android 6.0, Keystore added <a href="/security/keystore/features.html">symmetric cryptographic |
| primitives</a>, AES and HMAC, and an access control system for hardware-backed |
| keys. Access controls are specified during key generation and enforced for the |
| lifetime of the key. Keys can be restricted to be usable only after the user has |
| authenticated, and only for specified purposes or with specified cryptographic |
| parameters. For more information, see the <a href="/security/keystore/tags">Authorization |
| Tags</a> and <a href="/security/keystore/implementer-ref">Functions</a> pages.</p> |
| |
| <p> |
| In Android 7.0, Keymaster 2 added support for key attestation and version binding. |
| <a href="/security/keystore/attestation">Key attestation</a> |
| provides public key certificates that contain a detailed |
| description of the key and its access controls, to make the key's existence in |
| secure hardware and its configuration remotely verifiable. |
| </p> |
| <p> |
| <a href="/security/keystore/version-binding">Version binding</a> |
| binds keys to operating system and patch |
| level version. This ensures that an attacker who discovers a weakness in an old |
| version of system or TEE software cannot roll a device back to the vulnerable |
| version and use keys created with the newer version. In addition, when a key |
| with a given version and patch level is used on a device that has been upgraded |
| to a newer version or patch level, the key is upgraded before it can be used, |
| and the previous version of the key invalidated. As the device is upgraded, the |
| keys "ratchet" forward along with the device, but any reversion of the device to |
| a previous release causes the keys to be unusable. |
| </p> |
| |
| <h2 id=goals>Goals</h2> |
| |
| <p>The Android 7.0 Keystore API and the underlying Keymaster HAL |
| provides a basic but adequate set of cryptographic primitives to allow the |
| implementation of protocols using access-controlled, hardware-backed keys.</p> |
| |
| <p>In addition to expanding the range of cryptographic primitives, Keystore in |
| Android 6.0 adds the following:</p> |
| |
| <ul> |
| <li>A usage control scheme to allow key usage to be limited, to mitigate the risk |
| of security compromise due to misuse of keys |
| <li>An access control scheme to enable restriction of keys to specified users, |
| clients, and a defined time range |
| </ul> |
| |
| <h2 id=architecture>Architecture</h2> |
| |
| <p>The Keymaster HAL is an OEM-provided, dynamically-loadable library used by the |
| Keystore service to provide hardware-backed cryptographic services. To keep |
| things secure, HAL implementations don't perform any sensitive operations in |
| user space, or even in kernel space. Sensitive operations are delegated to a |
| secure processor reached through some kernel interface. |
| The resulting architecture looks like this:</p> |
| |
| <div align="center"> |
| <img src="/security/images/access-to-keymaster.png" alt="Access to Keymaster" id="figure1" /> |
| </div> |
| <p class="img-caption"><strong>Figure 1.</strong> Access to Keymaster</p> |
| |
| <p>Within an Android device, the "client" of the Keymaster HAL consists of |
| multiple layers (e.g. app, framework, Keystore daemon), but that can be ignored |
| for the purposes of this document. This means that the described Keymaster HAL |
| API is low-level, used by platform-internal components, and not exposed to app |
| developers. The higher-level API, for API level 23, is described on the <a |
| href="https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.html">Android |
| Developer site</a>.</p> |
| |
| <p>The purpose of the Keymaster HAL is not to implement the security-sensitive |
| algorithms but only to marshal and unmarshal requests to the secure world. The |
| wire format is implementation-defined.</p> |
| |
| <h2 id=compatibility_with_previous_versions>Compatibility with previous versions</h2> |
| |
| <p>The Keymaster 1 HAL is completely incompatible with the |
| previously-released HALs, e.g. Keymaster 0.2 and 0.3. To facilitate |
| interoperability on devices running Android 5.0 and earlier that launched with |
| the older Keymaster HALs, Keystore provides an adapter that implements the |
| Keymaster 1 HAL with calls to the existing hardware library. The result cannot |
| provide the full range of functionality in the Keymaster 1 HAL. In particular, |
| it only supports RSA and ECDSA algorithms, and all of the key authorization |
| enforcement is performed by the adapter, in the non-secure world.</p> |
| |
| <p> |
| Keymaster 2 further simplified the HAL interface by removing the <code>get_supported_*</code> |
| methods and allowing the <code>finish()</code> method to accept input. This reduces the |
| number of round trips to the TEE in cases where the input is available all at |
| once, and simplifies implementation of AEAD decryption. |
| </p> |
| |
| </body> |
| </html> |