Docs: Addition of Keymaster 1.0 document
Bug: 19317987
Change-Id: I5a8cf49116d2045ea28b6dc475c37d58cc44b6d0
diff --git a/src/devices/tech/security/authentication/keymaster.jd b/src/devices/tech/security/authentication/keymaster.jd
new file mode 100644
index 0000000..8febf76
--- /dev/null
+++ b/src/devices/tech/security/authentication/keymaster.jd
@@ -0,0 +1,100 @@
+page.title=Keymaster
+@jd:body
+
+<!--
+ Copyright 2015 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>The availability of a trusted execution environment in a system on a chip (SoC)
+offers an opportunity for Android devices to provide hardware-backed, strong
+security services to the Android OS, to platform services, and even to
+third-party apps.</p>
+
+<p>Keymaster has been <a href="km-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="km-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>
+
+<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>In addition to expanding the range of cryptographic primitives, Keymaster v1.0
+adds the following:</p>
+
+<ul>
+ <li>A usage control scheme to allow key usage to be limited, to mitigate the risk
+of security compromise due to misuse of keys
+ <li>An access control scheme to enable restriction of keys to specified users,
+clients, and a defined time range
+</ul>
+
+<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>
+
+<img src="../images/access-to-keymaster.png" alt="Access to Keymaster" id="figure1" />
+<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>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>
+
+<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>
diff --git a/src/devices/tech/security/authentication/km-features.jd b/src/devices/tech/security/authentication/km-features.jd
new file mode 100644
index 0000000..2b469c9
--- /dev/null
+++ b/src/devices/tech/security/authentication/km-features.jd
@@ -0,0 +1,412 @@
+page.title=Features
+@jd:body
+
+<!--
+ Copyright 2015 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>This page contains information about the features of <a href="keymaster.html">Keymaster</a> 1.0.</p>
+
+<h2 id=cryptographic_primitives>Cryptographic primitives</h2>
+
+<p>The <code>libkeymaster</code> library and Keymaster provide the following categories of operations:</p>
+
+<ul>
+ <li>Key generation
+ <li>Import and export of asymmetric keys (no key wrapping)
+ <li>Import of raw symmetric keys (again, no wrapping)
+ <li>Asymmetric encryption and decryption with appropriate padding modes
+ <li>Asymmetric signing and verification with digesting and appropriate padding
+modes
+ <li>Symmetric encryption and decryption in appropriate modes, including an AEAD
+mode
+ <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
+bound to the key, ensuring the key cannot be used in any other way.</p>
+
+<p>In addition to the list above, there is one more service that Keymaster
+implementations must provide but which is not exposed as an API: Random number
+generation. This is used internally for generation of keys, Initialization
+Vectors (IVs), random padding and other elements of secure protocols that
+require randomness.</p>
+
+<h2 id=required_primitives>Required primitives</h2>
+
+<p>All implementations must provide:</p>
+
+<ul>
+ <li><a href="http://en.wikipedia.org/wiki/RSA_(cryptosystem)">RSA</a>
+ <ul>
+ <li>2048, 3072 and 4096-bit key support are required
+ <li>Support for public exponent F4 (2^16+1)
+ <li>Required padding modes for RSA signing are:
+ <ul>
+ <li>No padding (deprecated, will be removed in the future)
+ <li>RSASSA-PSS (<code>KM_PAD_RSA_PSS</code>)
+ <li>RSASSA-PKCS1-v1_5 (<code>KM_PAD_RSA_PKCS1_1_5_SIGN</code>)
+ </ul>
+ <li>Required digest modes for RSA signing are:
+ <ul>
+ <li>No digest (deprecated, will be removed in the future)
+ <li>SHA-256
+ </ul>
+ <li>Required padding modes for RSA encryption/decryption are:
+ <ul>
+ <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>
+ <li>224, 256, 384 and 521-bit key support are required, using the NIST P-224,
+P-256, P-384 and P-521 curves, respectively
+ <li>Required digest modes for ECDSA are:
+ <ul>
+ <li>No digest (deprecated, will be removed in the future)
+ <li>SHA-256
+ </ul>
+ </ul>
+ <li><a href="http://en.wikipedia.org/wiki/Advanced_Encryption_Standard">AES</a>
+ <ul>
+ <li>128 and 256-bit keys are required
+ <li><a href="http://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Cipher-block_chaining_.28CBC.29">CBC</a>,
+ CTR, ECB and and GCM. The GCM implementation must not allow the use of tags
+smaller than 96 bits or nonce lengths other than 96 bits.
+ <li>Padding modes <code>KM_PAD_NONE</code> and <code>KM_PAD_PKCS7</code> must
+ be supported for CBC and ECB modes. With no padding, CBC or ECB mode
+encryption must fail if the input isn't a multiple of the block size.
+ </ul>
+ <li><a href="http://en.wikipedia.org/wiki/Hash-based_message_authentication_code">HMAC</a>
+ <a href="http://en.wikipedia.org/wiki/SHA-2">SHA-256</a>, with any key size up to at least 32 bytes.
+</ul>
+</ul>
+
+<p>SHA1 and the other members of the SHA2 family (SHA-224, SHA384 and SHA512) are
+strongly recommended, but not required. Keystore will provide them in software
+if the hardware Keymaster implementation doesn't provide them.</p>
+
+<p>Some primitives are also recommended for interoperability with other systems:</p>
+
+<ul>
+ <li>Smaller key sizes for RSA
+ <li>Arbitrary public exponents for RSA
+</ul>
+
+<h2 id=key_access_control>Key access control</h2>
+
+<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>
+
+<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>
+
+<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).
+Names are prefixed with <code>KM_TAG_</code>. The top
+four bits of tag IDs are used to indicate the type.</p>
+
+<p>Possible types include:</p>
+
+<p><strong><code>KM_ENUM</code>:</strong> Many tags' values are defined in enumerations. For example, the possible
+values of <code>KM_TAG_PURPOSE</code> are defined in enum <code>keymaster_purpose_t</code>.</p>
+
+<p><strong><code>KM_ENUM_REP</code></strong>: Same as <code>KM_ENUM</code>, except that the tag may
+be repeated in an authorization list. Repetition
+indicates multiple authorized values. For example, an encryption key will
+likely have <code>KM_PURPOSE_ENCRYPT</code> and <code>KM_PURPOSE_DECRYPT</code>.</p>
+
+<p><strong><code>KM_UINT</code>:</strong> 32-bit unsigned integers. Example: <code>KM_TAG_KEY_SIZE</code></p>
+
+<p><strong><code>KM_UINT_REP</code></strong>: Same as <code>KM_UINT</code>, except that the tag may be
+repeated in an authorization list. Repetition indicates multiple authorized values.</p>
+
+<p><strong><code>KM_ULONG</code></strong>: 64-bit unsigned integers. Example: <code>KM_TAG_RSA_PUBLIC_EXPONENT</code></p>
+
+<p><strong><code>KM_ULONG_REP</code></strong>: Same as <code>KM_ULONG</code>, except that the tag may be
+repeated in an authorization list. Repetition
+indicates multiple authorized values.</p>
+
+<p><strong><code>KM_DATE</code></strong>: Date/time values, expressed as milliseconds since January 1, 1970.
+Example: <code>KM_TAG_PRIVKEY_EXPIRE_DATETIME</code></p>
+
+<p><strong><code>KM_BOOL</code></strong>: True or false. A tag of type <code>KM_BOOL</code> is assumed
+to be "false" if the tag is not present and "true" if present. Example: <code>KM_TAG_ROLLBACK_RESISTANT</code></p>
+
+<p><strong><code>KM_BIGNUM</code></strong>: Arbitrary-length integers, expressed as a byte array
+in big-endian order. Example: <code>KM_TAG_RSA_PUBLIC_EXPONENT</code></p>
+
+<p><strong><code>KM_BYTES</code></strong>: A sequence of bytes. Example: <code>KM_TAG_ROOT_OF_TRUST</code></p>
+
+<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>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>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>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>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>
+
+<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
+keystore is somehow subverted or bypassed.</p>
+
+<h3 id=cryptographic_message_construction_authorizations>Cryptographic message construction authorizations</h3>
+
+<p>The following tags are used to define the cryptographic characteristics of
+operations using the associated key: <code>KM_TAG_ALGORITHM</code>, <code>KM_TAG_KEY_SIZE</code>,
+<code>KM_TAG_BLOCK_MODE</code>, <code>KM_TAG_PADDING</code>, <code>KM_TAG_CALLER_NONCE</code>, and <code>KM_TAG_DIGEST</code></p>
+
+<p><code>KM_TAG_PADDING</code>, <code>KM_TAG_DIGEST</code>, and <code>KM_PAD_BLOCK_MODE</code>
+are repeatable, meaning that multiple values may be associated with a single
+key, and the value to be used will be specified at operation time.</p>
+
+<h3 id=purpose>Purpose</h3>
+
+<p>Keys have an associated set of purposes, expressed as one or more authorization
+entries with tag <code>KM_TAG_PURPOSE</code>, which defines how they can be used. The purposes are:</p>
+
+<ul>
+ <li><code>KM_PURPOSE_ENCRYPT</code>
+ <li><code>KM_PURPOSE_DECRYPT</code>
+ <li><code>KM_PURPOSE_SIGN</code>
+ <li><code>KM_PURPOSE_VERIFY</code>
+</ul>
+
+<p>Any key can have any subset of these purposes. Note that some combinations
+create security problems. For example, an RSA key that can be used to both
+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>
+
+<ul>
+ <li>Public and private key pairs in DER-encoded PKCS#8 format, without
+password-based encryption, and
+ <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
+was generated in secure hardware, <code>KM_TAG_ORIGIN</code> with
+value <code>KM_ORIGIN_GENERATED</code> will be found in
+the <code>hw_enforced</code> list of the key characteristics, while a key
+that was imported into secure
+hardware will have the value <code>KM_ORIGIN_IMPORTED</code>.</p>
+
+<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>User authentication requirements are specified via two sets of tags. The first
+set indicate which user can use the key:</p>
+
+<ul>
+ <li><code>KM_TAG_ALL_USERS</code> indicates the key is usable by all users. If
+ present, <code>KM_TAG_USER_ID</code> and <code>KM_TAG_SECURE_USER_ID</code> must not be present.
+ <li><code>KM_TAG_USER_ID</code> has a numeric value specifying the ID of the authorized user.
+ Note that this
+is the Android user ID (for multi-user), not the application UID, and it is
+enforced by non-secure software only. If present, <code>KM_TAG_ALL_USERS</code> must not be present.
+ <li><code>KM_TAG_SECURE_USER_ID</code> has a 64-bit numeric value specifying the secure user ID
+ that must be provided
+in a secure authentication token to unlock use of the key. If repeated, the key
+may be used if any of the values is provided in a secure authentication token.
+</ul>
+
+<p>The second set indicate whether and when the user must be authenticated. If
+neither of these tags is present, but <code>KM_TAG_SECURE_USER_ID</code> is, authentication is
+required for every use of the key.</p>
+
+<ul>
+ <li><code>KM_NO_AUTHENTICATION_REQUIRED</code> indicates no user authentication is required, though
+ the key still may only be
+used by apps running as the user(s) specified by <code>KM_TAG_USER_ID</code>.
+ <li><code>KM_TAG_AUTH_TIMEOUT</code> is a numeric value specifying, in seconds, how fresh the user
+ authentication
+must be to authorize key usage. This applies only to private/secret key
+operations. Public key operations don't require authentication. Timeouts do not
+cross reboots; after a reboot, all keys are "never authenticated." The timeout
+may be set to a large value to indicate that authentication is required once
+per boot (2^32 seconds is ~136 years; presumably Android devices are rebooted
+more often than that).
+</ul>
+
+<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>
+
+<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>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
+assumed that the key in
+question can always be used to decrypt/verify messages.</p>
+
+<p>Because wall-clock time is provided by the non-secure world, it's unlikely that
+the expiration-related tags will be in the hardware-enforced list. Hardware
+enforcement of expiry would require that the secure world somehow obtain
+trusted time and data, for example via a challenge response protocol with a
+trusted remote timeserver.</p>
+
+<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
+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>
+
+<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>
+
+<ul>
+ <li><code>KM_BLOB_STANDALONE</code>
+ <li><code>KM_BLOB_REQUIRES_FILE_SYSTEM</code>
+</ul>
+
+<h3 id=velocity>Velocity</h3>
+
+<p>When it's created, the maximum usage velocity can be specified
+with <code>KM_TAG_MIN_SECONDS_BETWEEN_OPS</code>.
+TrustZone implementations will refuse to perform cryptographic operations
+with that key if an operation was performed less
+than <code>KM_TAG_MIN_SECONDS_BETWEEN_OPS</code> seconds earlier.</p>
+
+<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>
+
+<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>
+
+<h3 id=random_number_generator_re-seeding>Random number generator re-seeding</h3>
+
+<p>Because Keymaster 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>
+
+<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>
diff --git a/src/devices/tech/security/authentication/km-implementer-ref.jd b/src/devices/tech/security/authentication/km-implementer-ref.jd
new file mode 100644
index 0000000..9c8c619
--- /dev/null
+++ b/src/devices/tech/security/authentication/km-implementer-ref.jd
@@ -0,0 +1,1229 @@
+page.title=Implementer's Reference
+@jd:body
+
+<!--
+ Copyright 2015 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<p>This page provides details to assist implementers of <a href="keymaster.html">Keymaster</a> HALs. It
+covers each tag and each function in the API.</p>
+
+<h2 id=authorization_tags>Authorization tags</h2>
+
+<p>Except as noted in the tag descriptions, all of the tags below are used during
+key generation to specify key characteristics.</p>
+
+<h3 id=km_tag_purpose>KM_TAG_PURPOSE</h3>
+
+<p>Specifies the set of purposes for which the key may be used.</p>
+
+<p>Possible values are defined by the following enumeration:</p>
+
+<pre>
+typedef enum {
+ KM_PURPOSE_ENCRYPT = 0,
+ KM_PURPOSE_DECRYPT = 1,
+ KM_PURPOSE_SIGN = 2,
+ KM_PURPOSE_VERIFY = 3,
+} keymaster_purpose_t;
+</pre>
+
+<p>This tag is repeatable; keys may be generated with multiple values, although an
+operation has a single purpose. When the <a href="#begin">begin</a> function is called to
+start an operation, the purpose of the operation is
+specified. If the purpose specified to the operation is not authorized by the
+key, the operation must fail with <code>KM_ERROR_INCOMPATIBLE_PURPOSE</code>.</p>
+
+<h3 id=km_tag_algorithm>KM_TAG_ALGORITHM</h3>
+
+<p>Specifies the cryptographic algorithm with which the key is used.</p>
+
+<p>Possible values are defined by the following enumeration:</p>
+
+<pre>
+typedef enum {
+ KM_ALGORITHM_RSA = 1,
+ KM_ALGORITHM_EC = 3,
+ KM_ALGORITHM_AES = 32,
+ KM_ALGORITHM_HMAC = 128,
+} keymaster_algorithm_t;
+</pre>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_key_size>KM_TAG_KEY_SIZE</h3>
+
+<p>Specifies the size, in bits, of the key, measuring in the normal way for the
+key's algorithm. For example, for RSA keys, <code>KM_TAG_KEY_SIZE</code> specifies
+the size of the public modulus. For AES keys it specifies the length
+of the secret key material.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_block_mode>KM_TAG_BLOCK_MODE</h3>
+
+<p>Specifies the block cipher mode(s) with which the key may be used. This tag is
+only relevant to AES keys.</p>
+
+<p>Possible values are defined by the following enumeration:</p>
+
+<pre>
+typedef enum {
+ KM_MODE_ECB = 1,
+ KM_MODE_CBC = 2,
+ KM_MODE_CTR = 3,
+ KM_MODE_GCM = 32,
+} keymaster_block_mode_t;
+</pre>
+
+<p>This tag is repeatable, and for AES key operations a mode must be specified in
+the <code>additional_params</code> argument of <a href="#begin">begin</a>. If the specified
+mode is not in the modes associated with the key, the
+operation must fail with <code>KM_ERROR_INCOMPATIBLE_BLOCK_MODE</code>.</p>
+
+<h3 id=km_tag_digest>KM_TAG_DIGEST</h3>
+
+<p>Specifies the digest algorithms which may be used with the key to perform
+signing and verification operations. This tag is relevant to RSA, ECDSA and
+HMAC keys.</p>
+
+<p>Possible values are defined by the following enumeration:</p>
+
+<pre>
+typedef enum {
+ KM_DIGEST_NONE = 0,
+ KM_DIGEST_MD5 = 1,
+ KM_DIGEST_SHA1 = 2,
+ KM_DIGEST_SHA_2_224 = 3,
+ KM_DIGEST_SHA_2_256 = 4,
+ KM_DIGEST_SHA_2_384 = 5,
+ KM_DIGEST_SHA_2_512 = 6,
+}
+keymaster_digest_t;
+</pre>
+
+<p>This tag is repeatable. For signing and verification operations a digest must
+be specified in the <code>additional_params</code> argument of <a href="#begin">begin</a>.
+If the specified digest is not in the digests associated with the key, the
+operation must fail with <code>KM_ERROR_INCOMPATIBLE_DIGEST</code>.</p>
+
+<h3 id=km_tag_padding>KM_TAG_PADDING</h3>
+
+<p>Specifies the padding modes which may be used with the key. This tag is
+relevant to RSA and AES keys.</p>
+
+<p>Possible values are defined by the following enumeration:</p>
+
+<pre>
+typedef enum {
+ KM_PAD_NONE = 1,
+ KM_PAD_RSA_OAEP = 2,
+ KM_PAD_RSA_PSS = 3,
+ KM_PAD_RSA_PKCS1_1_5_ENCRYPT = 4,
+ KM_PAD_RSA_PKCS1_1_5_SIGN = 5,
+ KM_PAD_PKCS7 = 64,
+} keymaster_padding_t;
+</pre>
+
+<p><code>KM_PAD_RSA_OAEP</code> and <code>KM_PAD_RSA_PKCS1_1_5_ENCRYPT</code> are used
+only for RSA encryption/decryption keys and specify RSA PKCS#1v2 OAEP
+padding and RSA PKCS#1 v1.5 randomized padding, respectively. <code>KM_PAD_RSA_PSS</code> and
+<code>KM_PAD_RSA_PKCS1_1_5_SIGN</code> are used only for RSA signing/verification keys and
+specify RSA PKCS#1v2 PSS
+padding and RSA PKCS#1 v1.5 deterministic padding, respectively. Note also that
+the RSA PSS padding mode is incompatible with <a href="#km_tag_digest">KM_DIGEST_NONE</a>.</p>
+
+<p><code>KM_PAD_NONE</code> may be used with either RSA or AES keys. For AES keys,
+if <code>KM_PAD_NONE</code> is used with block mode ECB or CBC and the data to be encrypted
+or decrypted
+is not a multiple of the AES block size in length, the call to finish must fail
+with <code>KM_ERROR_INVALID_INPUT_LENGTH</code>.</p>
+
+<p><code>KM_PAD_PKCS7</code> may only be used with AES keys, and only with ECB and CBC modes.</p>
+
+<p>This tag is repeatable. A padding mode must be specified in the call to
+<a href="#begin">begin</a>. If the specified mode is not authorized for the key,
+the operation must fail
+with <code>KM_ERROR_INCOMPATIBLE_BLOCK_MODE</code>.</p>
+
+<h3 id=km_tag_caller_nonce>KM_TAG_CALLER_NONCE</h3>
+
+<p>Specifies that the caller is allowed to provide a nonce for nonce-requiring
+operations.</p>
+
+<p>This tag is boolean, so the possible values are true (if the tag is present)
+and false (if the tag is not present).</p>
+
+<p>This tag is used only for AES keys, and is only relevant for CBC, CTR and GCM
+block modes. If the tag is not present, implementations should reject any
+operation which provides <a href="#km_tag_nonce">KM_TAG_NONCE</a> to <a href="#begin">begin</a>
+with <code>KM_ERROR_CALLER_NONCE_PROHIBITED</code>.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_min_mac_length>KM_TAG_MIN_MAC_LENGTH</h3>
+
+<p>Required for HMAC keys and AES keys that support GCM mode, this tag specifies
+the minimum length of MAC that can be requested or verified with this key.</p>
+
+<p>This value is the minimum MAC length, in bits. It must be a multiple of 8. For
+HMAC keys, the value must be at least 64. For GCM keys it must be at least 96
+and must not exceed 128.</p>
+
+<h3 id=km_tag_rsa_public_exponent>KM_TAG_RSA_PUBLIC_EXPONENT</h3>
+
+<p>Specifies the value of the public exponent for an RSA key pair. This tag is
+relevant only to RSA keys, and required for all RSA keys.</p>
+
+<p>The value is a 64-bit unsigned integer that must satisfy the requirements of an
+RSA public exponent. Because it is specified by the caller and therefore cannot
+be chosen by the implementation, it must be a prime number. Trustlets are
+required to support the value 2^16+1. It is recommended that other reasonable
+values be supported, in particular the value 3. If no exponent is specified or
+if the specified exponent is not supported, key generation must fail
+with <code>KM_ERROR_INVALID_ARGUMENT</code>.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_blob_usage_requirements>KM_TAG_BLOB_USAGE_REQUIREMENTS</h3>
+
+<p>Specifies the system environment conditions which must hold for the generated
+key to be used.</p>
+
+<p>Possible values are defined by the following enumeration:</p>
+
+<pre>
+typedef enum {
+ KM_BLOB_STANDALONE = 0,
+ KM_BLOB_REQUIRES_FILE_SYSTEM = 1,
+} keymaster_key_blob_usage_requirements_t;
+</pre>
+
+<p>This tag may be specified during key generation to require that the key be
+usable in the specified condition, and must be returned with the key
+characteristics (from <a href="#generate_key">generate_key</a> and
+<a href="#get_key_characteristics">get_key_characteristics</a>). If
+the caller specifies <code>KM_TAG_BLOB_USAGE_REQUIREMENTS</code> with
+value <code>KM_BLOB_STANDALONE</code> the trustlet must return a key blob
+which can be used without file system
+support. This is critical for devices with encrypted disks, where the file
+system may not be available until after a Keymaster key is used to decrypt the
+disk.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_bootloader_only>KM_TAG_BOOTLOADER_ONLY</h3>
+
+<p>Specifies that the key may only be used by the bootloader.</p>
+
+<p>This tag is boolean, so the possible values are true (if the tag is present)
+and false (if the tag is not present).</p>
+
+<p>Any attempt to use a key with <code>KM_TAG_BOOTLOADER_ONLY</code> from the
+Android system must fail with <code>KM_ERROR_INVALID_KEY_BLOB</code>.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_active_datetime>KM_TAG_ACTIVE_DATETIME</h3>
+
+<p>Specifies the date and time at which the key becomes active. Prior to this
+time, any attempt to use the key must fail with <code>KM_ERROR_KEY_NOT_YET_VALID</code>.</p>
+
+<p>The value is a 64-bit integer representing milliseconds since January 1, 1970.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_origination_expire_datetime>KM_TAG_ORIGINATION_EXPIRE_DATETIME</h3>
+
+<p>Specifies the date and time at which the key expires for signing and encryption
+purposes. After this time, any attempt to use a key
+with <a href="#km_tag_purpose">KM_PURPOSE_SIGN</a> or
+<a href="#km_tag_purpose">KM_PURPOSE_ENCRYPT</a> provided
+to <a href="#begin">begin</a> must fail with <code>KM_ERROR_KEY_EXPIRED</code>.</p>
+
+<p>The value is a 64-bit integer representing milliseconds since January 1, 1970.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_usage_expire_datetime>KM_TAG_USAGE_EXPIRE_DATETIME</h3>
+
+<p>Specifies the date and time at which the key expires for verification and
+decryption purposes. After this time, any attempt to use a key with
+<a href="#km_tag_purpose">KM_PURPOSE_VERIFY</a> or <a href="#km_tag_purpose">KM_PURPOSE DECRYPT</a>
+provided to <a href="#begin">begin</a> must fail with <code>KM_ERROR_KEY_EXPIRED</code>.</p>
+
+<p>The value is a 64-bit integer representing milliseconds since January 1, 1970.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_min_seconds_between_ops>KM_TAG_MIN_SECONDS_BETWEEN_OPS</h3>
+
+<p>Specifies the minimum amount of time that must elapse between allowed
+operations using a key. This can be used to rate-limit uses of keys in contexts
+where unlimited use may enable brute force attacks.</p>
+
+<p>The value is a 32-bit integer representing seconds between allowed operations.</p>
+
+<p>When a key with this tag is used in an operation, a timer should be started
+during the <a href="#finish">finish</a> or <a href="#abort">abort</a> call. Any
+call to <a href="#begin">begin</a> that is received before the timer indicates
+that the interval specified by <code>KM_TAG_MIN_SECONDS_BETWEEN_OPS</code> has
+elapsed must fail with <code>KM_ERROR_KEY_RATE_LIMIT_EXCEEDED</code>. This
+requirement implies that a trustlet must keep a table of timers for keys
+with this tag. Because Keymaster memory is often limited, it is acceptable for
+this table to have a fixed maximum size and for Keymaster to fail operations
+which attempt to use keys with this tag when the table is full. At least 32
+in-use keys must be accommodated, and table slots must be aggressively reused
+when key minimum-usage intervals expire. If an operation fails because the
+table is full, Keymaster should return <code>KM_ERROR_TOO_MANY_OPERATIONS</code>.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_max_uses_per_boot>KM_TAG_MAX_USES_PER_BOOT</h3>
+
+<p>Specifies the maximum number of times that a key may be used between system
+reboots. This is another mechanism to rate-limit key use.</p>
+
+<p>The value is a 32-bit integer representing uses per boot.</p>
+
+<p>When a key with this tag is used in an operation, a key-associated counter
+should be incremented during the <a href="#begin">begin</a> call. After the key counter
+has exceeded this value, all subsequent attempts
+to use the key must fail with <code>KM_ERROR_MAX_OPS_EXCEEDED</code>, until the device is
+restarted. This requirement implies that a trustlet must
+keep a table of use counters for keys with this tag. Because Keymaster memory
+is often limited, it is acceptable for this table to have a fixed maximum size
+and for Keymaster to fail operations that attempt to use keys with this tag
+when the table is full. At least 16 keys must be accommodated. If an operation
+fails because the table is full, Keymaster should return <code>KM_ERROR_TOO_MANY_OPERATIONS</code>.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_user_secure_id>KM_TAG_USER_SECURE_ID</h3>
+
+<p>Specifies that a key may only be used under a particular secure user
+authentication state. This tag is mutually exclusive
+with <a href="#km_tag_no_auth_required">KM_TAG_NO_AUTH_REQUIRED</a>.</p>
+
+<p>The value is a 64-bit integer specifying the authentication policy state value
+which must be present in an authentication token (provided to <a href="#begin">begin</a> with
+the <a href="#km_tag_auth_token">KM_TAG_AUTH_TOKEN</a>) to authorize use of the key. Any
+call to <a href="#begin">begin</a> with a key with this tag that does not provide an
+authentication token, or provides an
+authentication token without a matching policy state value, must fail.</p>
+
+<p>This tag is repeatable. If any of the provided values matches any policy state
+value in the authentication token, the key is authorized for use. Otherwise the operation
+must fail with <code>KM_ERROR_KEY_USER_NOT_AUTHENTICATED</code>.</p>
+
+<h3 id=km_tag_no_auth_required>KM_TAG_NO_AUTH_REQUIRED</h3>
+
+<p>Specifies that no authentication is required to use this key. This tag is
+mutually exclusive with <a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_ID</a>.</p>
+
+<p>This tag is boolean, so the possible values are true (if the tag is present)
+and false (if the tag is not present).</p>
+
+<p>This tag is not repeatable.</p>
+
+<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>
+
+<p>The value is a 32-bit integer bitmask of values from the enumeration:</p>
+
+<pre>
+typedef enum {
+ HW_AUTH_NONE = 0,
+ HW_AUTH_PASSWORD = 1 << 0,
+ HW_AUTH_FINGERPRINT = 1 << 1,
+ // Additional entries should be powers of 2.
+ HW_AUTH_ANY = UINT32_MAX,
+} hw_authenticator_type_t;
+</pre>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_auth_timeout>KM_TAG_AUTH_TIMEOUT</h3>
+
+<p>Specifies the time in seconds for which the key is authorized for use, after
+authentication. If <a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_ID</a> is present and this tag
+is not, then the key requires authentication for every
+usage (see <a href="#begin">begin</a> for the details of the authentication-per-operation flow).</p>
+
+<p>The value is a 32-bit integer specifying the time in seconds after a successful
+authentication of the user specified by <a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_ID</a> with
+the authentication method specified
+by <a href="#km_tag_mac_length">KM_TAG_USER_AUTH_TYPE</a> that the key can be used.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_all_applications>KM_TAG_ALL_APPLICATIONS</h3>
+
+<p>Reserved for future use.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_application_id>KM_TAG_APPLICATION_ID</h3>
+
+<p>When provided to <a href="#generate_key">generate_key</a> or <a href="#import_key">import_key</a>,
+this tag specifies data that must be provided during all uses of the key. In
+particular, calls to <a href="#export_key">export_key</a> and
+<a href="#get_key_characteristics">get_key_characteristics</a> must
+provide the same value in the <code>client_id</code> parameter, and
+calls to <a href="#begin">begin</a> must provide this tag and the
+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 value is a blob, an arbitrary-length array of bytes.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_application_data>KM_TAG_APPLICATION_DATA</h3>
+
+<p>When provided to <a href="#generate_key">generate_key</a> or <a href="#import_key">import_key</a>,
+this tag specifies data that must be provided during all uses of the key. In
+particular, calls to <a href="#export_key">export_key</a> and
+<a href="#get_key_characteristics">get_key_characteristics</a> must
+provide the same value to the <code>client_id</code> parameter, and calls
+to <a href="#begin">begin</a> must provide this tag and the 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>This tag is not repeatable.</p>
+
+<h3 id=km_tag_creation_datetime>KM_TAG_CREATION_DATETIME</h3>
+
+<p>Specifies the date and time the key was created, in milliseconds since January
+1, 1970. This tag is optional and informational only.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_origin>KM_TAG_ORIGIN</h3>
+
+<p>Specifies where the key was created, if known. This tag may not be specified
+during key generation or import, and must be added to the key characteristics
+by the trustlet.</p>
+
+<p>The possible values are defined in <code>keymaster_origin_t</code>:</p>
+
+<pre>
+typedef enum {
+ KM_ORIGIN_GENERATED = 0,
+ KM_ORIGIN_IMPORTED = 2,
+ KM_ORIGIN_UNKNOWN = 3,
+} keymaster_key_origin_t
+</pre>
+
+<p>The full meaning of the value depends not only on the value but on whether it's
+found in the hardware-enforced or software-enforced characteristics list.</p>
+
+<p><code>KM_ORIGIN_GENERATED</code> indicates that Keymaster generated the key.
+If in the hardware-enforced list,
+the key was generated in secure hardware and is permanently hardware-bound. If
+in the software-enforced list, the key was generated in SoftKeymaster and is
+not hardware-bound.</p>
+
+<p><code>KM_ORIGIN_IMPORTED</code> indicates that the key was generated outside
+of Keymaster and imported into
+Keymaster. If in the hardware-enforced list, it is permanently hardware-bound,
+although copies outside of secure hardware may exist. If in the
+software-enforces list, the key was imported into SoftKeymaster and is not
+hardware-bound.</p>
+
+<p><code>KM_ORIGIN_UNKNOWN</code> should only appear in the hardware-enforced list.
+It indicates that the key is
+hardware-bound, but it is not known whether the key was originally generated in
+secure hardware or was imported. This only occurs when keymaster0 hardware is
+being used to emulate keymaster1 services.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_rollback_resistant>KM_TAG_ROLLBACK_RESISTANT</h3>
+
+<p>Indicates that the key is rollback-resistant, meaning that when deleted
+by <a href="#delete_key">delete_key</a> or <a href="#delete_all_keys">delete_all_keys</a>,
+the key is guaranteed to be permanently deleted and unusable. It's possible
+that keys without this tag could be deleted and then restored from backup.</p>
+
+<p>This tag is boolean, so the possible values are true (if the tag is present)
+and false (if the tag is not present).</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_root_of_trust>KM_TAG_ROOT_OF_TRUST</h3>
+
+<p>Specifies the "root of trust," the key used by verified boot to validate the
+operating system booted (if any). This tag is never provided to or returned
+from Keymaster in the key characteristics.</p>
+
+<h3 id=km_tag_associated_data>KM_TAG_ASSOCIATED_DATA</h3>
+
+<p>Provides "associated data" for AES-GCM encryption or decryption. This tag is
+provided to <a href="#update">update</a> and specifies data that is not
+encrypted/decrypted but is used in computing
+the GCM tag.</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_nonce>KM_TAG_NONCE</h3>
+
+<p>Provides or returns a nonce or Initialization Vector (IV) for AES GCM, CBC or
+CTR encryption or decryption. This tag is provided to <a href="#begin">begin</a>
+during encryption and decryption operations. It may only be provided to <a href="#begin">begin</a>
+if the key has <a href="#km_tag_caller_nonce">KM_TAG_CALLER_NONCE</a>. If not provided,
+an appropriate nonce or IV will be randomly generated by
+Keymaster and returned from begin.</p>
+
+<p>The value is a blob, an arbitrary-length array of bytes. Allowed lengths depend
+on the mode: GCM nonces are 12 bytes in length; CBC and CTR IVs are 16 bytes in
+length.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_auth_token>KM_TAG_AUTH_TOKEN</h3>
+
+<p>Provides an authentication token (see the Authentication page) to
+<a href="#begin">begin</a>, <a href="#update">update</a> or <a href="#finish">finish</a>,
+to prove user authentication for a key operation that requires
+it (key has <a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_ID</a>).</p>
+
+<p>The value is a blob which contains a <code>hw_auth_token_t</code> structure.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_mac_length>KM_TAG_MAC_LENGTH</h3>
+
+<p>Provides the requested length of a MAC or GCM authentication tag, in bits.</p>
+
+<p>The value is the MAC length in bits. It must be a multiple of 8 and must be at
+least as large as the value of <a href="#km_tag_min_mac_length">KM_TAG_MIN_MAC_LENGTH</a>
+associated with the key.</p>
+
+<h2 id=functions>Functions</h2>
+
+<h3 id=deprecated_functions>Deprecated functions</h3>
+
+<p>The following functions are in the <code>keymaster1_device_t</code> definition but
+should not be implemented. The function pointers should be set
+to <code>NULL</code>:</p>
+
+<ul>
+ <li><code>generate_keypair</code>
+ <li><code>import_keypair</code>
+ <li><code>get_keypair_public</code>
+ <li><code>delete_keypair</code>
+ <li><code>delete_all</code>
+ <li><code>sign_data</code>
+ <li><code>verify_data</code>
+</ul>
+
+<h3 id=general_implementation_guidelines>General implementation guidelines</h3>
+
+<p>The following guidelines apply to all functions in the API.</p>
+
+<h4 id=input_pointer_parameters>Input pointer parameters</h4>
+
+<p>Input pointer parameters that are not used for a given call may be <code>NULL</code>.
+The caller is not required to provide placeholders. For example, some key
+types and modes may not use any values from the <code>in_params</code> argument
+to <a href="#begin">begin</a>, so the caller may set <code>in_params</code>
+to <code>NULL</code> or provide an empty parameter set. It is also acceptable for the caller to
+provide unused parameters, and Keymaster methods should not issue errors.</p>
+
+<p>If a required input parameter is NULL, Keymaster methods should return
+<code>KM_ERROR_UNEXPECTED_NULL_POINTER</code>.</p>
+
+<h4 id=output_pointer_parameters>Output pointer parameters</h4>
+
+<p>Similar to input pointer parameters, unused output pointer parameters
+may be <code>NULL</code>. If a method needs to return data in an output
+parameter found to be <code>NULL</code>, it should return <code>KM_ERROR_OUTPUT_PARAMETER_NULL</code>.</p>
+
+<h4 id=api_misuse>API misuse</h4>
+
+<p>There are many ways that callers can make requests that don't make sense or are
+foolish but not technically wrong. Keymaster1 implementations are not required
+to fail in such cases or issue a diagnostic. Use of too-small keys,
+specification of irrelevant input parameters, reuse of IVs or nonces,
+generation of keys with no purposes (hence useless) and the like should not be
+diagnosed by implementations. Omission of required parameters, specification of
+invalid required parameters, and similar errors must be diagnosed.</p>
+
+<p>It is the responsibility of apps, the framework, and Android keystore to ensure
+that the calls to Keymaster modules are sensible and useful.</p>
+
+<h3 id=get_supported_algorithms>get_supported_algorithms</h3>
+
+<p>Returns the list of algorithms supported by the Keymaster hardware
+implementation. A software implementation must return an empty list; a hybrid
+implementation must return a list containing only the algorithms that are
+supported by hardware.</p>
+
+<p>Keymaster1 implementations must support RSA, EC, AES and HMAC.</p>
+
+<h3 id=get_supported_block_modes>get_supported_block_modes</h3>
+
+<p>Returns the list of AES block modes supported by the Keymaster hardware
+implementation for a specified algorithm and purpose.</p>
+
+<p>For RSA, EC and HMAC, which are not block ciphers, the method must return an
+empty list for all valid purposes. Invalid purposes should cause the method to
+return <code>KM_ERROR_INVALID_PURPOSE</code>.</p>
+
+<p>Keymaster1 implementations must support ECB, CBC, CTR and GCM for AES
+encryption and decryption.</p>
+
+<h3 id=get_supported_padding_modes>get_supported_padding_modes</h3>
+
+<p>Returns the list of padding modes supported by the Keymaster hardware
+implementation for a specified algorithm and purpose.</p>
+
+<p>HMAC and EC have no notion of padding so the method must return an empty list
+for all valid purposes. Invalid purposes should cause the method to return <code>KM_ERROR_INVALID_PURPOSE</code>.</p>
+
+<p>For RSA, keymaster1 implementations must support:</p>
+
+<ul>
+ <li>Unpadded encryption, decryption, signing and verification. For unpadded
+encryption and signing, if the message is shorter than the public modulus,
+implementations must left-pad it with zeros. For unpadded decryption and
+verification, the input length must match the public modulus size.
+ <li>PKCS#1 v1.5 encryption and signing padding modes
+ <li>PSS with a minimum salt length of 20
+ <li>OAEP
+</ul>
+
+<p>For AES in ECB and CBC modes, keymaster1 implementations must support no
+padding and PKCS#7-padding. CTR and GCM modes must support only no padding.</p>
+
+<h3 id=get_supported_digests>get_supported_digests</h3>
+
+<p>Returns the list of digest modes supported by the Keymaster hardware
+implementation for a specified algorithm and purpose.</p>
+
+<p>No AES modes support or require digesting, so the method must return an empty
+list for valid purposes.</p>
+
+<p>Keymaster1 implementations are allowed to implement a subset of the defined
+digests, but must provide SHA-256. It is strongly recommended that keymaster1
+implementations provide MD5, SHA1, SHA-224, SHA-256, SHA384 and SHA512 (the
+full set of defined digests).</p>
+
+<h3 id=get_supported_import_formats>get_supported_import_formats</h3>
+
+<p>Returns the list of import formats supported by the Keymaster hardware
+implementation of a specified algorithm.</p>
+
+<p>Keymaster1 implementations must support the PKCS#8 format (without password
+protection) for importing RSA and EC key pairs, and must support RAW import of
+AES and HMAC key material.</p>
+
+<h3 id=get_supported_export_formats>get_supported_export_formats</h3>
+
+<p>Returns the list of export formats supported by the Keymaster hardware
+implementation of a specified algorithm.</p>
+
+<p>Keymaster1 implementations must support the X.509 format for exporting RSA and
+EC public keys. Export of private keys or asymmetric keys must not be
+supported.</p>
+
+<h3 id=add_rng_entropy>add_rng_entropy</h3>
+
+<p>Adds caller-provided entropy to the pool used by the Keymaster1 implementation
+for generating random numbers, for keys, IVs, etc.</p>
+
+<p>Keymaster1 implementations must <strong>securely</strong> mix the provided
+entropy into their pool, which must also contain
+internally-generated entropy from a hardware random number generator. Mixing
+must have the property that an attacker with complete control of either
+the <code>add_rng_entropy</code>-provided bits or the hardware-generated bits, but not both, cannot predict
+bits generated from the entropy pool with probability greater than ½.</p>
+
+<p>Keymaster1 implementations that attempt to estimate the entropy in their
+internal pool must assume that data provided by <code>add_rng_entropy</code> contains no entropy.</p>
+
+<h3 id=generate_key>generate_key</h3>
+
+<p>Generates a new cryptographic key, specifying associated authorizations, which
+will be permanently bound to the key. Keymaster1 implementations must make it
+impossible to use a key in any way inconsistent with the authorizations
+specified at generation time. With respect to authorizations that the secure
+hardware cannot enforce, the secure hardware's obligation is limited to
+ensuring that the unenforceable authorizations associated with the key cannot
+be modified, so that every call to <a href="#get_key_characteristics">get_key_characteristics</a>
+will return the original value. In addition, the characteristics returned by <code>generate_key</code>
+must allocate authorizations correctly between the hardware-enforced and
+software-enforced lists. See <a href="#get_key_characteristics">get_key_characteristics</a>
+for more details.</p>
+
+<p>The parameters that must be provided to <code>generate_key</code> depend on the type of key
+being generated. This section will summarize the
+required and allowed tags for each type of key. <a href="#km_tag_algorithm">KM_TAG_ALGORITHM</a>
+is always required, to specify the type.</p>
+
+<h4 id=rsa_keys>RSA keys</h4>
+
+<p>The following parameters are required when generating an RSA key.</p>
+
+<ul>
+ <li><a href="#km_tag_key_size">KM_TAG_KEY_SIZE</a> specifies the size of the public
+ modulus, in bits. If omitted, the method must
+return <code>KM_ERROR_UNSUPPORTED_KEY_SIZE</code>. Values that must be supported are
+1024, 2048, 3072 and 4096. It is
+recommended to support all key sizes that are a multiple of 8.
+ <li><a href="#km_tag_rsa_public_exponent">KM_TAG_RSA_PUBLIC_EXPONENT</a> specifies
+ the RSA public exponent value. If omitted, the method must
+ return <code>KM_ERROR_INVALID_ARGUMENT</code>.
+ Implementations must support the values 3 and 65537. It is recommended to
+support all prime values up to 2^64.
+</ul>
+
+<p>The following parameters are not required to generate an RSA key, but creating
+an RSA key without them will produce a key that is unusable.
+The <code>generate_key</code> function should not return an error if these parameters are omitted.</p>
+
+<ul>
+ <li><a href="#km_tag_purpose">KM_TAG_PURPOSE</a> specifies allowed purposes.
+ All purposes must be supported for RSA keys, in
+any combination.
+ <li><a href="#km_tag_digest">KM_TAG_DIGEST</a> specifies digest algorithms that
+ may be used with the new key. Implementations
+that do not support all digest algorithms must accept key generation requests
+that include unsupported digests. The unsupported digests should be placed in
+the "software-enforced" list in the returned key characteristics. This is
+because the key will be usable with those other digests, but digesting will be
+performed in software. Then hardware will be called to perform the operation
+with <code>KM_DIGEST_NONE</code>.
+ <li><a href="#km_tag_padding">KM_TAG_PADDING</a> specifies the padding modes
+ that may be used with the new key. Implementations
+that do not support all digest algorithms must place <code>KM_PAD_RSA_PSS</code>
+and <code>KM_PAD_RSA_OAEP</code> in the software-enforced list of the key
+characteristics if any unsupported
+digest algorithms are specified.
+</ul>
+
+<h4 id=ecdsa_keys>ECDSA keys</h4>
+
+<p>Only <a href="#km_tag_key_size">KM_TAG_KEY_SIZE</a> is required to generate an
+ECDSA key. It is used to select the EC group.
+Implementations must support values 224, 256, 384 and 521, which indicate the
+NIST p-224, p-256, p-384 and p521 curves, respectively.</p>
+
+<p><a href="#km_tag_digest">KM_TAG_DIGEST</a> is also needed for a useful ECDSA key,
+but is not required for generation.</p>
+
+<h4 id=aes_keys>AES keys</h4>
+
+<p>Only <a href="#km_tag_key_size">KM_TAG_KEY_SIZE</a> is required when
+generating an AES key. If omitted, the method must return <code>KM_ERROR_UNSUPPORTED_KEY_SIZE</code>.
+Values that must be supported are 128 and 256. It is recommended to support
+192-bit AES keys.</p>
+
+<p>The following parameters are particularly relevant for AES keys, but not
+required to generate one:</p>
+
+<ul>
+ <li><code>KM_TAG_BLOCK_MODE</code> specifies the block modes with which the new key may be used.
+ <li><code>KM_TAG_PADDING</code> specifies the padding modes that may be used. This is only relevant for ECB
+and CBC modes.
+</ul>
+
+<p>If the GCM block mode is specified, then <a href="#km_tag_min_mac_length">KM_TAG_MIN_MAC_LENGTH</a>
+must be provided. If omitted, the method must return
+<code>KM_ERROR_MISSING_MIN_MAC_LENGTH</code>. The value of the tag must be a multiple of 8 and must
+be at least 96 and no more than 128.</p>
+
+<h4 id=hmac_keys>HMAC keys</h4>
+
+<p>The following parameters are required for HMAC key generation:</p>
+
+<ul>
+ <li><a href="#km_tag_key_size">KM_TAG_KEY_SIZE</a> specifies the key size in bits. Values
+ smaller than 64 and values that are not
+multiples of 8 must not be supported. All multiples of 8, from 64 to 512, must
+be supported. Larger values may be supported.
+ <li><a href="#km_tag_min_mac_length">KM_TAG_MIN_MAC_LENGTH</a> specifies the minimum length of
+ MACs that can be generated or verified with
+this key. The value must be a multiple of 8 and must be at least 64.
+ <li><a href="#km_tag_digest">KM_TAG_DIGEST</a> specifies the digest algorithm for the key. Exactly
+ one digest must be
+specified, otherwise return <code>KM_ERROR_UNSUPPORTED_DIGEST</code>. If the digest is not supported
+by the trustlet, return <code>KM_ERROR_UNSUPPORTED_DIGEST</code>.
+</ul>
+
+<h4 id=key_characteristics>Key characteristics</h4>
+
+<p>If the characteristics argument is non-NULL, <code>generate_key</code> must return the newly-generated
+key's characteristics divided appropriately
+into hardware-enforced and software-enforced lists. See <a href="#get_key_characteristics">get_key_characteristics</a>
+for a description of which characteristics go in which list. The returned
+characteristics must include all of the parameters specified to key generation,
+except <a href="#km_tag_application_id">KM_TAG_APPLICATION_ID</a> and
+<a href="#km_tag_application_data">KM_TAG_APPLICATION_DATA</a>.
+If these tags were included in the key parameters, they must be removed from
+the returned characteristics; it must not be possible to find their values by
+examining the returned key blob. However, they must be cryptographically bound
+to the key blob, so that if the correct values are not provided when the key is
+used, usage will fail. Similarly, <a href="#km_tag_root_of_trust">KM_TAG_ROOT_OF_TRUST</a> must
+be cryptographically bound to the key, but it may not be specified during
+key creation or import and must never be returned.</p>
+
+<p>In addition to the provided tags, the trustlet must also
+add <a href="#km_tag_origin">KM_TAG_ORIGIN</a>, with the value <code>KM_ORIGIN_GENERATED</code>,
+and if the key is rollback resistant, <a href="#km_tag_rollback_resistant">KM_TAG_ROLLBACK_RESISTANT</a>.</p>
+
+<h4 id=rollback_resistance>Rollback resistance </h4>
+
+<p>Rollback resistance means that once a key is deleted with
+<a href="#delete_key">delete_key</a> or <a href="#delete_all_keys">delete_all_keys</a>,
+it is guaranteed by secure hardware never to be usable again. Implementations
+without rollback resistance will typically return generated or imported key
+material to the caller as a key blob, an encrypted and authenticated form. When
+keystore deletes the key blob, the key is gone, but an attacker who has
+previously managed to retrieve the key material can potentially restore it to
+the device.</p>
+
+<p>A key is rollback resistant if the secure hardware guarantees that deleted keys
+cannot be restored later. This is generally done by storing additional key
+metadata in a trusted location that cannot be manipulated by an attacker. On
+mobile devices, the mechanism used for this is usually Replay Protected Memory
+Blocks (RPMB). Because the number of keys that may be created is essentially
+unbounded and the trusted storage used for rollback resistance may be limited
+in size, it is required that this method succeed even if rollback resistance
+cannot be provided for the new key. In that case,
+<a href="#km_tag_rollback_resistant">KM_TAG_ROLLBACK_RESISTANT</a> should not be
+added to the key characteristics.</p>
+
+<h3 id=get_key_characteristics>get_key_characteristics</h3>
+
+<p>Returns parameters and authorizations associated with the provided key, divided
+into two sets: hardware-enforced and software-enforced. The description here
+applies equally to the key characteristics lists returned
+by <a href="#generate_key">generate_key</a> and <a href="#import_key">import_key</a>.</p>
+
+<p>If <code>KM_TAG_APPLICATION_ID</code> was provided during key generation
+or import, the same value must provided to
+this method in the <code>client_id</code> argument. Otherwise, the
+method must return <code>KM_ERROR_INVALID_KEY_BLOB</code>. Similarly,
+if <code>KM_TAG_APPLICATION_DATA </code>was provided during generation
+or import, the same value must be provided to
+this method in the <code>app_data</code> argument.</p>
+
+<p>The characteristics returned by this method completely describe the type and
+usage of the specified key.</p>
+
+<p>The general rule for deciding whether a given tag belongs in the
+hardware-enforced or software-enforced list is that if the meaning of the tag
+is fully assured by secure hardware, it is hardware-enforced. Otherwise, it's
+software enforced. Below is a list of specific tags whose correct allocation
+may be unclear:</p>
+
+<ul>
+ <li><a href="#km_tag_algorithm">KM_TAG_ALGORITHM</a>, <a href="#km_tag_key_size">KM_TAG_KEY_SIZE</a>,
+ and <a href="#km_tag_rsa_public_exponent">KM_TAG_RSA_PUBLIC_EXPONENT</a> are
+ intrinsic properties of the key. For any key that is secured by hardware,
+these will be in the hardware-enforced list, because the statement that, for
+example, "This RSA key material is only used as an RSA key" is enforced by
+hardware because the hardware will use it in no other way and software has no
+access to the key material and cannot use it at all.
+ <li><a href="#km_tag_digest">KM_TAG_DIGEST</a> values that are supported by the
+ secure hardware are to be placed in the
+hardware-supported list. Unsupported digests go in the software-supported list.
+ <li><a href="#km_tag_padding">KM_TAG_PADDING</a> values generally go in the
+ hardware-supported list, but if there is a
+possibility that a specific padding mode may have to be performed by software,
+they go in the software-enforced list. Such a possibility arises for RSA keys
+that permit PSS or OAEP padding with digest algorithms that are not supported
+by the secure hardware.
+ <li><a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_ID</a> and
+ <a href="#km_tag_mac_length">KM_TAG_USER_AUTH_TYPE</a> are hardware-enforced
+ only if user authentication is hardware enforced. For
+that to be true, the Keymaster trustlet and the relevant authentication
+trustlet must both be secure and must share a secret HMAC key used to sign and
+validate authentication tokens. See the Authentication page for details.
+ <li><a href="#km_tag_active_datetime">KM_TAG_ACTIVE_DATETIME</a>,
+ <a href="#km_tag_origination_expire_datetime">KM_TAG_ORIGINATION_EXPIRE_DATETIME</a>,
+ and <a href="#km_tag_usage_expire_datetime">KM_TAG_USAGE_EXPIRE_DATETIME</a> tags
+ require access to a verifiably correct wall clock. Most secure hardware
+will only have access to time information provided by the non-secure OS, which
+means the tags are software-enforced.
+ <li><a href="#km_tag_origin">KM_TAG_ORIGIN</a> is always in the hardware list for
+ hardware-bound keys. Its presence in that
+list is the way higher layers determine that a key is hardware-backed.
+</ul>
+
+<h3 id=import_key>import_key</h3>
+
+<p>Imports key material into Keymaster hardware. Key definition parameters and
+output characteristics are handled the same as for <code>generate_key</code>,
+with the following exceptions:</p>
+
+<ul>
+ <li><a href="#km_tag_key_size">KM_TAG_KEY_SIZE</a> and
+ <a href="#km_tag_rsa_public_exponent">KM_TAG_RSA_PUBLIC_EXPONENT</a> (for RSA keys only)
+ are not required in the input parameters. If not provided,
+the trustlet must deduce the values from the provided key material and add
+appropriate tags and values to the key characteristics. If the parameters are
+provided, the trustlet must validate them against the key material. In the
+event of a mismatch, the method must return <code>KM_ERROR_IMPORT_PARAMETER_MISMATCH</code>.
+ <li>The returned <a href="#km_tag_origin">KM_TAG_ORIGIN</a> must have the
+ value <code>KM_ORIGIN_IMPORTED</code>.
+</ul>
+
+<h3 id=export_key>export_key</h3>
+
+<p>Exports a public key from a Keymaster RSA or EC key pair.</p>
+
+<p>If <code>KM_TAG_APPLICATION_ID</code> was provided during key generation or import,
+the same value must provided to
+this method in the <code>client_id</code> argument. Otherwise, the method must return
+<code>KM_ERROR_INVALID_KEY_BLOB</code>. Similarly, if <code>KM_TAG_APPLICATION_DATA</code>
+was provided during generation or import, the same value must be provided to
+this method in the <code>app_data</code> argument.</p>
+
+<h3 id=delete_key>delete_key</h3>
+
+<p>Deletes the provided key. This method is optional, and will likely be
+implemented only by Keymaster modules that provide rollback resistance.</p>
+
+<h3 id=delete_all_keys>delete_all_keys</h3>
+
+<p>Deletes all keys. This method is optional, and will likely be implemented only
+by Keymaster modules that provide rollback resistance.</p>
+
+<h3 id=begin>begin</h3>
+
+<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>
+
+<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>
+
+<h4 id=authorization_enforcement>Authorization enforcement</h4>
+
+<p>During this method, the following key authorizations must be enforced by the
+trustlet if the implementation placed them in the "hardware-enforced"
+characteristics and if the operation is not a public key operation. Public key
+operations, meaning <code>KM_PURPOSE_ENCRYPT</code> and <code>KM_PURPOSE_VERIFY</code>,
+with RSA or EC keys, must be allowed to succeed even if authorization
+requirements are not met.</p>
+
+<ul>
+ <li><a href="#km_tag_purpose">KM_TAG_PURPOSE</a> requires that the purpose specified
+ for this method match one of the purposes
+in the key authorizations, unless the requested operation is a public key
+operation, meaning that the key is RSA or EC and the purpose is <code>KM_PURPOSE_ENCRYPT</code>
+or <code>KM_PURPOSE_VERIFY</code>. Note that <code>KM_PURPOSE_ENCRYPT</code> is not valid for EC keys.
+Begin should return <code>KM_ERROR_UNSUPPORTED_PURPOSE</code> in that case.
+ <li><a href="#km_tag_active_datetime">KM_TAG_ACTIVE_DATETIME</a> requires comparison with a trusted
+ UTC time source. If the current date and
+time is prior to the tag value, the method must return <code>KM_ERROR_KEY_NOT_YET_VALID</code>.
+ <li><a href="#km_tag_origination_expire_datetime">KM_TAG_ORIGINATION_EXPIRE_DATETIME</a> requires
+ comparison with a trusted UTC time source. If the current date and
+time is later than the tag value and the purpose is <code>KM_PURPOSE_ENCRYPT</code> or <code>KM_PURPOSE_SIGN</code>,
+the method must return <code>KM_ERROR_KEY_EXPIRED</code>.
+ <li><a href="#km_tag_usage_expire_datetime">KM_TAG_USAGE_EXPIRE_DATETIME</a> requires comparison with a
+ trusted UTC time source. If the current date and
+time is later than the tag value and the purpose is <code>KM_PURPOSE_DECRYPT</code> or <code>KM_PURPOSE_VERIFY</code>,
+the method must return <code>KM_ERROR_KEY_EXPIRED</code>.
+ <li><a href="#km_tag_min_seconds_between_ops">KM_TAG_MIN_SECONDS_BETWEEN_OPS</a> requires comparison with a
+ trusted relative timer indicating the last use of
+the key. If the last use time plus the tag value is less than the current time,
+the method must return <code>KM_ERROR_KEY_RATE_LIMIT_EXCEEDED</code>. See the tag description for
+important implementation requirements.
+ <li><a href="#km_tag_max_uses_per_boot">KM_TAG_MAX_USES_PER_BOOT</a> requires comparison against a
+ secure counter that tracks the uses of the key
+since boot time. If the count of previous uses exceeds the tag value, the
+method must return <code>KM_ERROR_KEY_MAX_OPS_EXCEEDED</code>.
+ <li><a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_ID</a> is enforced by this method only
+ if the key also has <a href="#km_tag_auth_timeout">KM_TAG_AUTH_TIMEOUT</a>. If the key has both,
+ then this method must have received a <a href="#km_tag_auth_token">KM_TAG_AUTH_TOKEN</a> in
+ <code>in_params</code> and that token must be valid, meaning that the HMAC field validates correctly.
+In addition, at least one of the <a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_ID</a>
+values from the key must match at least one of the secure ID values in the
+token. Finally, the key must also have a <a href="#km_tag_mac_length">KM_TAG_USER_AUTH_TYPE</a> and
+it must match the auth type in the token. If any of these requirements is
+not met, the method must return <code>KM_ERROR_KEY_USER_NOT_AUTHENTICATED</code>.
+ <li><a href="#km_tag_caller_nonce">KM_TAG_CALLER_NONCE</a> allows the caller to specify a nonce
+ or initialization vector (IV). If the key
+does not have this tag but the caller provided <a href="#km_tag_nonce">KM_TAG_NONCE</a> to this method,
+<code>KM_ERROR_CALLER_NONCE_PROHIBITED</code> must be returned.
+ <li><a href="#km_tag_bootloader_only">KM_TAG_BOOTLOADER_ONLY</a> specifies that the key may only be
+ used by the bootloader. If this method is
+called with a bootloader-only key after the bootloader has finished executing,
+it must return <code>KM_ERROR_INVALID_KEY_BLOB</code>.
+</ul>
+
+<h4 id=rsa_keys>RSA keys</h4>
+
+<p>All RSA key operations must specify exactly one padding mode in <code>in_params</code>. If
+unspecified or specified more than once, the method must return <code>KM_ERROR_UNSUPPORTED_PADDING_MODE</code>.</p>
+
+<p>RSA signing and verification operations require a digest, as do RSA encryption
+and decryption operations with OAEP padding mode. For those cases, the caller
+must specify exactly one digest in <code>in_params</code>. If unspecified or specified more than once,
+the method must return <code>KM_ERROR_UNSUPPORTED_DIGEST</code>.</p>
+
+<p>Private key operations (<code>KM_PURPOSE_DECYPT</code> and <code>KM_PURPOSE_SIGN</code>) require
+authorization of digest and padding, which means that the specified
+values must be in the key authorizations. If not, the method must return <code>KM_ERROR_INCOMPATIBLE_DIGEST</code>
+or <code>KM_ERROR_INCOMPATIBLE_PADDING</code>, as appropriate. Public key operations
+(<code>KM_PURPOSE_ENCRYPT</code> and <code>KM_PURPOSE_VERIFY</code>) are permitted with
+unauthorized digest or padding.</p>
+
+<p>With the exception of <code>KM_PAD_NONE</code>, all RSA padding modes are applicable only to
+certain purposes. Specifically, <code>KM_PAD_RSA_PKCS1_1_5_SIGN</code> and <code>KM_PAD_RSA_PSS</code>
+only support signing and verification, while <code>KM_PAD_RSA_PKCS1_1_1_5_ENCRYPT</code> and
+<code>KM_PAD_RSA_OAEP</code> only support encryption and decryption. The method must return
+<code>KM_ERROR_UNSUPPORTED_PADDING_MODE</code> if the specified mode does not support the specified purpose.</p>
+
+<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_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>.
+</ul>
+
+<h4 id=ec_keys>EC keys</h4>
+
+<p>EC key operations must specify exactly one padding mode in <code>in_params</code>.
+If unspecified or specified more than once,
+return <code>KM_ERROR_UNSUPPORTED_PADDING_MODE</code>.</p>
+
+<p>Private key operations (<code>KM_PURPOSE_SIGN</code>) require authorization of the
+digest, which means that the specified value must be in the key authorizations.
+If not, return <code>KM_ERROR_INCOMPATIBLE_DIGEST</code>.
+Public key operations (<code>KM_PURPOSE_VERIFY</code>) are permitted with unauthorized digest or padding.</p>
+
+<h4 id=aes_keys>AES keys</h4>
+
+<p>AES key operations must specify exactly one block mode and one padding mode in <code>in_params</code>.
+If either value is unspecified or specified more than once, return <code>KM_ERROR_UNSUPPORTED_BLOCK_MODE</code> or
+<code>KM_ERROR_UNSUPPORTED_PADDING_MODE</code>. The specified modes must be authorized by the key.
+Otherwise, the method must
+return <code>KM_ERROR_INCOMPATIBLE_BLOCK_MODE</code> or <code>KM_ERROR_INCOMPATIBLE_PADDING_MODE</code>.</p>
+
+<p>If the block mode is <code>KM_MODE_GCM</code>, <code>in_params</code> must specify <code>KM_TAG_MAC_LENGTH</code>, and the
+specified value must be a multiple of 8 and must not be greater than
+128, or less than the value of <code>KM_TAG_MIN_MAC_LENGTH</code> in the key authorizations. For MAC lengths greater than 128 or non-multiples of
+8, return <code>KM_ERROR_UNSUPPORTED_MAC_LENGTH</code>. For values less than the key's minimum length, return <code>KM_ERROR_INVALID_MAC_LENGTH</code>.</p>
+
+<p>If the block mode is <code>KM_MODE_GCM</code> or <code>KM_MODE_CTR</code>, the specified padding mode must
+be <code>KM_PAD_NONE</code>. For <code>KM_MODE_ECB</code> or <code>KM_MODE_CBC</code>, the mode may
+be <code>KM_PAD_NONE</code> or <code>KM_PAD_PKCS7</code>. If the padding mode doesn't meet these
+requirements, return <code>KM_ERROR_INCOMPATIBLE_PADDING_MODE</code>.</p>
+
+<p>If the block mode is <code>KM_MODE_CBC</code>, <code>KM_MODE_CTR</code>, or <code>KM_MODE_GCM</code>, an initialization vector or nonce is needed.
+In most cases, callers should not
+provide an IV or nonce and the Keymaster implementation must generate a random
+IV or nonce and return it via <a href="#km_tag_nonce">KM_TAG_NONCE</a> in <code>out_params</code>. CBC
+and CTR IVs are 16 bytes. GCM nonces are 12 bytes. If the key
+authorizations contain <a href="#km_tag_caller_nonce">KM_TAG_CALLER_NONCE</a>, then the caller may
+provide an IV/nonce with <a href="#km_tag_nonce">KM_TAG_NONCE</a> in <code>in_params</code>. If a
+nonce is provided when <a href="#km_tag_caller_nonce">KM_TAG_CALLER_NONCE</a> is not authorized,
+return <code>KM_ERROR_CALLER_NONCE_PROHIBITED</code>. If a nonce is not provided when
+<a href="#km_tag_caller_nonce">KM_TAG_CALLER_NONCE</a> is authorized, generate a random IV/nonce.</p>
+
+<h4 id=hmac_keys>HMAC keys</h4>
+
+<p>HMAC key operations must specify <code>KM_TAG_MAC_LENGTH</code> in <code>in_params</code>.
+The specified value must be a multiple of 8 and must not be greater than the
+digest length, or less than the value of <code>KM_TAG_MIN_MAC_LENGTH</code> in the key authorizations.
+For MAC lengths greater than the digest length or
+non-multiples of 8, return <code>KM_ERROR_UNSUPPORTED_MAC_LENGTH</code>. For values less than
+the key's minimum length, return <code>KM_ERROR_INVALID_MAC_LENGTH</code>.</p>
+
+<h3 id=update>update</h3>
+
+<p>Provides data to process in an ongoing operation started with <a href="#begin">begin</a>.
+The operation is specified by the <code>operation_handle</code> parameter.</p>
+
+<p>To provide more flexibility for buffer handling, implementations of this method
+have the option of consuming less data than was provided. The caller is
+responsible for looping to feed the rest of the data in subsequent calls. The
+amount of input consumed must be returned in the <code>input_consumed</code> parameter.
+Implementations must always consume at least one byte, unless the
+operation cannot accept any more; if more than zero bytes are provided and zero
+bytes are consumed, callers will consider this an error and abort the
+operation.</p>
+
+<p>Implementations may also choose how much data to return, as a result of the
+update. This is only relevant for encryption and decryption operations, since
+signing and verification return no data until <a href="#finish">finish</a>. It is recommended
+to return data as early as possible, rather than buffer it.</p>
+
+<h4 id=error_handling>Error handling</h4>
+
+<p>If this method returns an error code other than <code>KM_ERROR_OK</code>, the operation is
+aborted and the operation handle must be invalidated. Any
+future use of the handle, with this method or <a href="#finish">finish</a> or <a href="#abort">abort</a>,
+must return <code>KM_ERROR_INVALID_OPERATION_HANDLE</code>.</p>
+
+<h4 id=authorization_enforcement>Authorization enforcement</h4>
+
+<p>Key authorization enforcement is performed primarily in <a href="#begin">begin</a>. The one exception
+is the case where the key has:</p>
+
+<ul>
+ <li>One or more <a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_IDs</a>, and
+ <li>Does not have a <a href="#km_tag_auth_timeout">KM_TAG_AUTH_TIMEOUT</a>
+</ul>
+
+<p>In this case, the key requires an authorization per operation, and the update
+method must receive a <a href="#km_tag_auth_token">KM_TAG_AUTH_TOKEN</a> in the <code>in_params</code> argument.
+The token must be valid (HMAC must verify) and it must contain a
+matching secure user ID, must match the key's <a href="#km_tag_mac_length">KM_TAG_USER_AUTH_TYPE</a>, and must
+contain the operation handle of the current operation in the
+challenge field. If these requirements aren't met, return <code>KM_ERROR_KEY_USER_NOT_AUTHENTICATED</code>.</p>
+
+<p>The caller must provide the authentication token to every call to <a href="#update">update</a> and
+<a href="#finish">finish</a>. The implementation need only validate the token once if it prefers.</p>
+
+<h4 id=rsa_keys>RSA keys</h4>
+
+<p>For signing and verification operations with <code>KM_DIGEST_NONE</code>, this method must accept
+the entire block to be signed or verified in a single
+update. It may not consume only a portion of the block. It still must accept
+the data in multiple updates if the caller chooses to provide it that way,
+however. If the caller provides more data to sign than can be used (length of
+data exceeds RSA key size), return <code>KM_ERROR_INVALID_INPUT_LENGTH</code>.</p>
+
+<h4 id=ecdsa_keys>ECDSA keys</h4>
+
+<p>For signing and verification operations with <code>KM_DIGEST_NONE</code>, this method must accept the
+entire block to be signed or verified in a single
+update. This method may not consume only a portion of the block.</p>
+
+<p>However, this method still must accept the data in multiple updates if the
+caller chooses to provide it that way. If the caller provides more data to sign
+than can be used, the data should be silently truncated. (This differs from the
+handling of excess data provided in similar RSA operations. The reason for this
+is compatibility with legacy clients.)</p>
+
+<h4 id=aes_keys>AES keys</h4>
+
+<p>AES GCM mode supports "associated authentication data," provided via the
+<a href="#km_tag_associated_data">KM_TAG_ASSOCIATED_DATA</a> tag in the <code>in_params</code> argument.
+The associated data may be provided in repeated calls (important if
+the data is too large to send in a single block) but must always precede data
+to be encrypted or decrypted. An update call may receive both associated data
+and data to encrypt/decrypt, but subsequent updates may not include associated
+data. If the caller provides associated data to an update call after a call
+that includes data to encrypt/decrypt, return <code>KM_ERROR_INVALID_TAG</code>.</p>
+
+<p>For GCM encryption, the tag is appended to the ciphertext by <a href="#finish">finish</a>.
+During decryption, the last <code>KM_TAG_MAC_LENGTH</code> bytes of the data provided to the last
+update call is the tag. Since a given
+invocation of <a href="#update">update</a> cannot know if it's the last invocation, it must process all but the tag
+length and buffer the possible tag data for processing during <a href="#finish">finish</a>.</p>
+
+<h3 id=finish>finish</h3>
+
+<p>Finished an ongoing operation started with <a href="#begin">begin</a>, processing all of the
+as-yet-unprocessed data provided by <a href="#update">update</a>(s).</p>
+
+<p>This method is the last one called in an operation, so all processed data must
+be returned.</p>
+
+<p>Whether it completes successfully or returns an error, this method finalizes
+the operation and therefore invalidates the provided operation handle. Any
+future use of the handle, with this method or <a href="#update">update</a> or
+<a href="#abort">abort</a>, must return <code>KM_ERROR_INVALID_OPERATION_HANDLE</code>.</p>
+
+<p>Signing operations return the signature as the output. Verification operations
+accept the signature in the <code>signature</code> parameter, and return no output.</p>
+
+<h4 id=authorization_enforcement>Authorization enforcement</h4>
+
+<p>Key authorization enforcement is performed primarily in <a href="#begin">begin</a>. The one exception is the case where the key has:</p>
+
+<ul>
+ <li>One or more <a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_IDs</a>, and
+ <li>Does not have a <a href="#km_tag_auth_timeout">KM_TAG_AUTH_TIMEOUT</a>
+</ul>
+
+<p>In this case, the key requires an authorization per operation, and the update
+method must receive a <a href="#km_tag_auth_token">KM_TAG_AUTH_TOKEN</a> in the <code>in_params</code> argument.
+The token must be valid (HMAC must verify) and it must contain a
+matching secure user ID, must match the key's <a href="#km_tag_mac_length">KM_TAG_USER_AUTH_TYPE</a>, and must
+contain the operation handle of the current operation in the
+challenge field. If these requirements aren't met, return <code>KM_ERROR_KEY_USER_NOT_AUTHENTICATED</code>.</p>
+
+<p>The caller must provide the authentication token to every call to <a href="#update">update</a> and <a href="#finish">finish</a>.
+The implementation need only validate the token once if it prefers.</p>
+
+<h4 id=rsa_keys>RSA keys</h4>
+
+<p>Some additional requirements, depending on the padding mode:</p>
+
+<ul>
+ <li><strong>KM_PAD_NONE</strong>. For unpadded signing and encryption operations, if the provided data is
+shorter than the key, the data must be zero-padded on the left before
+signing/encryption. If the data is the same length as the key but numerically
+larger, return <code>KM_ERROR_INVALID_ARGUMENT</code>. For verification and decryption operations, the data must be exactly as long
+as the key. Otherwise, return <code>KM_ERROR_INVALID_INPUT_LENGTH.</code>
+ <li><strong>KM_PAD_RSA_PSS</strong>. For PSS-padded signature operations, the PSS salt must be at least 20 bytes
+in length and randomly-generated. The salt may be longer; the reference
+implementation uses maximally-sized salt. The digest specified with <a href="#km_tag_digest">KM_TAG_DIGEST</a> in
+<code>input_params</code> on <a href="#begin">begin</a> is used as the PSS digest algorithm, and SHA1 is used as the MGF1 digest
+algorithm.
+ <li><strong>KM_PAD_RSA_OAEP</strong>. The digest specified with <a href="#km_tag_digest">KM_TAG_DIGEST</a> in
+ <code>input_params</code> on <a href="#begin">begin</a> is used as the OAEP digest algorithm, and SHA1 is used as the MGF1 digest
+algorithm.
+</ul>
+
+<h4 id=ecdsa_keys>ECDSA keys</h4>
+
+<p>If the data provided for unpadded signing or verification is too long, truncate
+it.</p>
+
+<h4 id=aes_keys>AES keys</h4>
+
+<p>Some additional requirements, depending on block mode:</p>
+
+<ul>
+ <li><strong>KM_MODE_ECB</strong> or <strong>KM_MODE_CBC</strong>. If padding is <code>KM_PAD_NONE</code> and the
+ data length is not a multiple of the AES block size, return <code>KM_ERROR_INVALID_INPUT_LENGTH</code>. If
+ padding is <code>KM_PAD_PKCS7</code>, pad the data per the PKCS#7 specification. Note that PKCS#7 requires that if
+the data is a multiple of the block length, an additional padding block must be
+added.
+ <li><strong>KM_MODE_GCM</strong>. During encryption, after processing all plaintext, compute the
+ tag (<a href="#km_tag_mac_length">KM_TAG_MAC_LENGTH</a> bytes) and append it to the returned ciphertext.
+ During decryption, process
+the last <a href="#km_tag_mac_length">KM_TAG_MAC_LENGTH</a> bytes as the tag. If tag verification fails,
+return <code>KM_ERROR_VERIFICATION_FAILED</code>.
+</ul>
+
+<h3 id=abort>abort</h3>
+
+<p>Aborts the in-progress operation. After the call to abort, return <code>KM_ERROR_INVALID_OPERATION_HANDLE</code> for
+any subsequent use of the provided operation handle with <a href="#update">update</a>,
+<a href="#finish">finish</a>, or <a href="#abort">abort</a>.</p>
diff --git a/src/devices/tech/security/images/access-to-keymaster.png b/src/devices/tech/security/images/access-to-keymaster.png
new file mode 100644
index 0000000..611f8e3
--- /dev/null
+++ b/src/devices/tech/security/images/access-to-keymaster.png
Binary files differ
