Make use of keystore and keymaster names consistent. Also fix bugs.
The documentation often says "keymaster" where it shoud say "keystore", and
when it correctly says "keymaster" it often fails to distinguish between
the keymaster HAL and the underlying secure hardware. In addition,
there are a number of content errors identified by partners in the
process of implementing the keymaster specification. This CL updates the
documentation to correct both of those issues.
Change-Id: Iba4d75493c5a419a1ddf7aeeafc13a7dd53f6b46
diff --git a/src/security/keystore/index.jd b/src/security/keystore/index.jd
index e86f253..d05d3f8 100644
--- a/src/security/keystore/index.jd
+++ b/src/security/keystore/index.jd
@@ -29,32 +29,31 @@
security services to the Android OS, to platform services, and even to
third-party apps.</p>
-<p>Keymaster has been <a href="features.html">significantly enhanced</a>
-in Android 6.0 with the addition of symmetric cryptographic primitives,
-AES and HMAC, and the addition of 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, only at a specific usage
-velocity, and only for specified purposes or with specified cryptographic
-parameters. For more information, please see
-the <a href="implementer-ref.html">Implementer's Reference</a>.</p>
+<p>Keystore has been <a href="features.html">significantly enhanced</a> in
+Android 6.0 with the addition of symmetric cryptographic primitives, AES and
+HMAC, and the addition of 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, please see the <a
+href="implementer-ref.html">Implementer's Reference</a>.</p>
-<p>Before Keymaster 1.0, Android already had a simple, hardware-backed crypto
-services API: Keymaster versions 0.2 and 0.3, which provided only digital
-signing and verification operations, plus generation 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. The intent of Keymaster 1.0 is to
-extend the Keymaster API to provide a broader range of capabilities.</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>
<h2 id=goals>Goals</h2>
-<p>The goal of the Keymaster API is to provide a basic but adequate set of
-cryptographic primitives to allow the implementation of protocols using
-access-controlled, hardware-backed keys.</p>
+<p>The goal of the Android 6.0 Keystore API and the underlying Keymaster 1.0 HAL
+is to provide 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, Keymaster v1.0
-adds the following:</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
@@ -65,36 +64,37 @@
<h2 id=architecture>Architecture</h2>
-<p>The Keymaster API is a Hardware Abstraction Layer module, which is a
-dynamically-loaded library. Implementations must not
-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 something like the
-following:</p>
+<p>The Keymaster HAL is an OEM-provided, dynamically-loadable library used by the
+Keystore service to provide hardware-backed cryptographic services. HAL
+implementations must not 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 the following:</p>
-<img src="../images/access-to-keymaster.png" alt="Access to Keymaster" id="figure1" />
+<div align="center">
+ <img src="../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" actually 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 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="http://developer.android.com/reference/java/security/KeyStore.html">Android Developer site</a>.</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="http://developer.android.com/reference/java/security/KeyStore.html">Android
+Developer site</a>.</p>
-<p>The purpose of the <code>libkeymaster</code> library 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>
+<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 v1.0 API is completely incompatible with the previously-released
-APIs, e.g. Keymaster v0.2 and v0.3.
-To facilitate interoperability on pre-Marshmallow devices that launched
-with the older Keymaster APIs, Keystore provides an adapter that provides
-the 1.0 API implemented with calls to the existing hardware library. The result
-cannot provide the full range of functionality in the
-1.0 API. In particular, it will only support RSA and ECDSA algorithms, and all
-of the key authorization enforcement will be performed by the adapter, in the
-non-secure world.</p>
+<p>The Keymaster v1.0 HAL is completely incompatible with the
+previously-released HALs, e.g. Keymaster v0.2 and v0.3. To facilitate
+interoperability on pre-Marshmallow devices that launched with the older
+Keymaster HALs, Keystore provides an adapter that implements the 1.0 HAL with
+calls to the existing hardware library. The result cannot provide the full range
+of functionality in the 1.0 HAL. In particular, it will only support RSA and
+ECDSA algorithms, and all of the key authorization enforcement will be performed
+by the adapter, in the non-secure world.</p>
\ No newline at end of file