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/features.jd b/src/security/keystore/features.jd
index 7feae91..7d00ebb 100644
--- a/src/security/keystore/features.jd
+++ b/src/security/keystore/features.jd
@@ -24,11 +24,12 @@
</div>
</div>
-<p>This page contains information about the features of <a href="index.html">Keymaster</a> 1.0.</p>
+<p>This page contains information about the features of <a href="index.html">Keystore</a>
+in Android 6.0.</p>
<h2 id=cryptographic_primitives>Cryptographic primitives</h2>
-<p>The <code>libkeymaster</code> library and Keymaster provide the following categories of operations:</p>
+<p>Keystore provides the following categories of operations:</p>
<ul>
<li>Key generation
@@ -42,11 +43,6 @@
<li>Generation and verification of symmetric message authentication codes
</ul>
-<p>Within each category, <code>libkeymaster</code> provides a mechanism for
-discovering the available options (algorithms,
-modes, etc.). But we also specify at least one required option, to ensure that
-client software can depend on the presence of the required primitives.</p>
-
<p>Protocol elements, such as purpose, mode and padding, as well
as <a href="#key_access_control">access control constraints</a>,
must be specified when keys are generated or imported and are permanently
@@ -80,10 +76,10 @@
</ul>
<li>Required padding modes for RSA encryption/decryption are:
<ul>
+ <li>Unpadded
<li>RSAES-OAEP (<code>KM_PAD_RSA_OAEP</code>)
<li>RSAES-PKCS1-v1_5 (<code>KM_PAD_RSA_PKCS1_1_5_ENCRYPT</code>)
</ul>
- <li>Unpadded RSA encryption must not be supported
</ul>
<li><a href="http://en.wikipedia.org/wiki/Elliptic_Curve_DSA">ECDSA</a>
<ul>
@@ -125,17 +121,19 @@
<p>Hardware-based keys that can never be extracted from the device don't provide
much security if an attacker can use them at will (though they're more secure
-than keys which <em>can</em> be exfiltrated). Thus, it's crucial that Keymaster enforce access controls.</p>
+than keys which <em>can</em> be exfiltrated). Thus, it's crucial that Keystore
+enforce access controls.</p>
<p>Access controls are defined as an "authorization list" of tag/value pairs.
Authorization tags are 32-bit integers and the values are a variety of types.
Some tags may be repeated to specify multiple values. Whether a tag may be
repeated is specified in the documentation for the tag. When a key is created,
-the caller specifies an authorization list. The Keymaster implementation will
-modify the list to specify some additional information, such as whether the key
-has rollback protection, and return a "final" authorization list, encoded into
-the returned key blob. Any attempt to use the key for any cryptographic
-operation must fail if the final authorization list is modified.</p>
+the caller specifies an authorization list. The Keymaster implementation
+underlying Keystore will modify the list to specify some additional information,
+such as whether the key has rollback protection, and return a "final"
+authorization list, encoded into the returned key blob. Any attempt to use the
+key for any cryptographic operation must fail if the final authorization list is
+modified.</p>
<p>The set of possible tags is defined in the enumeration <code>keymaster_authorization_tag_t</code> and
the set must be permanently fixed (though it can be extended).
@@ -176,42 +174,46 @@
<h3 id=hardware_vs_software_enforcement>Hardware vs. software enforcement</h3>
-<p>Not all Keymaster implementations will implement the same features. To support
-a variety of approaches, Keymaster 1.0 distinguishes between secure and
-non-secure world access control enforcement, which we call hardware and
-software enforcement, respectively.</p>
+<p>Not all secure hardware will implement the same features. To support a
+variety of approaches, Keymaster 1.0 distinguishes between secure and non-secure
+world access control enforcement, which we call hardware and software
+enforcement, respectively.</p>
<p>Implementations are required to:</p>
<ul>
- <li>Enforce exact matching (not enforcement) of all authorizations. Authorization
-lists in key blobs must exactly match the authorizations returned during key
-generation, including ordering. Any mismatch must cause an error diagnostic.
+
+ <li>Enforce exact matching (not enforcement) of all authorizations.
+ Authorization lists in key blobs must exactly match the authorizations
+ returned during key generation, including ordering. Any mismatch must cause an
+ error diagnostic.
+
<li>Declare the authorizations whose semantic values are enforced.
+
</ul>
-<p>The API mechanism for declaring hardware-enforced authorizations is in
-the <code>keymaster_key_characteristics_t</code> structure. It divides the authorization
-list into two sub-lists, <code>hw_enforced</code> and <code>sw_enforced</code>. The
-Keymaster implementation is responsible for placing the appropriate
-values in each, based on what it can enforce.</p>
+<p>The API mechanism for declaring hardware-enforced authorizations is in the
+<code>keymaster_key_characteristics_t</code> structure. It divides the
+authorization list into two sub-lists, <code>hw_enforced</code> and
+<code>sw_enforced</code>. The secure hardware is responsible for placing the
+appropriate values in each, based on what it can enforce.</p>
-<p>In addition, the keystore daemon will implement software-based enforcement of <em>all</em> authorizations,
-whether they're enforced in hardware or not.</p>
+<p>In addition, Keystore implements software-based enforcement of <em>all</em>
+authorizations, whether they're enforced by the secure hardware or not.</p>
<p>For example, consider a TrustZone-based implementation that does not support
key expiration. A key with an expiration date may still be created. That key's
-authorization list will include the tag <code>KM_TAG_ORIGINATION_EXPIRE_DATETIME</code> with
-the expiration date. A request to Keymaster for the key characteristics
-will find this tag in the <code>sw_enforced</code> list and the Keymaster implementation will
-not enforce the expiration
-requirement. However, attempts to use the key after expiration will be rejected
-by the keystore daemon.</p>
+authorization list will include the tag
+<code>KM_TAG_ORIGINATION_EXPIRE_DATETIME</code> with the expiration date. A
+request to Keystore for the key characteristics will find this tag in the
+<code>sw_enforced</code> list and the secure hardware will not enforce the
+expiration requirement. However, attempts to use the key after expiration will
+be rejected by Keystore.</p>
-<p>If the device is then upgraded with a Keymaster implementation that does
-support expiration, then a request for key characteristics will
-find <code>KM_TAG_ORIGINATION_EXPIRE_DATETIME</code> in
-the <code>hw_enforced</code> list, and attempts to use the key after expiration will fail even if the
+<p>If the device is then upgraded with secure hardware that does support
+expiration, then a request for key characteristics will find
+<code>KM_TAG_ORIGINATION_EXPIRE_DATETIME</code> in the <code>hw_enforced</code>
+list, and attempts to use the key after expiration will fail even if the
keystore is somehow subverted or bypassed.</p>
<h3 id=cryptographic_message_construction_authorizations>Cryptographic message construction authorizations</h3>
@@ -241,15 +243,6 @@
encrypt and to sign allows an attacker who can convince the system to decrypt
arbitrary data to generate signatures.</p>
-<p>Other purposes for keys that may be added in the future include:</p>
-
-<ul>
- <li>"Derive Key" purpose, for key derivation keys
- <li>"Attest" purpose, for keys that can generate attestations of the Keymaster
-implementation and/or its environment
- <li>"Wrap Key" purpose, for keys used to wrap keys for secure import or export
-</ul>
-
<h3 id=import_and_export>Import and export</h3>
<p>Keymaster supports export of public keys only, in X.509 format, and import of:</p>
@@ -260,8 +253,6 @@
<li>Symmetric keys as raw bytes
</ul>
-<p>Future versions will likely expand the import/export options.</p>
-
<p>To ensure that imported keys can be distinguished from securely-generated
keys, <code>KM_TAG_ORIGIN</code> is included in the appropriate key
authorization list. For example, if a key
@@ -273,9 +264,9 @@
<h3 id=user_authentication>User authentication</h3>
-<p>Keymaster does not implement user authentication, but depends on other trusted
-apps which do. For the interface that must be implemented by these apps, see
-the Gatekeeper page.</p>
+<p>Secure Keymaster implementations do not implement user authentication, but
+depend on other trusted apps which do. For the interface that must be
+implemented by these apps, see the Gatekeeper page.</p>
<p>User authentication requirements are specified via two sets of tags. The first
set indicate which user can use the key:</p>
@@ -313,24 +304,29 @@
<h3 id=client_binding>Client binding</h3>
-<p>Client binding, the association of a key with a particular client application,
-is done via an optional client ID and some optional client data (<code>KM_TAG_APPLICATION_ID</code>
-and <code>KM_TAG_APPLICATION_DATA</code>, respectively). Keymaster treats these values as opaque blobs,
-only ensuring
-that the same blobs presented during key generation/import are presented for
-every use and are byte-for-byte identical. The client binding data is not
-returned by Keymaster. The caller must know it in order to use the key.</p>
+<p>Client binding, the association of a key with a particular client
+application, is done via an optional client ID and some optional client data
+(<code>KM_TAG_APPLICATION_ID</code> and <code>KM_TAG_APPLICATION_DATA</code>,
+respectively). Keystore treats these values as opaque blobs, only ensuring that
+the same blobs presented during key generation/import are presented for every
+use and are byte-for-byte identical. The client binding data is not returned by
+Keymaster. The caller must know it in order to use the key.</p>
+
+<p>This feature is not exposed to applications.
<h3 id=expiration>Expiration</h3>
-<p>Keymaster supports restricting key usage by date. Key start of validity and key
-expirations can be associated with a key and Keymaster will refuse to perform
-key operations if the current date/time is outside of the valid range. The key
-validity range is specified with the tags <code>KM_TAG_ACTIVE_DATETIME</code>,
-<code>KM_TAG_ORIGINATION_EXPIRE_DATETIME</code>, and <code>KM_TAG_USAGE_EXPIRE_DATETIME</code>.
-The distinction between "origination" and "usage" is based on whether the key
-is being used to "originate" a new ciphertext/signature/etc., or to "use" an
-existing ciphertext/signature/etc.</p>
+<p>Keystore supports restricting key usage by date. Key start of validity and
+key expirations can be associated with a key and Keymaster will refuse to
+perform key operations if the current date/time is outside of the valid
+range. The key validity range is specified with the tags
+<code>KM_TAG_ACTIVE_DATETIME</code>,
+<code>KM_TAG_ORIGINATION_EXPIRE_DATETIME</code>, and
+<code>KM_TAG_USAGE_EXPIRE_DATETIME</code>. The distinction between
+"origination" and "usage" is based on whether the key is being used to
+"originate" a new ciphertext/signature/etc., or to "use" an existing
+ciphertext/signature/etc. Note that this distinction is not exposed to
+applications.</p>
<p>The <code>KM_TAG_ACTIVE_DATETIME</code>, <code>KM_TAG_ORIGINATION_EXPIRE_DATETIME</code>,
and <code>KM_TAG_USAGE_EXPIRE_DATETIME</code> tags are optional. If the tags are absent, it is
@@ -345,37 +341,38 @@
<h3 id=root_of_trust_binding>Root of trust binding</h3>
-<p>Keymaster allows keys to be bound to a root of trust, which is a bitstring
-provided to Keymaster during startup, preferably by the bootloader. If
-provided, this bitstring must be cryptographically bound to every key managed
+<p>Keystore requires keys to be bound to a root of trust, which is a bitstring
+provided to the Keymaster secure hardware during startup, preferably by the
+bootloader. This bitstring must be cryptographically bound to every key managed
by Keymaster.</p>
-<p>The intent is for the bootloader to pass in the public key, used to verify the
-signature on the boot image, along with the verified boot state (locked or
-unlocked). If the public key is changed to allow a different system image to be
-used or if the verified boot state is changed, then none of the
-Keymaster-protected keys created by the previous system will be usable, unless
-the previous root of trust is restored and a system that is signed by that key
-is booted. The goal is to increase the value of the software-enforced key
-access controls by making it imposSTEM</code>sible for an attacker-installed operating
-system to use Keymaster keys.</p>
+<p>The root of trust consists of the public key used to verify the signature on
+the boot image and the lock state of the device. If the public key is changed to
+allow a different system image to be used or if the lock state is changed, then
+none of the Keymaster-protected keys created by the previous system will be
+usable, unless the previous root of trust is restored and a system that is
+signed by that key is booted. The goal is to increase the value of the
+software-enforced key access controls by making it impossible for an
+attacker-installed operating system to use Keymaster keys.</p>
<h3 id=standalone_keys>Standalone keys</h3>
-<p>Some Keymaster implementations may choose to store key material internally and
-return handles rather than encrypted key material. Or there may be other cases
-in which keys cannot be used until some other non-secure or secure world system
-component is available. The Keymaster 1.0 API allows the caller to request that
-a key be "standalone," via the <code>KM_TAG_STANDALONE</code> tag,
-meaning that no resources other than the blob and the running Keymaster
-system are required. The tags associated with a key may be inspected to see
-whether a key is standalone. At present, only two values are defined:</p>
+<p>Some Keymaster secure hardware may choose to store key material internally
+and return handles rather than encrypted key material. Or there may be other
+cases in which keys cannot be used until some other non-secure or secure world
+system component is available. The Keymaster 1.0 HAL allows the caller to
+request that a key be "standalone," via the <code>KM_TAG_STANDALONE</code> tag,
+meaning that no resources other than the blob and the running Keymaster system
+are required. The tags associated with a key may be inspected to see whether a
+key is standalone. At present, only two values are defined:</p>
<ul>
<li><code>KM_BLOB_STANDALONE</code>
<li><code>KM_BLOB_REQUIRES_FILE_SYSTEM</code>
</ul>
+<p>This feature is not exposed to applications.
+
<h3 id=velocity>Velocity</h3>
<p>When it's created, the maximum usage velocity can be specified
@@ -387,26 +384,32 @@
<p>The simple approach to implementing velocity limits is a table of key IDs and
last-use timestamps. This table will likely be of limited size, but must
accommodate at least 16 entries. In the event that the table is full and no
-entries may be updated or discarded, Keymaster implementations must "fail
-safe," preferring to refuse all velocity-limited key operations until one of
-the entries expires. It is acceptable for all entries to expire upon reboot.</p>
+entries may be updated or discarded, secure hardware implementations must "fail
+safe," preferring to refuse all velocity-limited key operations until one of the
+entries expires. It is acceptable for all entries to expire upon reboot.</p>
-<p>Keys can also be limited to <em>n</em> uses per boot with <code>KM_TAG_USES_PER_BOOT</code>.
-This also requires a tracking table, which must accommodate at least four
-keys, and must also fail safe. Note that applications will be unable to create
-per-boot limited keys. This feature will not be exposed through keystore and
-will be reserved for system operations.</p>
+<p>Keys can also be limited to <em>n</em> uses per boot with
+<code>KM_TAG_MAX_USES_PER_BOOT</code>. This also requires a tracking table,
+which must accommodate at least four keys, and must also fail safe. Note that
+applications will be unable to create per-boot limited keys. This feature will
+not be exposed through Keystore and will be reserved for system operations.</p>
+
+<p>This feature is not exposed to applications.</p>
<h3 id=random_number_generator_re-seeding>Random number generator re-seeding</h3>
-<p>Because Keymaster must generate random numbers for key material and
+<p>Because secure hardware must generate random numbers for key material and
Initialization Vectors (IVs), and because hardware random number generators may
-not always be fully trustworthy, Keymaster provides an interface to allow the
-client to provide additional entropy which will be mixed into the random
-numbers generated.</p>
+not always be fully trustworthy, the Keymaster HAL provides an interface to
+allow the client to provide additional entropy which will be mixed into the
+random numbers generated.</p>
-<p>A hardware random-number generator should be used as the primary seed source,
-if available, and the seed data provided through the external API must not be
-the sole source of randomness used for number generation. Further, the mixing
-operation used must ensure that the random output is unpredictable if any one
-of the seed sources is unpredictable.</p>
+<p>A hardware random-number generator must be used as the primary seed source,
+and the seed data provided through the external API must not be the sole source
+of randomness used for number generation. Further, the mixing operation used
+must ensure that the random output is unpredictable if any one of the seed
+sources is unpredictable.</p>
+
+<p>This feature is not exposed to applications but is used by the framework,
+which regularly provides additional entropy, retrieved from a Java SecureRandom
+instance, to the secure hardware.
diff --git a/src/security/keystore/implementer-ref.jd b/src/security/keystore/implementer-ref.jd
index ba8c45a..7375651 100644
--- a/src/security/keystore/implementer-ref.jd
+++ b/src/security/keystore/implementer-ref.jd
@@ -18,7 +18,7 @@
-->
<p>This page provides details to assist implementers of <a href="index.html">Keymaster</a> HALs. It
-covers each tag and each function in the API.</p>
+covers each tag and each function in the HAL.</p>
<h2 id=authorization_tags>Authorization tags</h2>
@@ -341,7 +341,13 @@
<h3 id=km_tag_user_auth_type>KM_TAG_USER_AUTH_TYPE</h3>
<p>Specifies the types of user authenticators that may be used to authorize this
-key.</p>
+key. When Keymaster is requested to perform an operation with a key with this
+tag, it must receive an authentication token, and the token's
+<code>authenticator_type</code> field must match the value in the tag. To be
+precise, it must be true that <code>(ntoh(token.authenticator_type) &
+auth_type_tag_value) != 0, where <code>ntoh</code> is a function that converts
+network-ordered integers to host-ordered integers and
+<code>auth_type_tag_value</code> is the value of this tag.</p>
<p>The value is a 32-bit integer bitmask of values from the enumeration:</p>
@@ -388,6 +394,11 @@
same associated data as part of the <code>in_params</code> set. If the correct
data is not provided the function must return <code>KM_ERROR_INVALID_KEY_BLOB</code>.</p>
+<p>The content of this tag must be bound to the key <i>cryptographically</i>,
+meaning it must not be possible for an adversary who has access to all of the
+secure world secrets but does not have access to the tag content to decrypt the
+key (without brute-forcing the tag content).</p>
+
<p>The value is a blob, an arbitrary-length array of bytes.</p>
<p>This tag is not repeatable.</p>
@@ -403,6 +414,14 @@
data as part of the <code>in_params</code> set. If the correct data is not
provided, the function must return <code>KM_ERROR_INVALID_KEY_BLOB</code>.</p>
+<p>The content of this tag must be bound to the key <i>cryptographically</i>,
+meaning it must not be possible for an adversary who has access to all of the
+secure world secrets but does not have access to the tag content to decrypt the
+key (without brute-forcing the tag content, which applications can prevent by
+specifying sufficiently high-entropy content).</p>
+
+<p>The value is a blob, an arbitrary-length array of bytes.</p>
+
<p>This tag is not repeatable.</p>
<h3 id=km_tag_creation_datetime>KM_TAG_CREATION_DATETIME</h3>
@@ -911,11 +930,26 @@
<p>Begins a cryptographic operation, using the specified key, for the specified
purpose, with the specified parameters (as appropriate), and returns an
-operation handle which is used with <a href="#update">update</a> and <a href="#finish">finish</a> to complete the operation.</p>
+operation handle which is used with <a href="#update">update</a> and <a
+href="#finish">finish</a> to complete the operation. The operation handle is
+also used as the "challenge" token in authenticated operations, and for such
+operations must be included in the <code>challenge</code> field of the
+authentication token.</p>
-<p>If <a href="#km_tag_application_id">KM_TAG_APPLICATION_ID</a> or <a href="#km_tag_application_data">KM_TAG_APPLICATION_DATA</a>
-were specified during key generation or import, calls to begin must include
-those tags with the originally-specified values in the <code>in_params</code> argument to this method.</p>
+<p>A Keymaster implementation must support at least 16 concurrent
+operations. Keystore will use up to 15, leaving one for vold to use for password
+encryption. When Keystore has 15 operations in progress (<code>begin</code> has
+been called, but <code>finish</code> or <code>abort</code> have not yet been
+called) and it receives a request to begin a 16th, it will call
+<code>abort</code> on the least-recently used operation to reduce the number of
+active operations to 14 before calling <code>begin</code> to start the
+newly-requested operation.
+
+<p>If <a href="#km_tag_application_id">KM_TAG_APPLICATION_ID</a> or <a
+href="#km_tag_application_data">KM_TAG_APPLICATION_DATA</a> were specified
+during key generation or import, calls to <code>begin</code> must include those
+tags with the originally-specified values in the <code>in_params</code> argument
+to this method.</p>
<h4 id=authorization_enforcement>Authorization enforcement</h4>
@@ -998,18 +1032,34 @@
<p>There are some important interactions between padding modes and digests:</p>
<ul>
- <li><code>KM_PAD_NONE</code> indicates that a "raw" RSA operation will be performed. If signing or
-verifying, <code>KM_DIGEST_NONE </code>must be specified for the digest. No digest is required for unpadded encryption
-or decryption.
- <li><code>KM_PAD_RSA_PKCS1_1_5_SIGN</code> padding requires a digest, which may be <code>KM_DIGEST_NONE.</code>
+
+ <li><code>KM_PAD_NONE</code> indicates that a "raw" RSA operation will be
+ performed. If signing or verifying, <code>KM_DIGEST_NONE</code> must be
+ specified for the digest. No digest is required for unpadded encryption or
+ decryption.
+
+ <li><code>KM_PAD_RSA_PKCS1_1_5_SIGN</code> padding requires a digest. The
+ digest may be <code>KM_DIGEST_NONE</code>, in which case the Keymaster
+ implementation cannot build a proper PKCS#1 v1.5 signature structure, because
+ it cannot add the DigestInfo structure. Instead, the implementation must
+ construct <code>0x00 || 0x01 || PS || 0x00 || M</code>, where M is the
+ provided message and PS is the padding string. The size of the RSA key must be
+ at least 11 bytes larger than the message, otherwise the method must return
+ <code>KM_ERROR_INVALID_INPUT_LENGTH</code>.
+
<li><code>KM_PAD_RSA_PKCS1_1_1_5_ENCRYPT</code> padding does not require a digest.
- <li><code>KM_PAD_RSA_PSS</code> padding requires a digest, which may not be <code>KM_DIGEST_NONE</code>.
- If <code>KM_DIGEST_NONE</code> is specified, the method must return
- <code>KM_ERROR_INCOMPATIBLE_PADDING_MODE</code>. In addition, the
- size of the RSA key must be at least 22 bytes larger than
-the output size of the digest. Otherwise, the method must return <code>KM_ERROR_INCOMPATIBLE_DIGEST</code>.
- <li><code>KM_PAD_RSA_OAEP</code> padding requires a digest, which may not be <code>KM_DIGEST_NONE</code>.
- If <code>KM_DIGEST_NONE</code> is specified, the method must return <code>KM_ERROR_INCOMPATIBLE_DIGEST</code>.
+
+ <li><code>KM_PAD_RSA_PSS</code> padding requires a digest, which may not be
+ <code>KM_DIGEST_NONE</code>. If <code>KM_DIGEST_NONE</code> is specified, the
+ method must return <code>KM_ERROR_INCOMPATIBLE_DIGEST</code>. In addition, the
+ size of the RSA key must be at least 22 bytes larger than the output size of
+ the digest. Otherwise, the method must return
+ <code>KM_ERROR_INCOMPATIBLE_DIGEST</code>.
+
+ <li><code>KM_PAD_RSA_OAEP</code> padding requires a digest, which may not be
+ <code>KM_DIGEST_NONE</code>. If <code>KM_DIGEST_NONE</code> is specified, the
+ method must return <code>KM_ERROR_INCOMPATIBLE_DIGEST</code>.
+
</ul>
<h4 id=ec_keys>EC keys</h4>
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