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.