Google Git
Sign in
android / platform / docs / source.android.com / e55b3193405187e091a4ac7730ef04360ec04504 / . / en / security / keystore / implementer-ref.html
blob: d003e98a172bcf94854192b79b856c4f1a429b43 [file] [log] [blame]
<html devsite>
<head>
<title>Keymaster Functions</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
<!--
Copyright 2017 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 Keymaster
Hardware Abstraction Layers (HALs). It covers each function in the
API and which Keymaster version that function is available in and
describes the default implementation. For tags, see the
<a href="/security/keystore/tags">Keymaster Tags</a> page.</p>
<p class="note">To support Keymaster 3's transition from the old-style
C-structure HAL to the C++ HAL interface generated from a definition in the new
Hardware Interface Definition Language (HIDL), function names have changed in
Android 8.0. To support this, functions are now in camel case. For example,
<code>get_key_characteristics</code> is now <code>getKeyCharacteristics</code>.
</p>
<h2 id="general_implementation_guidelines">General implementation guidelines</h2>
<p>The following guidelines apply to all functions in the API.</p>
<h3 id="input_pointer_parameters">Input pointer parameters</h3>
<p><strong>Version</strong>: 1, 2</p>
<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>inParams</code> argument
to <a href="#begin">begin</a>, so the caller may set <code>inParams</code>
to <code>NULL</code> or provide an empty parameter set. Callers can also
provide unused parameters, and Keymaster methods should not issue errors.</p>
<p>If a required input parameter is NULL, Keymaster methods should return
<code>ErrorCode::UNEXPECTED_NULL_POINTER</code>.</p>
<p>Starting in Keymaster 3, there are no pointer parameters. All parameters
are passed by value or const references.</p>
<h3 id="output_pointer_parameters">Output pointer parameters</h3>
<p><strong>Version</strong>: 1, 2</p>
<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>ErrorCode::OUTPUT_PARAMETER_NULL</code>.</p>
<p>Starting in Keymaster 3, there are no pointer parameters. All parameters
are passed by value or const references.</p>
<h3 id="api_misuse">API misuse</h3>
<p><strong>Version</strong>: 1, 2, 3</p>
<p>There are many ways that callers can make requests that don't make sense or are
foolish but not technically wrong. Keymaster 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>
<p class="caution">Keymaster implementations should attempt to diagnose
serious errors, such as omission of required parameters, specification of invalid
required parameters, and similar errors that compromise the integrity of the
Keymaster implementation.</p>
<h2 id="functions">Functions</h2>
<h3 id="get_hardware_features">getHardwareFeatures</h3>
<p><strong>Version</strong>: 3</p>
<p>
The new <code>getHardwareFeatures</code> method exposes to clients some important
characteristics of the underlying secure hardware. The method takes no arguments
and returns four values, all booleans:
</p>
<ul>
<li><code>isSecure</code> is <code>true</code> if keys are stored in
secure hardware (TEE, etc.) and never leave it.</li>
<li><code>supportsEllipticCurve</code> is <code>true</code> if the
hardware supports Elliptic Curve cryptography with the NIST curves (P-224,
P-256, P-384, and P-521).</li>
<li><code>supportsSymmetricCryptography</code> is <code>true</code>
if the hardware supports symmetric cryptography, including AES and HMAC.</li>
<li><code>supportsAttestation</code> is <code>true</code> if the
hardware supports generation of Keymaster public key attestation certificates,
signed with a key injected in a secure environment.</li>
</ul>
<p>
The only error codes this method may return are <code>ErrorCode:OK</code>,
<code>ErrorCode::KEYMASTER_NOT_CONFIGURED</code> or one of the error codes
indicating a failure to communicate with the secure hardware.
</p>
<pre class="devsite-click-to-copy">
getHardwareFeatures()
generates(bool isSecure, bool supportsEllipticCurve, bool supportsSymmetricCryptography,
bool supportsAttestation, bool supportsAllDigests, string keymasterName,
string keymasterAuthorName);</pre>
<h3 id="configure">configure</h3>
<p><strong>Version</strong>: 2</p>
<p>This function was introduced in Keymaster 2 and deprecated in Keymaster
3, as this information is available in system properties files, and manufacturer
implementations read those files during startup.</p>
<p>Configures keymaster. This method is called once after the device is opened and before
it is used. It's used to provide
<a href="/security/keystore/tags#os_version">KM_TAG_OS_VERSION</a> and
<a href="/security/keystore/tags#os_patchlevel">KM_TAG_OS_PATCHLEVEL</a> to keymaster.
Until this method is called, all other methods return
<code>KM_ERROR_KEYMASTER_NOT_CONFIGURED</code>. The values provided by this
method are only accepted by keymaster once per boot. Subsequent
calls return <code>KM_ERROR_OK</code>, but do nothing.</p>
<p>
If the keymaster implementation is in secure hardware and the OS version and patch level
values provided do not match the values provided to the secure hardware by the bootloader (or
if the bootloader did not provide values), then this method returns
<code>KM_ERROR_INVALID_ARGUMENT</code>, and all other methods continue returning
<code>KM_ERROR_KEYMASTER_NOT_CONFIGURED</code>.</p>
<pre class="devsite-click-to-copy">
keymaster_error_t (*configure)(const struct keymaster2_device* dev,
const keymaster_key_param_set_t* params);</pre>
<h3 id="add_rng_entropy">addRngEntropy</h3>
<p><strong>Version</strong>: 1, 2, 3</p>
<p>This function was introduced in Keymaster 1 as <code>add_rng_entropy</code>
and renamed in Keymaster 3.</p>
<p>Adds caller-provided entropy to the pool used by the Keymaster 1 implementation
for generating random numbers, for keys, IVs, etc.</p>
<p>Keymaster implementations need to securely mix the provided
entropy into their pool, which also must contain
internally-generated entropy from a hardware random number generator.
Mixing should be handled so that an attacker who has complete control
of either the <code>addRngEntropy</code>-provided bits or the hardware-generated bits,
but not both, has no non-neglible advantage in predicting the bits generated
from the entropy pool.</p>
<p>Keymaster implementations that attempt to estimate the entropy in their
internal pool assume that data provided by
<code>addRngEntropy</code> contains no entropy. Keymaster implementations may
return <code>ErrorCode::INVALID_INPUT_LENGTH</code> if they're given more than 2
KiB of data in a single call.</p>
<h3 id="generate_key">generateKey</h3>
<p><strong>Version</strong>: 1, 2, 3</p>
<p>This function was introduced in Keymaster 1 as <code>generate_key</code>
and renamed in Keymaster 3.</p>
<p>Generates a new cryptographic key, specifying associated authorizations, which
are permanently bound to the key. Keymaster implementations 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">getKeyCharacteristics</a>
returns the original value. In addition, the characteristics returned by
<code>generateKey</code> allocates authorizations correctly between the
hardware-enforced and software-enforced lists. See
<a href="#get_key_characteristics">getKeyCharacteristics</a> for more details.</p>
<p>The parameters provided to <code>generateKey</code> depend on the type of key
being generated. This section summarizes the necessary and optional tags for each
type of key. <a href="/security/keystore/tags#algorithm">Tag::ALGORITHM</a>
is always necessary, to specify the type.</p>
<h4 id="generate_key_rsa_keys">RSA keys</h4>
<p>The following parameters are necessary to generate an RSA key.</p>
<ul>
<li><a href="/security/keystore/tags#key_size">Tag::KEY_SIZE</a>
specifies the size of the public modulus, in bits. If omitted,
the method returns <code>ErrorCode::UNSUPPORTED_KEY_SIZE</code>.
Supported values are 1024, 2048, 3072 and 4096. Recommended values
are all key sizes that are a multiple of 8.</li>
<li><a href="/security/keystore/tags#rsa_public_exponent">Tag::RSA_PUBLIC_EXPONENT</a>
specifies the RSA public exponent value. If omitted, the method
returns <code>ErrorCode::INVALID_ARGUMENT</code>.
Supported values are 3 and 65537. Recommended values are
all prime values up to 2^64.</li>
</ul>
<p>The following parameters are not necessary to generate an RSA key, but creating
an RSA key without them produces a key that is unusable. However, the
<code>generateKey</code> function doesn't return an error if these parameters are omitted.</p>
<ul>
<li><a href="/security/keystore/tags#purpose">Tag::PURPOSE</a> specifies allowed purposes.
All purposes need to be supported for RSA keys, in
any combination.</li>
<li><a href="/security/keystore/tags#digest">Tag::DIGEST</a> specifies
digest algorithms that may be used with the new key. Implementations
that do not support all digest algorithms need to 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 is usable with those other digests, but digesting is
performed in software. Then hardware is called to perform the operation
with <code>Digest::NONE</code>.</li>
<li><a href="/security/keystore/tags#padding">Tag::PADDING</a> specifies the padding modes
that may be used with the new key. Implementations
that do not support all digest algorithms need to place <code>PaddingMode::RSA_PSS</code>
and <code>PaddingMode::RSA_OAEP</code> in the software-enforced list of the key
characteristics if any unsupported digest algorithms are specified.</li>
</ul>
<h4 id="generate_key_ecdsa_keys">ECDSA keys</h4>
<p>Only <a href="/security/keystore/tags#key_size">Tag::KEY_SIZE</a> is
necessary to generate an ECDSA key. It is used to select the EC group.
Supported values are 224, 256, 384 and 521, which indicate the
NIST p-224, p-256, p-384 and p521 curves, respectively.</p>
<p><a href="/security/keystore/tags#digest">Tag::DIGEST</a>
is also necessary for a useful ECDSA key,
but is not required for generation.</p>
<h4 id="generate_key_aes_keys">AES keys</h4>
<p>Only <a href="/security/keystore/tags#key_size">Tag::KEY_SIZE</a>
is necessary to generate an AES key. If omitted, the method returns
<code>ErrorCode::UNSUPPORTED_KEY_SIZE</code>. Supported values are
128 and 256, with optional support for 192-bit AES keys.</p>
<p>The following parameters are particularly relevant for AES keys, but not
necessary to generate one:</p>
<ul>
<li><code>Tag::BLOCK_MODE</code> specifies the block modes with which
the new key may be used.</li>
<li><code>Tag::PADDING</code> specifies the padding modes that may be
used. This is only relevant for ECB and CBC modes.</li>
</ul>
<p>If the GCM block mode is specified, then provide the
<a href="/security/keystore/tags#min_mac_length">Tag::MIN_MAC_LENGTH</a>.
If omitted, the method returns <code>ErrorCode::MISSING_MIN_MAC_LENGTH</code>.
The tag's value is a multiple of 8 and between 96 and 128.</p>
<h4 id="generate_key_hmac_keys">HMAC keys</h4>
<p>The following parameters are required for HMAC key generation:</p>
<ul>
<li><a href="/security/keystore/tags#key_size">Tag::KEY_SIZE</a>
specifies the key size in bits. Values smaller than 64
and values that are not multiples of 8 are not supported. All
multiples of 8, from 64 to 512, are supported. Larger values may be supported.</li>
<li><a href="/security/keystore/tags#min_mac_length">Tag::MIN_MAC_LENGTH</a>
specifies the minimum length of
MACs that can be generated or verified with this key. The value is a multiple of
8 and at least 64.</li>
<li><a href="/security/keystore/tags#digest">Tag::DIGEST</a>
specifies the digest algorithm for the key. Exactly
one digest is specified, otherwise return <code>ErrorCode::UNSUPPORTED_DIGEST</code>.
If the digest is not supported by the trustlet, return
<code>ErrorCode::UNSUPPORTED_DIGEST</code>.</li>
</ul>
<h4 id="key_characteristics">Key characteristics</h4>
<p>If the characteristics argument is non-NULL,
<code>generateKey</code> returns the newly-generated
key's characteristics divided appropriately
into hardware-enforced and software-enforced lists.
See <a href="#get_key_characteristics">getKeyCharacteristics</a>
for a description of which characteristics go in which list. The returned
characteristics include all of the parameters specified to key generation,
except <a href="/security/keystore/tags#application_id">Tag::APPLICATION_ID</a> and
<a href="/security/keystore/tags#application_data">Tag::APPLICATION_DATA</a>.
If these tags were included in the key parameters, they are removed from
the returned characteristics so that it is not be possible to find their values by
examining the returned key blob. However, they are cryptographically bound
to the key blob, so that if the correct values are not provided when the key is
used, usage fails. Similarly,
<a href="/security/keystore/tags#root_of_trust">Tag::ROOT_OF_TRUST</a> is
cryptographically bound to the key, but it may not be specified during
key creation or import and is never returned.</p>
<p>In addition to the provided tags, the trustlet also
adds <a href="/security/keystore/tags#origin">Tag::ORIGIN</a>,
with the value <code>KeyOrigin::GENERATED</code>,
and if the key is rollback resistant,
<a href="/security/keystore/tags#rollback_resistant">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">deleteKey</a> or <a href="#delete_all_keys">deleteAllKeys</a>,
it is guaranteed by secure hardware never to be usable again. Implementations
without rollback resistance 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, this method needs to succeed even if rollback resistance
cannot be provided for the new key. In that case,
<a href="/security/keystore/tags#rollback_resistant">Tag::ROLLBACK_RESISTANT</a>
should not be added to the key characteristics.</p>
<h3 id="get_key_characteristics">getKeyCharacteristics</h3>
<p><strong>Version</strong>: 1, 2, 3</p>
<p>This function was introduced in Keymaster 1 as <code>get_key_characteristics</code>
and renamed in Keymaster 3.</p>
<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">generateKey</a> and <a href="#import_key">importKey</a>.</p>
<p>If <code>Tag::APPLICATION_ID</code> was provided during key generation
or import, the same value is provided to
this method in the <code>clientId</code> argument. Otherwise, the
method returns <code>ErrorCode::INVALID_KEY_BLOB</code>. Similarly,
if <code>Tag::APPLICATION_DATA</code> was provided during generation
or import, the same value is provided to
this method in the <code>appData</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="/security/keystore/tags#algorithm">Tag::ALGORITHM</a>,
<a href="/security/keystore/tags#key_size">Tag::KEY_SIZE</a>,
and <a href="/security/keystore/tags#rsa_public_exponent">Tag::RSA_PUBLIC_EXPONENT</a>
are intrinsic properties of the key. For any key that is secured by hardware,
these tags will be in the hardware-enforced list.</li>
<li><a href="/security/keystore/tags#digest">Tag::DIGEST</a> values
that are supported by the secure hardware are placed in the
hardware-supported list. Unsupported digests go in the software-supported list.</li>
<li><a href="/security/keystore/tags#padding">Tag::PADDING</a> values
generally go in the hardware-supported list, unlessthere is a
possibility that a specific padding mode may have to be performed by software.
In that case, 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>
<li><a href="/security/keystore/tags#user_secure_id">Tag::USER_SECURE_ID</a>
and <a href="/security/keystore/tags#mac_length">Tag::USER_AUTH_TYPE</a>
are hardware-enforced only if user authentication is hardware enforced. To
accomplish this, the Keymaster trustlet and the relevant authentication
trustlet both have to be secure and share a secret HMAC key used to sign and
validate authentication tokens. See the
<a href="/security/authentication/">Authentication</a> page for details.</li>
<li><a href="/security/keystore/tags#active_datetime">Tag::ACTIVE_DATETIME</a>,
<a href="/security/keystore/tags#origination_expire_datetime">Tag::ORIGINATION_EXPIRE_DATETIME</a>,
and <a href="/security/keystore/tags#usage_expire_datetime">Tag::USAGE_EXPIRE_DATETIME</a> tags
require access to a verifiably correct wall clock. Most secure hardware
only has access to time information provided by the non-secure OS, which
means the tags are software enforced.</li>
<li><a href="/security/keystore/tags#origin">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.</li>
</ul>
<h3 id="import_key">importKey</h3>
<p><strong>Version</strong>: 1, 2, 3</p>
<p>This function was introduced in Keymaster 1 as <code>import_key</code>
and renamed in Keymaster 3.</p>
<p>Imports key material into Keymaster hardware. Key definition parameters and
output characteristics are handled the same as for <code>generateKey</code>,
with the following exceptions:</p>
<ul>
<li><a href="/security/keystore/tags#key_size">Tag::KEY_SIZE</a> and
<a href="/security/keystore/tags#rsa_public_exponent">Tag::RSA_PUBLIC_EXPONENT</a>
(for RSA keys only) are not necessary in the input parameters. If not provided,
the trustlet deduces the values from the provided key material and adds
appropriate tags and values to the key characteristics. If the parameters are
provided, the trustlet validates them against the key material. In the
event of a mismatch, the method returns <code>ErrorCode::IMPORT_PARAMETER_MISMATCH</code>.</li>
<li>The returned <a href="/security/keystore/tags#origin">Tag::ORIGIN</a> has the
same value as <code>KeyOrigin::IMPORTED</code>.</li>
</ul>
<h3 id="export_key">exportKey</h3>
<p><strong>Version</strong>: 1, 2, 3</p>
<p>This function was introduced in Keymaster 1 as <code>export_key</code>
and renamed in Keymaster 3.</p>
<p>Exports a public key from a Keymaster RSA or EC key pair.</p>
<p>If <code>Tag::APPLICATION_ID</code> was provided during key generation or import,
the same value is provided to this method in the
<code>clientId</code> argument. Otherwise, the method returns
<code>ErrorCode::INVALID_KEY_BLOB</code>. Similarly, if
<code>Tag::APPLICATION_DATA</code>
was provided during generation or import, the same value is provided to
this method in the <code>appData</code> argument.</p>
<h3 id="delete_key">deleteKey</h3>
<p><strong>Version</strong>: 1, 2, 3</p>
<p>This function was introduced in Keymaster 1 as <code>delete_key</code>
and renamed in Keymaster 3.</p>
<p>Deletes the provided key. This method is optional, and is only
implemented by Keymaster modules that provide rollback resistance.</p>
<h3 id="delete_all_keys">deleteAllKeys</h3>
<p><strong>Version</strong>: 1, 2, 3</p>
<p>This function was introduced in Keymaster 1 as <code>delete_all_keys</code>
and renamed in Keymaster 3.</p>
<p>Deletes all keys. This method is optional, and is only implemented
by Keymaster modules that provide rollback resistance.</p>
<h3 id="destroy_attestation_ids">destroyAttestationIds</h3>
<p><strong>Version</strong>: 3</p>
<p>
The <code>destroyAttestationIds()</code> method is used to permanently
disable the new (optional, but highly recommended)
<a href="/security/keystore/attestation#id-attestation">ID attestation</a>
feature. If the TEE has no way to ensure that ID attestation is permanently
disabled after this method is called, then ID attestation must not be
implemented at all, in which case this method does nothing and
returns <code>ErrorCode::UNIMPLEMENTED</code>. If ID attestation is
supported, this method needs to be implemented and must permanently disable
all future ID attestation attempts. The method may be called any number of
times. If ID attestation is permanently disabled already, the method does
nothing and returns <code>ErrorCode::OK</code>.
</p>
<p>
The only error codes this method may return are
<code>ErrorCode::UNIMPLEMENTED</code> (if ID attestation is not supported),
<code>ErrorCode:OK</code>, <code>ErrorCode::KEYMASTER_NOT_CONFIGURED</code> or
one of the error codes indicating a failure to communicate with the secure
hardware.
</p>
<h3 id="begin">begin</h3>
<p><strong>Version</strong>: 1, 2, 3</p>
<p>Begins a cryptographic operation, using the specified key, for the specified
purpose, with the specified parameters (as appropriate), and returns an
operation handle that is used with <a href="#update">update</a> and <a
href="#finish">finish</a> to complete the operation. The operation handle is
also used as the "challenge" token in authenticated operations, and for such
operations is included in the <code>challenge</code> field of the
authentication token.</p>
<p>A Keymaster implementation supports at least 16 concurrent
operations. Keystore uses up to 15, leaving one for vold to use for password
encryption. When Keystore has 15 operations in progress (<code>begin</code> has
been called, but <code>finish</code> or <code>abort</code> have not yet been
called) and it receives a request to begin a 16th, it calls
<code>abort</code> on the least-recently used operation to reduce the number of
active operations to 14 before calling <code>begin</code> to start the
newly-requested operation.</p>
<p>If <a href="/security/keystore/tags#application_id">Tag::APPLICATION_ID</a>
or <a href="#application_data">Tag::APPLICATION_DATA</a> were specified
during key generation or import, calls to <code>begin</code> include those
tags with the originally-specified values in the <code>inParams</code> argument
to this method.</p>
<h4 id="begin_authorization_enforcement">Authorization enforcement</h4>
<p>During this method, the following key authorizations are 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>KeyPurpose::ENCRYPT</code> and <code>KeyPurpose::VERIFY</code>,
with RSA or EC keys, are allowed to succeed even if authorization
requirements are not met.</p>
<ul>
<li><a href="/security/keystore/tags#purpose">Tag::PURPOSE</a>: The purpose
specified in the <code>begin()</code> call has to match one of the purposes
in the key authorizations, unless the requested operation is a public key
operation. If the specified purpose does not match and the operation is not
a public key operation, <code>begin</code> will return
<code>ErrorCode::UNSUPPORTED_PURPOSE</code>. Public key operations are
asymmetric encryption or verification operations.</li>
<li><a href="/security/keystore/tags#active_datetime">Tag::ACTIVE_DATETIME</a>
can only be enforced if a trusted UTC time source is available. If the
current date and time is prior to the tag value, the method returns
<code>ErrorCode::KEY_NOT_YET_VALID</code>.</li>
<li><a href="/security/keystore/tags#origination_expire_datetime">Tag::ORIGINATION_EXPIRE_DATETIME</a>
can only be enforced if a trusted UTC time source is available. If the
current date and time is later than the tag value and the purpose is
<code>KeyPurpose::ENCRYPT</code> or <code>KeyPurpose::SIGN</code>, the method
returns <code>ErrorCode::KEY_EXPIRED</code>.</li>
<li><a href="/security/keystore/tags#usage_expire_datetime">Tag::USAGE_EXPIRE_DATETIME</a>
can only be enforced if a trusted UTC time source is available. If the
current date and time is later than the tag value and the purpose is
<code>KeyPurpose::DECRYPT</code> or <code>KeyPurpose::VERIFY</code>, the method
returns <code>ErrorCode::KEY_EXPIRED</code>.</li>
<li><a href="/security/keystore/tags#min_seconds_between_ops">Tag::MIN_SECONDS_BETWEEN_OPS</a>
is compared 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 returns <code>ErrorCode::KEY_RATE_LIMIT_EXCEEDED</code>. See the
<a href="/security/keystore/tags#min_seconds_between_ops">tag description</a>
for important implementation details.</li>
<li><a href="/security/keystore/tags#max_uses_per_boot">Tag::MAX_USES_PER_BOOT</a>
is compared 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 returns <code>ErrorCode::KEY_MAX_OPS_EXCEEDED</code>.</li>
<li><a href="/security/keystore/tags#user_secure_id">Tag::USER_SECURE_ID</a>
is enforced by this method only if the key also has
<a href="/security/keystore/tags#auth_timeout">Tag::AUTH_TIMEOUT</a>.
If the key has both, then this method must receive a valid
<a href="/security/keystore/tags#auth_token">Tag::AUTH_TOKEN</a> in
<code>inParams</code>. For the auth token to be valid, all of the following
has to be true:
<ul>
<li>The HMAC field validates correctly.</li>
<li>At least one of the
<a href="/security/keystore/tags#user_secure_id">Tag::USER_SECURE_ID</a>
values from the key matches at least one of the secure ID values in the
token.</li>
<li>The key has a
<a href="/security/keystore/tags#mac_length">Tag::USER_AUTH_TYPE</a>
that matches the auth type in the token.</li>
</ul>
<p>If any of these conditions aren't met, the method returns
<code>ErrorCode::KEY_USER_NOT_AUTHENTICATED</code>.</p></li>
<li><a href="/security/keystore/tags#caller_nonce">Tag::CALLER_NONCE</a>
allows the caller to specify a nonce or initialization vector (IV). If the key
doesn't have this tag, but the caller provided
<a href="/security/keystore/tags#nonce">Tag::NONCE</a> to this method,
<code>ErrorCode::CALLER_NONCE_PROHIBITED</code> is returned.</li>
<li><a href="/security/keystore/tags#bootloader_only">Tag::BOOTLOADER_ONLY</a>
specifies that only the bootloader may use the key. If this method is
called with a bootloader-only key after the bootloader has finished executing,
it returns <code>ErrorCode::INVALID_KEY_BLOB</code>.</li>
</ul>
<h4 id="begin_rsa_keys">RSA keys</h4>
<p>All RSA key operations specify exactly one padding mode in <code>inParams</code>.
If unspecified or specified more than once, the method returns
<code>ErrorCode::UNSUPPORTED_PADDING_MODE</code>.</p>
<p>RSA signing and verification operations need a digest, as do RSA encryption
and decryption operations with OAEP padding mode. For those cases, the caller
specifies exactly one digest in <code>inParams</code>. If unspecified or specified
more than once, the method returns <code>ErrorCode::UNSUPPORTED_DIGEST</code>.</p>
<p>Private key operations (<code>KeyPurpose::DECYPT</code> and <code>KeyPurpose::SIGN</code>)
need authorization of digest and padding, which means that the key authorizations
need to contain the specified values. If not, the method returns
<code>ErrorCode::INCOMPATIBLE_DIGEST</code>
or <code>ErrorCode::INCOMPATIBLE_PADDING</code>, as appropriate. Public key operations
(<code>KeyPurpose::ENCRYPT</code> and <code>KeyPurpose::VERIFY</code>) are permitted with
unauthorized digest or padding.</p>
<p>With the exception of <code>PaddingMode::NONE</code>, all RSA padding modes are
applicable only to certain purposes. Specifically,
<code>PaddingMode::RSA_PKCS1_1_5_SIGN</code> and <code>PaddingMode::RSA_PSS</code>
only support signing and verification, while <code>PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT</code>
and <code>PaddingMode::RSA_OAEP</code> only support encryption and decryption.
The method returns <code>ErrorCode::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>PaddingMode::NONE</code> indicates that a "raw" RSA operation is
performed. If signing or verifying, <code>Digest::NONE</code> is
specified for the digest. No digest is necessary for unpadded encryption or
decryption.</li>
<li><code>PaddingMode::RSA_PKCS1_1_5_SIGN</code> padding requires a digest. The
digest may be <code>Digest::NONE</code>, in which case the Keymaster
implementation cannot build a proper PKCS#1 v1.5 signature structure, because
it cannot add the DigestInfo structure. Instead, the implementation
constructs <code>0x00 || 0x01 || PS || 0x00 || M</code>, where M is the
provided message and PS is the padding string. The size of the RSA key has to
be at least 11 bytes larger than the message, otherwise the method returns
<code>ErrorCode::INVALID_INPUT_LENGTH</code>.</li>
<li><code>PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT</code> padding does not require a digest.</li>
<li><code>PaddingMode::RSA_PSS</code> padding requires a digest, which may not be
<code>Digest::NONE</code>. If <code>Digest::NONE</code> is specified, the
method returns <code>ErrorCode::INCOMPATIBLE_DIGEST</code>. In addition, the
size of the RSA key has to be at least 2 + D bytes larger than the output
size of the digest, where D is the size of the digest, in bytes. Otherwise
the method returns <code>ErrorCode::INCOMPATIBLE_DIGEST</code>. The salt size
is D.</li>
<li><code>PaddingMode::RSA_OAEP</code> padding requires a digest, which may not be
<code>Digest::NONE</code>. If <code>Digest::NONE</code> is specified, the
method returns <code>ErrorCode::INCOMPATIBLE_DIGEST</code>.</li>
</ul>
<h4 id="begin_ec_keys">EC keys</h4>
<p>EC key operations specify exactly one padding mode in <code>inParams</code>.
If unspecified or specified more than once, the method
returns <code>ErrorCode::UNSUPPORTED_PADDING_MODE</code>.</p>
<p>Private key operations (<code>KeyPurpose::SIGN</code>) need authorization
of digest and padding, which means that the key authorizations
need to contain the specified values. If not, return
<code>ErrorCode::INCOMPATIBLE_DIGEST</code>. Public key operations
(<code>KeyPurpose::VERIFY</code>) are permitted with unauthorized digest or padding.</p>
<h4 id="begin_aes_keys">AES keys</h4>
<p>AES key operations specify exactly one block mode and one padding mode
in <code>inParams</code>. If either value is unspecified or specified more
than once, return <code>ErrorCode::UNSUPPORTED_BLOCK_MODE</code> or
<code>ErrorCode::UNSUPPORTED_PADDING_MODE</code>. The specified modes have to be
authorized by the key, otherwise the method returns
<code>ErrorCode::INCOMPATIBLE_BLOCK_MODE</code> or
<code>ErrorCode::INCOMPATIBLE_PADDING_MODE</code>.</p>
<p>If the block mode is <code>BlockMode::GCM</code>, <code>inParams</code>
specifies <code>Tag::MAC_LENGTH</code>, and the
specified value is a multiple of 8 that is not greater than 128
or less than the value of <code>Tag::MIN_MAC_LENGTH</code> in the
key authorizations. For MAC lengths greater than 128 or non-multiples of
8, return <code>ErrorCode::UNSUPPORTED_MAC_LENGTH</code>. For values less
than the key's minimum length, return <code>ErrorCode::INVALID_MAC_LENGTH</code>.</p>
<p>If the block mode is <code>BlockMode::GCM</code> or <code>BlockMode::CTR</code>,
the specified padding mode has to be <code>PaddingMode::NONE</code>.
For <code>BlockMode::ECB</code> or <code>BlockMode::CBC</code>, the mode may be
<code>PaddingMode::NONE</code> or <code>PaddingMode::PKCS7</code>. If the padding mode
doesn't meet these conditions, return <code>ErrorCode::INCOMPATIBLE_PADDING_MODE</code>.</p>
<p>If the block mode is <code>BlockMode::CBC</code>, <code>BlockMode::CTR</code>,
or <code>BlockMode::GCM</code>, an initialization vector or nonce is needed.
In most cases, callers shouldn't provide an IV or nonce. In that case, the
Keymaster implementation generates a random IV or nonce and returns it via
<a href="/security/keystore/tags#nonce">Tag::NONCE</a> in <code>outParams</code>.
CBC and CTR IVs are 16 bytes. GCM nonces are 12 bytes. If the key
authorizations contain
<a href="/security/keystore/tags#caller_nonce">Tag::CALLER_NONCE</a>,
then the caller may provide an IV/nonce with
<a href="/security/keystore/tags#nonce">Tag::NONCE</a>
in <code>inParams</code>. If a nonce is provided when
<a href="/security/keystore/tags#caller_nonce">Tag::CALLER_NONCE</a>
is not authorized, return <code>ErrorCode::CALLER_NONCE_PROHIBITED</code>.
If a nonce is not provided when
<a href="/security/keystore/tags#caller_nonce">Tag::CALLER_NONCE</a>
is authorized, generate a random IV/nonce.</p>
<h4 id="begin_hmac_keys">HMAC keys</h4>
<p>HMAC key operations specify <code>Tag::MAC_LENGTH</code> in <code>inParams</code>.
The specified value must be a multiple of 8 that is not greater than the
digest length or less than the value of <code>Tag::MIN_MAC_LENGTH</code>
in the key authorizations. For MAC lengths greater than the digest length or
non-multiples of 8, return <code>ErrorCode::UNSUPPORTED_MAC_LENGTH</code>.
For values less than the key's minimum length, return
<code>ErrorCode::INVALID_MAC_LENGTH</code>.</p>
<h3 id="update">update</h3>
<p><strong>Version</strong>: 1, 2, 3</p>
<p>Provides data to process in an ongoing operation started with <a href="#begin">begin</a>.
The operation is specified by the <code>operationHandle</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 is returned in the <code>inputConsumed</code> parameter.
Implementations 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 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, because
signing and verification return no data until <a href="#finish">finish</a>.
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>ErrorCode::OK</code>,
the operation is aborted and the operation handle is invalidated. Any
future use of the handle, with this method,
<a href="#finish">finish</a>, or <a href="#abort">abort</a>,
returns <code>ErrorCode::INVALID_OPERATION_HANDLE</code>.</p>
<h4 id="update_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="/security/keystore/tags#user_secure_id">Tag::USER_SECURE_IDs</a>, and</li>
<li>Does not have a <a href="/security/keystore/tags#auth_timeout">Tag::AUTH_TIMEOUT</a></li>
</ul>
<p>In this case, the key requires an authorization per operation, and the update
method receives a <a href="/security/keystore/tags#auth_token">Tag::AUTH_TOKEN</a>
in the <code>inParams</code> argument. HMAC verifies that the token is valid and contains
a matching secure user ID, matches the key's
<a href="/security/keystore/tags#mac_length">Tag::USER_AUTH_TYPE</a>,
and contains the operation handle of the current operation in the
challenge field. If these conditions aren't met, return
<code>ErrorCode::KEY_USER_NOT_AUTHENTICATED</code>.</p>
<p>The caller provides 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="update_rsa_keys">RSA keys</h4>
<p>For signing and verification operations with <code>Digest::NONE</code>,
this method accepts the entire block to be signed or verified in a single
update. It may not consume only a portion of the block. However, if the caller
chooses to provide the data in multiple updates, this method accepts it.
If the caller provides more data to sign than can be used (length of
data exceeds RSA key size), return <code>ErrorCode::INVALID_INPUT_LENGTH</code>.</p>
<h4 id="update_ecdsa_keys">ECDSA keys</h4>
<p>For signing and verification operations with <code>Digest::NONE</code>,
this method accepts 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, if the caller chooses to provide the data in multiple updates,
this method accepts it. If the caller provides more data to sign
than can be used, the data is 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="update_aes_keys">AES keys</h4>
<p>AES GCM mode supports "associated authentication data," provided via the
<a href="/security/keystore/tags#associated_data">Tag::ASSOCIATED_DATA</a>
tag in the <code>inParams</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 always precedes 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>ErrorCode::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>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 processes all but the tag length and buffer the possible tag data
during <a href="#finish">finish</a>.</p>
<h3 id="finish">finish</h3>
<p><strong>Version</strong>: 1, 2, 3</p>
<p>Finishes 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 is 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>, returns <code>ErrorCode::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="finish_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="/security/keystore/tags#user_secure_id">Tag::USER_SECURE_IDs</a>, and</li>
<li>Does not have a
<a href="/security/keystore/tags#auth_timeout">Tag::AUTH_TIMEOUT</a></li>
</ul>
<p>In this case, the key requires an authorization per operation, and the update
method receives a <a href="/security/keystore/tags#auth_token">Tag::AUTH_TOKEN</a>
in the <code>inParams</code> argument. HMAC verifies that the token
is valid and contains a matching secure user ID, matches the key's
<a href="/security/keystore/tags#mac_length">Tag::USER_AUTH_TYPE</a>, and
contains the operation handle of the current operation in the
challenge field. If these conditions aren't met, return
<code>ErrorCode::KEY_USER_NOT_AUTHENTICATED</code>.</p>
<p>The caller provides 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="finish_rsa_keys">RSA keys</h4>
<p>Some additional requirements, depending on the padding mode:</p>
<ul>
<li><code>PaddingMode::NONE</code>. For unpadded signing and encryption operations,
if the provided data is shorter than the key, the data is be zero-padded on
the left before signing/encryption. If the data is the same length as the key,
but numerically larger, return <code>ErrorCode::INVALID_ARGUMENT</code>. For
verification and decryption operations, the data must be exactly as long
as the key. Otherwise, return <code>ErrorCode::INVALID_INPUT_LENGTH.</code></li>
<li><code>PaddingMode::RSA_PSS</code>. For PSS-padded signature operations,
the PSS salt is 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="/security/keystore/tags#digest">Tag::DIGEST</a>
in <code>inputParams</code> on <a href="#begin">begin</a> is used as the PSS digest
algorithm, and SHA1 is used as the MGF1 digest algorithm.</li>
<li><code>PaddingMode::RSA_OAEP</code>. The digest specified with
<a href="/security/keystore/tags#digest">Tag::DIGEST</a> in
<code>inputParams</code> on <a href="#begin">begin</a> is used as the OAEP
digest algorithm, and SHA1 is used as the MGF1 digest algorithm.</li>
</ul>
<h4 id="finish_ecdsa_keys">ECDSA keys</h4>
<p>If the data provided for unpadded signing or verification is too long, truncate
it.</p>
<h4 id="finish_aes_keys">AES keys</h4>
<p>Some additional conditions, depending on block mode:</p>
<ul>
<li><code>BlockMode::ECB</code> or <code>BlockMode::CBC</code>.
If padding is <code>PaddingMode::NONE</code> and the
data length is not a multiple of the AES block size, return
<code>ErrorCode::INVALID_INPUT_LENGTH</code>. If padding is
<code>PaddingMode::PKCS7</code>, pad the data per the PKCS#7 specification.
Note that PKCS#7 recommends adding an additional padding block
if the data is a multiple of the block length.</li>
<li><code>BlockMode::GCM</code>. During encryption, after processing
all plaintext, compute the tag
(<a href="/security/keystore/tags#mac_length">Tag::MAC_LENGTH</a> bytes)
and append it to the returned ciphertext. During decryption, process
the last <a href="/security/keystore/tags#mac_length">Tag::MAC_LENGTH</a>
bytes as the tag. If tag verification fails, return
<code>ErrorCode::VERIFICATION_FAILED</code>.</li>
</ul>
<h3 id="abort">abort</h3>
<p><strong>Version</strong>: 1, 2, 3</p>
<p>Aborts the in-progress operation. After the call to abort, return
<code>ErrorCode::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>
<h3 id="get_supported_algorithms">get_supported_algorithms</h3>
<p><strong>Version</strong>: 1</p>
<p>Returns the list of algorithms supported by the Keymaster hardware
implementation. A software implementation returns an empty list; a hybrid
implementation returns a list containing only the algorithms that are
supported by hardware.</p>
<p>Keymaster 1 implementations support RSA, EC, AES and HMAC.</p>
<h3 id="get_supported_block_modes">get_supported_block_modes</h3>
<p><strong>Version</strong>: 1</p>
<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 returns an
empty list for all valid purposes. Invalid purposes should cause the method to
return <code>ErrorCode::INVALID_PURPOSE</code>.</p>
<p>Keymaster 1 implementations support ECB, CBC, CTR and GCM for AES
encryption and decryption.</p>
<h3 id="get_supported_padding_modes">get_supported_padding_modes</h3>
<p><strong>Version</strong>: 1</p>
<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 returns an empty list
for all valid purposes. Invalid purposes should cause the method to return
<code>ErrorCode::INVALID_PURPOSE</code>.</p>
<p>For RSA, Keymaster 1 implementations 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>
<li>PKCS#1 v1.5 encryption and signing padding modes</li>
<li>PSS with a minimum salt length of 20</li>
<li>OAEP</li>
</ul>
<p>For AES in ECB and CBC modes, Keymaster 1 implementations support no
padding and PKCS#7-padding. CTR and GCM modes support only no padding.</p>
<h3 id="get_supported_digests">get_supported_digests</h3>
<p><strong>Version</strong>: 1</p>
<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 returns an empty
list for valid purposes.</p>
<p>Keymaster 1 implementations can implement a subset of the defined
digests. Implementations provide SHA-256 and can 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><strong>Version</strong>: 1</p>
<p>Returns the list of import formats supported by the Keymaster hardware
implementation of a specified algorithm.</p>
<p>Keymaster 1 implementations support the PKCS#8 format (without password
protection) for importing RSA and EC key pairs, and support RAW import of
AES and HMAC key material.</p>
<h3 id="get_supported_export_formats">get_supported_export_formats</h3>
<p><strong>Version</strong>: 1</p>
<p>Returns the list of export formats supported by the Keymaster hardware
implementation of a specified algorithm.</p>
<p>Keymaster1 implementations support the X.509 format for exporting RSA and
EC public keys. Export of private keys or asymmetric keys is not supported.</p>
<h2 id="historical-functions">Historical functions</h2>
<h3 id="km0">Keymaster 0</h3>
<p>
The following functions belong to the original Keymaster 0 definition. They
were present in Keymaster 1 struct keymaster1_device_t. However, in Keymaster
1.0 they were not implemented, and their function pointers were set to NULL.
</p>
<ul>
<li><code>generate_keypair</code></li>
<li><code>import_keypair</code></li>
<li><code>get_keypair_public</code></li>
<li><code>delete_keypair</code></li>
<li><code>delete_all</code></li>
<li><code>sign_data</code></li>
<li><code>Verify_data</code></li>
</ul>
<h3 id="km1">Keymaster 1</h3>
<p>The following functions belong to the Keymaster 1 definition, but were
removed in Keymaster 2, along with the Keymaster 0 functions listed above.
</p>
<ul>
<li><code>get_supported_algorithms</code></li>
<li><code>get_supported_block_modes</code></li>
<li><code>get_supported_padding_modes</code></li>
<li><code>get_supported_digests</code></li>
<li><code> get_supported_import_formats</code></li>
<li><code>get_supported_export_formats</code></li>
</ul>
<h3 id="km2">Keymaster 2</h3>
<p>The following functions belong to the Keymaster 2 definition, but were
removed in Keymaster 3, along with the Keymaster 1 functions listed above.
</p>
<ul>
<li><code>configure</code></li>
</ul>
</body>
</html>