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