src/security/keystore/features.jd

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="index.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>