Merge "Make use of keystore and keymaster names consistent. Also fix bugs."
diff --git a/src/security/images/access-to-keymaster.png b/src/security/images/access-to-keymaster.png
index 611f8e3..5f27a31 100644
--- a/src/security/images/access-to-keymaster.png
+++ b/src/security/images/access-to-keymaster.png
Binary files differ
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
