| 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> |