Google Git
Sign in
android / platform / hardware / interfaces / 2658c0da40fabf8fff9a765ebd5c5b293c4b57e8 / . / keymaster / 4.0 / types.hal
blob: 94dfec55a9e407870e35b3faf58db9c5f57658f0 [file] [log] [blame]
/*
* Copyright (C) 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.
*/
package android.hardware.keymaster@4.0;
/**
* Time in milliseconds since some arbitrary point in time. Time must be monotonically increasing,
* and a secure environment's notion of "current time" must not repeat until the Android device
* reboots, or until at least 50 million years have elapsed (note that this requirement is satisfied
* by setting the clock to zero during each boot, and then counting time accurately).
*/
typedef uint64_t Timestamp;
/**
* A place to define any needed constants.
*/
enum Constants : uint32_t {
AUTH_TOKEN_MAC_LENGTH = 32,
};
enum TagType : uint32_t {
/** Invalid type, used to designate a tag as uninitialized. */
INVALID = 0 << 28,
/** Enumeration value. */
ENUM = 1 << 28,
/** Repeatable enumeration value. */
ENUM_REP = 2 << 28,
/** 32-bit unsigned integer. */
UINT = 3 << 28,
/** Repeatable 32-bit unsigned integer. */
UINT_REP = 4 << 28,
/** 64-bit unsigned integer. */
ULONG = 5 << 28,
/** 64-bit unsigned integer representing a date and time, in milliseconds since 1 Jan 1970. */
DATE = 6 << 28,
/** Boolean. If a tag with this type is present, the value is "true". If absent, "false". */
BOOL = 7 << 28,
/** Byte string containing an arbitrary-length integer, big-endian ordering. */
BIGNUM = 8 << 28,
/** Byte string */
BYTES = 9 << 28,
/** Repeatable 64-bit unsigned integer */
ULONG_REP = 10 << 28,
};
enum Tag : uint32_t {
INVALID = TagType:INVALID | 0,
/**
* Tag::PURPOSE specifies the set of purposes for which the key may be used. Possible values
* are defined in the KeyPurpose enumeration.
*
* This tag is repeatable; keys may be generated with multiple values, although an operation has
* a single purpose. When begin() is called to start an operation, the purpose of the operation
* is specified. If the purpose specified for the operation is not authorized by the key (the
* key didn't have a corresponding Tag::PURPOSE provided during generation/import), the
* operation must fail with ErrorCode::INCOMPATIBLE_PURPOSE.
*
* Must be hardware-enforced.
*/
PURPOSE = TagType:ENUM_REP | 1,
/**
* Tag::ALGORITHM specifies the cryptographic algorithm with which the key is used. This tag
* must be provided to generateKey and importKey, and must be specified in the wrapped key
* provided to importWrappedKey.
*
* Must be hardware-enforced.
*/
ALGORITHM = TagType:ENUM | 2,
/**
* Tag::KEY_SIZE pecifies the size, in bits, of the key, measuring in the normal way for the
* key's algorithm. For example, for RSA keys, Tag::KEY_SIZE specifies the size of the public
* modulus. For AES keys it specifies the length of the secret key material. For 3DES keys it
* specifies the length of the key material, not counting parity bits (though parity bits must
* be provided for import, etc.). Since only three-key 3DES keys are supported, 3DES
* Tag::KEY_SIZE must be 168.
*
* Must be hardware-enforced.
*/
KEY_SIZE = TagType:UINT | 3,
/**
* Tag::BLOCK_MODE specifies the block cipher mode(s) with which the key may be used. This tag
* is only relevant to AES and 3DES keys. Possible values are defined by the BlockMode enum.
*
* This tag is repeatable for key generation/import. For AES and 3DES operations the caller
* must specify a Tag::BLOCK_MODE in the additionalParams argument of begin(). If the mode is
* missing or the specified mode is not in the modes specified for the key during
* generation/import, the operation must fail with ErrorCode::INCOMPATIBLE_BLOCK_MODE.
*
* Must be hardware-enforced.
*/
BLOCK_MODE = TagType:ENUM_REP | 4, /* BlockMode. */
/**
* Tag::DIGEST specifies the digest algorithms that may be used with the key to perform signing
* and verification operations. This tag is relevant to RSA, ECDSA and HMAC keys. Possible
* values are defined by the Digest enum.
*
* This tag is repeatable for key generation/import. For signing and verification operations,
* the caller must specify a digest in the additionalParams argument of begin(). If the digest
* is missing or the specified digest is not in the digests associated with the key, the
* operation must fail with ErrorCode::INCOMPATIBLE_DIGEST.
*
* Must be hardware-enforced.
*/
DIGEST = TagType:ENUM_REP | 5,
/**
* Tag::PADDING specifies the padding modes that may be used with the key. This tag is relevant
* to RSA, AES and 3DES keys. Possible values are defined by the PaddingMode enum.
*
* PaddingMode::RSA_OAEP and PaddingMode::RSA_PKCS1_1_5_ENCRYPT are used only for RSA
* encryption/decryption keys and specify RSA OAEP padding and RSA PKCS#1 v1.5 randomized
* padding, respectively. PaddingMode::RSA_PSS and PaddingMode::RSA_PKCS1_1_5_SIGN are used
* only for RSA signing/verification keys and specify RSA PSS padding and RSA PKCS#1 v1.5
* deterministic padding, respectively.
*
* PaddingMode::NONE may be used with either RSA, AES or 3DES keys. For AES or 3DES keys, if
* PaddingMode::NONE 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 ErrorCode::INVALID_INPUT_LENGTH.
*
* PaddingMode::PKCS7 may only be used with AES and 3DES keys, and only with ECB and CBC modes.
*
* In any case, if the caller specifies a padding mode that is not usable with the key's
* algorithm, the generation or import method must return ErrorCode::INCOMPATIBLE_PADDING_MODE.
*
* This tag is repeatable. A padding mode must be specified in the call to begin(). If the
* specified mode is not authorized for the key, the operation must fail with
* ErrorCode::INCOMPATIBLE_BLOCK_MODE.
*
* Must be hardware-enforced.
*/
PADDING = TagType:ENUM_REP | 6,
/**
* Tag::CALLER_NONCE specifies that the caller can provide a nonce for nonce-requiring
* operations. This tag is boolean, so the possible values are true (if the tag is present) and
* false (if the tag is not present).
*
* This tag is used only for AES and 3DES keys, and is only relevant for CBC, CTR and GCM block
* modes. If the tag is not present in a key's authorization list, implementations must reject
* any operation that provides Tag::NONCE to begin() with ErrorCode::CALLER_NONCE_PROHIBITED.
*
* Must be hardware-enforced.
*/
CALLER_NONCE = TagType:BOOL | 7,
/**
* Tag::MIN_MAC_LENGTH specifies the minimum length of MAC that can be requested or verified
* with this key for HMAC keys and AES keys that support GCM mode.
*
* This value is the minimum MAC length, in bits. It must be a multiple of 8 bits. For HMAC
* keys, the value must be least 64 and no more than 512. For GCM keys, the value must be at
* least 96 and no more than 128. If the provided value violates these requirements,
* generateKey() or importKey() must return ErrorCode::UNSUPPORTED_KEY_SIZE.
*
* Must be hardware-enforced.
*/
MIN_MAC_LENGTH = TagType:UINT | 8,
// Tag 9 reserved
/**
* Tag::EC_CURVE specifies the elliptic curve. EC key generation requests may have
* Tag:EC_CURVE, Tag::KEY_SIZE, or both. If both are provided and the size and curve do not
* match, IKeymasterDevice must return ErrorCode::INVALID_ARGUMENT.
*
* Must be hardware-enforced.
*/
EC_CURVE = TagType:ENUM | 10,
/**
* Tag::RSA_PUBLIC_EXPONENT specifies the value of the public exponent for an RSA key pair.
* This tag is relevant only to RSA keys, and is required for all RSA keys.
*
* The value is a 64-bit unsigned integer that satisfies the requirements of an RSA public
* exponent. This value must be a prime number. IKeymasterDevice implementations must support
* the value 2^16+1 and may support other reasonable values. If no exponent is specified or if
* the specified exponent is not supported, key generation must fail with
* ErrorCode::INVALID_ARGUMENT.
*
* Must be hardware-enforced.
*/
RSA_PUBLIC_EXPONENT = TagType:ULONG | 200,
// Tag 201 reserved
/**
* Tag::INCLUDE_UNIQUE_ID is specified during key generation to indicate that an attestation
* certificate for the generated key should contain an application-scoped and time-bounded
* device-unique ID. See Tag::UNIQUE_ID.
*
* Must be hardware-enforced.
*/
INCLUDE_UNIQUE_ID = TagType:BOOL | 202,
/**
* Tag::BLOB_USAGE_REQUIREMENTS specifies the necessary system environment conditions for the
* generated key to be used. Possible values are defined by the KeyBlobUsageRequirements enum.
*
* This tag is specified by the caller during key generation or import to require that the key
* is usable in the specified condition. If the caller specifies Tag::BLOB_USAGE_REQUIREMENTS
* with value KeyBlobUsageRequirements::STANDALONE the IKeymasterDevice must return a key blob
* that 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.
*
* Must be hardware-enforced.
*/
BLOB_USAGE_REQUIREMENTS = TagType:ENUM | 301,
/**
* Tag::BOOTLOADER_ONLY specifies only the bootloader can use the key.
*
* Any attempt to use a key with Tag::BOOTLOADER_ONLY from the Android system must fail with
* ErrorCode::INVALID_KEY_BLOB.
*
* Must be hardware-enforced.
*/
BOOTLOADER_ONLY = TagType:BOOL | 302,
/**
* Tag::ROLLBACK_RESISTANCE specifies that the key has rollback resistance, meaning that when
* deleted with deleteKey() or deleteAllKeys(), 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.
*
* This tag is specified by the caller during key generation or import to require. If the
* IKeymasterDevice cannot guarantee rollback resistance for the specified key, it must return
* ErrorCode::ROLLBACK_RESISTANCE_UNAVAILABLE. IKeymasterDevice implementations are not
* required to support rollback resistance.
*
* Must be hardwared-enforced.
*/
ROLLBACK_RESISTANCE = TagType:BOOL | 303,
// Reserved for future use.
HARDWARE_TYPE = TagType:ENUM | 304,
/**
* Tag::ACTIVE_DATETIME specifies the date and time at which the key becomes active, in
* milliseconds since Jan 1, 1970. If a key with this tag is used prior to the specified date
* and time, IKeymasterDevice::begin() must return ErrorCode::KEY_NOT_YET_VALID;
*
* Need not be hardware-enforced.
*/
ACTIVE_DATETIME = TagType:DATE | 400, /* Start of validity. */
/**
* Tag::ORIGINATION_EXPIRE_DATETIME 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
* KeyPurpose::SIGN or KeyPurpose::ENCRYPT provided to begin() must fail with
* ErrorCode::KEY_EXPIRED.
*
* The value is a 64-bit integer representing milliseconds since January 1, 1970.
*
* Need not be hardware-enforced.
*/
ORIGINATION_EXPIRE_DATETIME = TagType:DATE | 401,
/**
* Tag::USAGE_EXPIRE_DATETIME 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
* KeyPurpose::VERIFY or KeyPurpose::DECRYPT provided to begin() must fail with
* ErrorCode::KEY_EXPIRED.
*
* The value is a 64-bit integer representing milliseconds since January 1, 1970.
*
* Need not be hardware-enforced.
*/
USAGE_EXPIRE_DATETIME = TagType:DATE | 402,
/**
* Tag::MIN_SECONDS_BETWEEN_OPS specifies the minimum amount of time that elapses 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.
*
* The value is a 32-bit integer representing seconds between allowed operations.
*
* When a key with this tag is used in an operation, the IKeymasterDevice must start a timer
* during the finish() or abort() call. Any call to begin() that is received before the timer
* indicates that the interval specified by Tag::MIN_SECONDS_BETWEEN_OPS has elapsed must fail
* with ErrorCode::KEY_RATE_LIMIT_EXCEEDED. This implies that the IKeymasterDevice must keep a
* table of use counters for keys with this tag. Because memory is often limited, this table
* may have a fixed maximum size and Keymaster may fail operations that attempt to use keys with
* this tag when the table is full. The table must acommodate at least 8 in-use keys and
* aggressively reuse table slots when key minimum-usage intervals expire. If an operation
* fails because the table is full, Keymaster returns ErrorCode::TOO_MANY_OPERATIONS.
*
* Must be hardware-enforced.
*/
MIN_SECONDS_BETWEEN_OPS = TagType:UINT | 403,
/**
* Tag::MAX_USES_PER_BOOT specifies the maximum number of times that a key may be used between
* system reboots. This is another mechanism to rate-limit key use.
*
* The value is a 32-bit integer representing uses per boot.
*
* When a key with this tag is used in an operation, a key-associated counter must be
* incremented during the begin() call. After the key counter has exceeded this value, all
* subsequent attempts to use the key must fail with ErrorCode::MAX_OPS_EXCEEDED, until the
* device is restarted. This implies that the IKeymasterDevice must keep a table of use
* counters for keys with this tag. Because Keymaster memory is often limited, this table can
* have a fixed maximum size and Keymaster can fail operations that attempt to use keys with
* this tag when the table is full. The table needs to acommodate at least 8 keys. If an
* operation fails because the table is full, IKeymasterDevice must
* ErrorCode::TOO_MANY_OPERATIONS.
*
* Must be hardware-enforced.
*/
MAX_USES_PER_BOOT = TagType:UINT | 404,
/**
* Tag::USER_ID specifies the ID of the Android user that is permitted to use the key.
*
* Must not be hardware-enforced.
*/
USER_ID = TagType:UINT | 501,
/**
* Tag::USER_SECURE_ID specifies that a key may only be used under a particular secure user
* authentication state. This tag is mutually exclusive with Tag::NO_AUTH_REQUIRED.
*
* The value is a 64-bit integer specifying the authentication policy state value which must be
* present in the userId or authenticatorId field of a HardwareAuthToken provided to begin(),
* update(), or finish(). If a key with Tag::USER_SECURE_ID is used without a HardwareAuthToken
* with the matching userId or authenticatorId, the IKeymasterDevice must return
* ErrorCode::KEY_USER_NOT_AUTHENTICATED.
*
* Tag::USER_SECURE_ID interacts with Tag::AUTH_TIMEOUT in a very important way. If
* Tag::AUTH_TIMEOUT is present in the key's characteristics then the key is a "timeout-based"
* key, and may only be used if the difference between the current time when begin() is called
* and the timestamp in the HardwareAuthToken is less than the value in Tag::AUTH_TIMEOUT * 1000
* (the multiplier is because Tag::AUTH_TIMEOUT is in seconds, but the HardwareAuthToken
* timestamp is in milliseconds). Otherwise the IKeymasterDevice must returrn
* ErrorCode::KEY_USER_NOT_AUTHENTICATED.
*
* If Tag::AUTH_TIMEOUT is not present, then the key is an "auth-per-operation" key. In this
* case, begin() must not require a HardwareAuthToken with appropriate contents. Instead,
* update() and finish() must receive a HardwareAuthToken with Tag::USER_SECURE_ID value in
* userId or authenticatorId fields, and the current operation's operation handle in the
* challenge field. Otherwise the IKeymasterDevice must returrn
* ErrorCode::KEY_USER_NOT_AUTHENTICATED.
*
* This tag is repeatable. If repeated, and any one of the values matches the HardwareAuthToken
* as described above, the key is authorized for use. Otherwise the operation must fail with
* ErrorCode::KEY_USER_NOT_AUTHENTICATED.
*
* Must be hardware-enforced.
*/
USER_SECURE_ID = TagType:ULONG_REP | 502, /* Secure ID of authorized user or authenticator(s).
* Disallowed if NO_AUTH_REQUIRED is present. */
/**
* Tag::NO_AUTH_REQUIRED specifies that no authentication is required to use this key. This tag
* is mutually exclusive with Tag::USER_SECURE_ID.
*
* Must be hardware-enforced.
*/
NO_AUTH_REQUIRED = TagType:BOOL | 503, /* If key is usable without authentication. */
/**
* Tag::USER_AUTH_TYPE specifies the types of user authenticators that may be used to authorize
* this key.
*
* The value is one or more values from HardwareAuthenticatorType, ORed together.
*
* When IKeymasterDevice is requested to perform an operation with a key with this tag, it must
* receive a HardwareAuthToken and one or more bits must be set in both the HardwareAuthToken's
* authenticatorType field and the Tag::USER_AUTH_TYPE value. That is, it must be true that
*
* (token.authenticatorType & tag_user_auth_type) != 0
*
* where token.authenticatorType is the authenticatorType field of the HardwareAuthToken and
* tag_user_auth_type is the value of Tag:USER_AUTH_TYPE.
*
* Must be hardware-enforced.
*/
USER_AUTH_TYPE = TagType:ENUM | 504,
/**
* Tag::AUTH_TIMEOUT specifies the time in seconds for which the key is authorized for use,
* after user authentication. If
* Tag::USER_SECURE_ID is present and this tag is not, then the key requies authentication for
* every usage (see begin() for the details of the authentication-per-operation flow).
*
* The value is a 32-bit integer specifying the time in seconds after a successful
* authentication of the user specified by Tag::USER_SECURE_ID with the authentication method
* specified by Tag::USER_AUTH_TYPE that the key can be used.
*
* Must be hardware-enforced.
*/
AUTH_TIMEOUT = TagType:UINT | 505,
/**
* Tag::ALLOW_WHILE_ON_BODY specifies that the key may be used after authentication timeout if
* device is still on-body (requires on-body sensor).
*
* Cannot be hardware-enforced.
*/
ALLOW_WHILE_ON_BODY = TagType:BOOL | 506,
/**
* TRUSTED_USER_PRESENCE_REQUIRED is an optional feature that specifies that this key must be
* unusable except when the user has provided proof of physical presence. Proof of physical
* presence must be a signal that cannot be triggered by an attacker who doesn't have one of:
*
* a) Physical control of the device or
*
* b) Control of the secure environment that holds the key.
*
* For instance, proof of user identity may be considered proof of presence if it meets the
* requirements. However, proof of identity established in one security domain (e.g. TEE) does
* not constitute proof of presence in another security domain (e.g. StrongBox), and no
* mechanism analogous to the authentication token is defined for communicating proof of
* presence across security domains.
*
* Some examples:
*
* A hardware button hardwired to a pin on a StrongBox device in such a way that nothing
* other than a button press can trigger the signal constitutes proof of physical presence
* for StrongBox keys.
*
* Fingerprint authentication provides proof of presence (and identity) for TEE keys if the
* TEE has exclusive control of the fingerprint scanner and performs fingerprint matching.
*
* Password authentication does not provide proof of presence to either TEE or StrongBox,
* even if TEE or StrongBox does the password matching, because password input is handled by
* the non-secure world, which means an attacker who has compromised Android can spoof
* password authentication.
*
* Note that no mechanism is defined for delivering proof of presence to an IKeymasterDevice,
* except perhaps as implied by an auth token. This means that Keymaster must be able to check
* proof of presence some other way. Further, the proof of presence must be performed between
* begin() and the first call to update() or finish(). If the first update() or the finish()
* call is made without proof of presence, the keymaster method must return
* ErrorCode::PROOF_OF_PRESENCE_REQUIRED and abort the operation. The caller must delay the
* update() or finish() call until proof of presence has been provided, which means the caller
* must also have some mechanism for verifying that the proof has been provided.
*
* Only one operation requiring TUP may be in flight at a time. If begin() has already been
* called on one key with TRUSTED_USER_PRESENCE_REQUIRED, and another begin() comes in for that
* key or another with TRUSTED_USER_PRESENCE_REQUIRED, Keymaster must return
* ErrorCode::CONCURRENT_PROOF_OF_PRESENCE_REQUESTED.
*
* Must be hardware-enforced.
*/
TRUSTED_USER_PRESENCE_REQUIRED = TagType:BOOL | 507,
/** Tag::TRUSTED_CONFIRMATION_REQUIRED is only applicable to keys with KeyPurpose SIGN, and
* specifies that this key must not be usable unless the user provides confirmation of the data
* to be signed. Confirmation is proven to keymaster via an approval token. See
* CONFIRMATION_TOKEN, as well as the ConfirmatinUI HAL.
*
* If an attempt to use a key with this tag does not have a cryptographically valid
* CONFIRMATION_TOKEN provided to finish() or if the data provided to update()/finish() does not
* match the data described in the token, keymaster must return NO_USER_CONFIRMATION.
*
* Must be hardware-enforced.
*/
TRUSTED_CONFIRMATION_REQUIRED = TagType:BOOL | 508,
/**
* Tag::UNLOCKED_DEVICE_REQUIRED specifies that the key may only be used when the device is
* unlocked.
*
* Must be software-enforced.
*/
UNLOCKED_DEVICE_REQUIRED = TagType:BOOL | 509,
/**
* Tag::APPLICATION_ID. When provided to generateKey or importKey, this tag specifies data
* that is necessary during all uses of the key. In particular, calls to exportKey() and
* getKeyCharacteristics() must provide the same value to the clientId parameter, and calls to
* begin must provide this tag and the same associated data as part of the inParams set. If
* the correct data is not provided, the method must return ErrorCode::INVALID_KEY_BLOB.
*
* The content of this tag must be bound to the key cryptographically, meaning it must not be
* possible for an adversary who has access to all of the secure world secrets but does not have
* access to the tag content to decrypt the key without brute-forcing the tag content, which
* applications can prevent by specifying sufficiently high-entropy content.
*
* Must never appear in KeyCharacteristics.
*/
APPLICATION_ID = TagType:BYTES | 601,
/*
* Semantically unenforceable tags, either because they have no specific meaning or because
* they're informational only.
*/
/**
* Tag::APPLICATION_DATA. When provided to generateKey or importKey, this tag specifies data
* that is necessary during all uses of the key. In particular, calls to exportKey() and
* getKeyCharacteristics() must provide the same value to the appData parameter, and calls to
* begin must provide this tag and the same associated data as part of the inParams set. If
* the correct data is not provided, the method must return ErrorCode::INVALID_KEY_BLOB.
*
* The content of this tag msut be bound to the key cryptographically, meaning it must not be
* possible for an adversary who has access to all of the secure world secrets but does not have
* access to the tag content to decrypt the key without brute-forcing the tag content, which
* applications can prevent by specifying sufficiently high-entropy content.
*
* Must never appear in KeyCharacteristics.
*/
APPLICATION_DATA = TagType:BYTES | 700,
/**
* Tag::CREATION_DATETIME specifies the date and time the key was created, in milliseconds since
* January 1, 1970. This tag is optional and informational only.
*
* Tag::CREATED is informational only, and not enforced by anything. Must be in the
* software-enforced list, if provided.
*/
CREATION_DATETIME = TagType:DATE | 701,
/**
* Tag::ORIGIN specifies where the key was created, if known. This tag must not be specified
* during key generation or import, and must be added to the key characteristics by the
* IKeymasterDevice. The possible values are defined in the KeyOrigin enum.
*
* Must be hardware-enforced.
*/
ORIGIN = TagType:ENUM | 702,
// 703 is unused.
/**
* Tag::ROOT_OF_TRUST 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. It exists only to define the tag for use in the attestation
* record.
*
* Must never appear in KeyCharacteristics.
*/
ROOT_OF_TRUST = TagType:BYTES | 704,
/**
* Tag::OS_VERSION specifies the system OS version with which the key may be used. This tag is
* never sent to the IKeymasterDevice, but is added to the hardware-enforced authorization list
* by the TA. Any attempt to use a key with a Tag::OS_VERSION value different from the
* currently-running OS version must cause begin(), getKeyCharacteristics() or exportKey() to
* return ErrorCode::KEY_REQUIRES_UPGRADE. See upgradeKey() for details.
*
* The value of the tag is an integer of the form MMmmss, where MM is the major version number,
* mm is the minor version number, and ss is the sub-minor version number. For example, for a
* key generated on Android version 4.0.3, the value would be 040003.
*
* The IKeymasterDevice HAL must read the current OS version from the system property
* ro.build.version.release and deliver it to the secure environment when the HAL is first
* loaded (mechanism is implementation-defined). The secure environment must not accept another
* version until after the next boot. If the content of ro.build.version.release has additional
* version information after the sub-minor version number, it must not be included in
* Tag::OS_VERSION. If the content is non-numeric, the secure environment must use 0 as the
* system version.
*
* Must be hardware-enforced.
*/
OS_VERSION = TagType:UINT | 705,
/**
* Tag::OS_PATCHLEVEL specifies the system security patch level with which the key may be used.
* This tag is never sent to the keymaster TA, but is added to the hardware-enforced
* authorization list by the TA. Any attempt to use a key with a Tag::OS_PATCHLEVEL value
* different from the currently-running system patchlevel must cause begin(),
* getKeyCharacteristics() or exportKey() to return ErrorCode::KEY_REQUIRES_UPGRADE. See
* upgradeKey() for details.
*
* The value of the tag is an integer of the form YYYYMM, where YYYY is the four-digit year of
* the last update and MM is the two-digit month of the last update. For example, for a key
* generated on an Android device last updated in December 2015, the value would be 201512.
*
* The IKeymasterDevice HAL must read the current system patchlevel from the system property
* ro.build.version.security_patch and deliver it to the secure environment when the HAL is
* first loaded (mechanism is implementation-defined). The secure environment must not accept
* another patchlevel until after the next boot.
*
* Must be hardware-enforced.
*/
OS_PATCHLEVEL = TagType:UINT | 706,
/**
* Tag::UNIQUE_ID specifies a unique, time-based identifier. This tag is never provided to or
* returned from Keymaster in the key characteristics. It exists only to define the tag for use
* in the attestation record.
*
* When a key with Tag::INCLUDE_UNIQUE_ID is attested, the unique ID is added to the attestation
* record. The value is a 128-bit hash that is unique per device and per calling application,
* and changes monthly and on most password resets. It is computed with:
*
* HMAC_SHA256(T || C || R, HBK)
*
* Where:
*
* T is the "temporal counter value", computed by dividing the value of
* Tag::CREATION_DATETIME by 2592000000, dropping any remainder. T changes every 30 days
* (2592000000 = 30 * 24 * 60 * 60 * 1000).
*
* C is the value of Tag::ATTESTATION_APPLICATION_ID that is provided to attestKey().
*
* R is 1 if Tag::RESET_SINCE_ID_ROTATION was provided to attestKey or 0 if the tag was not
* provided.
*
* HBK is a unique hardware-bound secret known to the secure environment and never revealed
* by it. The secret must contain at least 128 bits of entropy and be unique to the
* individual device (probabilistic uniqueness is acceptable).
*
* HMAC_SHA256 is the HMAC function, with SHA-2-256 as the hash.
*
* The output of the HMAC function must be truncated to 128 bits.
*
* Must be hardware-enforced.
*/
UNIQUE_ID = TagType:BYTES | 707,
/**
* Tag::ATTESTATION_CHALLENGE is used to deliver a "challenge" value to the attestKey() method,
* which must place the value in the KeyDescription SEQUENCE of the attestation extension. See
* attestKey().
*
* Must never appear in KeyCharacteristics.
*/
ATTESTATION_CHALLENGE = TagType:BYTES | 708, /* Used to provide challenge in attestation */
/**
* Tag::ATTESTATION_APPLICATION_ID identifies the set of applications which may use a key, used
* only with attestKey().
*
* The content of Tag::ATTESTATION_APPLICATION_ID is a DER-encoded ASN.1 structure, with the
* following schema:
*
* AttestationApplicationId ::= SEQUENCE {
* packageInfoRecords SET OF PackageInfoRecord,
* signatureDigests SET OF OCTET_STRING,
* }
*
* PackageInfoRecord ::= SEQUENCE {
* packageName OCTET_STRING,
* version INTEGER,
* }
*
* See system/security/keystore/keystore_attestation_id.cpp for details of construction.
* IKeymasterDevice implementers do not need to create or parse the ASN.1 structure, but only
* copy the tag value into the attestation record. The DER-encoded string must not exceed 1 KiB
* in length.
*
* Cannot be hardware-enforced.
*/
ATTESTATION_APPLICATION_ID = TagType:BYTES | 709,
/**
* Tag::ATTESTATION_ID_BRAND provides the device's brand name, as returned by Build.BRAND in
* Android, to attestKey(). This field must be set only when requesting attestation of the
* device's identifiers.
*
* If the device does not support ID attestation (or destroyAttestationIds() was previously
* called and the device can no longer attest its IDs), any key attestation request that
* includes this tag must fail with ErrorCode::CANNOT_ATTEST_IDS.
*
* Must never appear in KeyCharacteristics.
*/
ATTESTATION_ID_BRAND = TagType:BYTES | 710,
/**
* Tag::ATTESTATION_ID_DEVICE provides the device's device name, as returned by Build.DEVICE in
* Android, to attestKey(). This field must be set only when requesting attestation of the
* device's identifiers.
*
* If the device does not support ID attestation (or destroyAttestationIds() was previously
* called and the device can no longer attest its IDs), any key attestation request that
* includes this tag must fail with ErrorCode::CANNOT_ATTEST_IDS.
*
* Must never appear in KeyCharacteristics.
*/
ATTESTATION_ID_DEVICE = TagType:BYTES | 711,
/**
* Tag::ATTESTATION_ID_PRODUCT provides the device's product name, as returned by Build.PRODUCT
* in Android, to attestKey(). This field must be set only when requesting attestation of the
* device's identifiers.
*
* If the device does not support ID attestation (or destroyAttestationIds() was previously
* called and the device can no longer attest its IDs), any key attestation request that
* includes this tag must fail with ErrorCode::CANNOT_ATTEST_IDS.
*
* Must never appear in KeyCharacteristics.
*/
ATTESTATION_ID_PRODUCT = TagType:BYTES | 712,
/**
* Tag::ATTESTATION_ID_SERIAL the device's serial number. This field must be set only when
* requesting attestation of the device's identifiers.
*
* If the device does not support ID attestation (or destroyAttestationIds() was previously
* called and the device can no longer attest its IDs), any key attestation request that
* includes this tag must fail with ErrorCode::CANNOT_ATTEST_IDS.
*
* Must never appear in KeyCharacteristics.
*/
ATTESTATION_ID_SERIAL = TagType:BYTES | 713,
/**
* Tag::ATTESTATION_ID_IMEI provides the IMEIs for all radios on the device to attestKey().
* This field must be set only when requesting attestation of the device's identifiers.
*
* If the device does not support ID attestation (or destroyAttestationIds() was previously
* called and the device can no longer attest its IDs), any key attestation request that
* includes this tag must fail with ErrorCode::CANNOT_ATTEST_IDS.
*
* Must never appear in KeyCharacteristics.
*/
ATTESTATION_ID_IMEI = TagType:BYTES | 714, /* Used to provide the device's IMEI to be included
* in attestation */
/**
* Tag::ATTESTATION_ID_MEID provides the MEIDs for all radios on the device to attestKey().
* This field must be set only when requesting attestation of the device's identifiers.
*
* If the device does not support ID attestation (or destroyAttestationIds() was previously
* called and the device can no longer attest its IDs), any key attestation request that
* includes this tag must fail with ErrorCode::CANNOT_ATTEST_IDS.
*
* Must never appear in KeyCharacteristics.
*/
ATTESTATION_ID_MEID = TagType:BYTES | 715, /* Used to provide the device's MEID to be included
* in attestation */
/**
* Tag::ATTESTATION_ID_MANUFACTURER provides the device's manufacturer name, as returned by
* Build.MANUFACTURER in Android, to attstKey(). This field must be set only when requesting
* attestation of the device's identifiers.
*
* If the device does not support ID attestation (or destroyAttestationIds() was previously
* called and the device can no longer attest its IDs), any key attestation request that
* includes this tag must fail with ErrorCode::CANNOT_ATTEST_IDS.
*
* Must never appear in KeyCharacteristics.
*/
ATTESTATION_ID_MANUFACTURER = TagType:BYTES | 716,
/**
* Tag::ATTESTATION_ID_MODEL provides the device's model name, as returned by Build.MODEL in
* Android, to attestKey(). This field must be set only when requesting attestation of the
* device's identifiers.
*
* If the device does not support ID attestation (or destroyAttestationIds() was previously
* called and the device can no longer attest its IDs), any key attestation request that
* includes this tag must fail with ErrorCode::CANNOT_ATTEST_IDS.
*
* Must never appear in KeyCharacteristics.
*/
ATTESTATION_ID_MODEL = TagType:BYTES | 717,
/**
* Tag::VENDOR_PATCHLEVEL specifies the vendor image security patch level with which the key may
* be used. This tag is never sent to the keymaster TA, but is added to the hardware-enforced
* authorization list by the TA. Any attempt to use a key with a Tag::VENDOR_PATCHLEVEL value
* different from the currently-running system patchlevel must cause begin(),
* getKeyCharacteristics() or exportKey() to return ErrorCode::KEY_REQUIRES_UPGRADE. See
* upgradeKey() for details.
*
* The value of the tag is an integer of the form YYYYMMDD, where YYYY is the four-digit year of
* the last update, MM is the two-digit month and DD is the two-digit day of the last
* update. For example, for a key generated on an Android device last updated on June 5, 2018,
* the value would be 20180605.
*
* The IKeymasterDevice HAL must read the current vendor patchlevel from the system property
* ro.vendor.build.security_patch and deliver it to the secure environment when the HAL is first
* loaded (mechanism is implementation-defined). The secure environment must not accept another
* patchlevel until after the next boot.
*
* Must be hardware-enforced.
*/
VENDOR_PATCHLEVEL = TagType:UINT | 718,
/**
* Tag::BOOT_PATCHLEVEL specifies the boot image (kernel) security patch level with which the
* key may be used. This tag is never sent to the keymaster TA, but is added to the
* hardware-enforced authorization list by the TA. Any attempt to use a key with a
* Tag::BOOT_PATCHLEVEL value different from the currently-running system patchlevel must
* cause begin(), getKeyCharacteristics() or exportKey() to return
* ErrorCode::KEY_REQUIRES_UPGRADE. See upgradeKey() for details.
*
* The value of the tag is an integer of the form YYYYMMDD, where YYYY is the four-digit year of
* the last update, MM is the two-digit month and DD is the two-digit day of the last
* update. For example, for a key generated on an Android device last updated on June 5, 2018,
* the value would be 20180605. If the day is not known, 00 may be substituted.
*
* During each boot, the bootloader must provide the patch level of the boot image to the secure
* envirionment (mechanism is implementation-defined).
*
* Must be hardware-enforced.
*/
BOOT_PATCHLEVEL = TagType:UINT | 719,
/**
* Tag::ASSOCIATED_DATA Provides "associated data" for AES-GCM encryption or decryption. This
* tag is provided to update and specifies data that is not encrypted/decrypted, but is used in
* computing the GCM tag.
*
* Must never appear KeyCharacteristics.
*/
ASSOCIATED_DATA = TagType:BYTES | 1000,
/**
* Tag::NONCE is used to provide or return a nonce or Initialization Vector (IV) for AES-GCM,
* AES-CBC, AES-CTR, or 3DES-CBC encryption or decryption. This tag is provided to begin during
* encryption and decryption operations. It is only provided to begin if the key has
* Tag::CALLER_NONCE. If not provided, an appropriate nonce or IV must be randomly generated by
* Keymaster and returned from begin.
*
* The value is a blob, an arbitrary-length array of bytes. Allowed lengths depend on the mode:
* GCM nonces are 12 bytes in length; AES-CBC and AES-CTR IVs are 16 bytes in length, 3DES-CBC
* IVs are 8 bytes in length.
*
* Must never appear in KeyCharacteristics.
*/
NONCE = TagType:BYTES | 1001,
/**
* Tag::MAC_LENGTH provides the requested length of a MAC or GCM authentication tag, in bits.
*
* The value is the MAC length in bits. It must be a multiple of 8 and at least as large as the
* value of Tag::MIN_MAC_LENGTH associated with the key. Otherwise, begin() must return
* ErrorCode::INVALID_MAC_LENGTH.
*
* Must never appear in KeyCharacteristics.
*/
MAC_LENGTH = TagType:UINT | 1003,
/**
* Tag::RESET_SINCE_ID_ROTATION specifies whether the device has been factory reset since the
* last unique ID rotation. Used for key attestation.
*
* Must never appear in KeyCharacteristics.
*/
RESET_SINCE_ID_ROTATION = TagType:BOOL | 1004,
/**
* Tag::CONFIRMATION_TOKEN is used to deliver a cryptographic token proving that the user
* confirmed a signing request. The content is a full-length HMAC-SHA256 value. See the
* ConfirmationUI HAL for details of token computation.
*
* Must never appear in KeyCharacteristics.
*/
CONFIRMATION_TOKEN = TagType:BYTES | 1005,
};
/**
* Algorithms provided by IKeymasterDevice implementations.
*/
enum Algorithm : uint32_t {
/** Asymmetric algorithms. */
RSA = 1,
// 2 removed, do not reuse.
EC = 3,
/** Block cipher algorithms */
AES = 32,
TRIPLE_DES = 33,
/** MAC algorithms */
HMAC = 128,
};
/**
* Symmetric block cipher modes provided by keymaster implementations.
*/
enum BlockMode : uint32_t {
/*
* Unauthenticated modes, usable only for encryption/decryption and not generally recommended
* except for compatibility with existing other protocols.
*/
ECB = 1,
CBC = 2,
CTR = 3,
/*
* Authenticated modes, usable for encryption/decryption and signing/verification. Recommended
* over unauthenticated modes for all purposes.
*/
GCM = 32,
};
/**
* Padding modes that may be applied to plaintext for encryption operations. This list includes
* padding modes for both symmetric and asymmetric algorithms. Note that implementations should not
* provide all possible combinations of algorithm and padding, only the
* cryptographically-appropriate pairs.
*/
enum PaddingMode : uint32_t {
NONE = 1, /* deprecated */
RSA_OAEP = 2,
RSA_PSS = 3,
RSA_PKCS1_1_5_ENCRYPT = 4,
RSA_PKCS1_1_5_SIGN = 5,
PKCS7 = 64,
};
/**
* Digests provided by keymaster implementations.
*/
enum Digest : uint32_t {
NONE = 0,
MD5 = 1,
SHA1 = 2,
SHA_2_224 = 3,
SHA_2_256 = 4,
SHA_2_384 = 5,
SHA_2_512 = 6,
};
/**
* Supported EC curves, used in ECDSA
*/
enum EcCurve : uint32_t {
P_224 = 0,
P_256 = 1,
P_384 = 2,
P_521 = 3,
};
/**
* The origin of a key (or pair), i.e. where it was generated. Note that ORIGIN can be found in
* either the hardware-enforced or software-enforced list for a key, indicating whether the key is
* hardware or software-based. Specifically, a key with GENERATED in the hardware-enforced list
* must be guaranteed never to have existed outide the secure hardware.
*/
enum KeyOrigin : uint32_t {
/** Generated in keymaster. Should not exist outside the TEE. */
GENERATED = 0,
/** Derived inside keymaster. Likely exists off-device. */
DERIVED = 1,
/** Imported into keymaster. Existed as cleartext in Android. */
IMPORTED = 2,
/**
* Keymaster did not record origin. This value can only be seen on keys in a keymaster0
* implementation. The keymaster0 adapter uses this value to document the fact that it is
* unkown whether the key was generated inside or imported into keymaster.
*/
UNKNOWN = 3,
/**
* Securely imported into Keymaster. Was created elsewhere, and passed securely through Android
* to secure hardware.
*/
SECURELY_IMPORTED = 4,
};
/**
* Usability requirements of key blobs. This defines what system functionality must be available
* for the key to function. For example, key "blobs" which are actually handles referencing
* encrypted key material stored in the file system cannot be used until the file system is
* available, and should have BLOB_REQUIRES_FILE_SYSTEM.
*/
enum KeyBlobUsageRequirements : uint32_t {
STANDALONE = 0,
REQUIRES_FILE_SYSTEM = 1,
};
/**
* Possible purposes of a key (or pair).
*/
enum KeyPurpose : uint32_t {
ENCRYPT = 0, /* Usable with RSA, EC and AES keys. */
DECRYPT = 1, /* Usable with RSA, EC and AES keys. */
SIGN = 2, /* Usable with RSA, EC and HMAC keys. */
VERIFY = 3, /* Usable with RSA, EC and HMAC keys. */
/* 4 is reserved */
WRAP_KEY = 5, /* Usable with wrapping keys. */
};
/**
* Keymaster error codes.
*/
enum ErrorCode : int32_t {
OK = 0,
ROOT_OF_TRUST_ALREADY_SET = -1,
UNSUPPORTED_PURPOSE = -2,
INCOMPATIBLE_PURPOSE = -3,
UNSUPPORTED_ALGORITHM = -4,
INCOMPATIBLE_ALGORITHM = -5,
UNSUPPORTED_KEY_SIZE = -6,
UNSUPPORTED_BLOCK_MODE = -7,
INCOMPATIBLE_BLOCK_MODE = -8,
UNSUPPORTED_MAC_LENGTH = -9,
UNSUPPORTED_PADDING_MODE = -10,
INCOMPATIBLE_PADDING_MODE = -11,
UNSUPPORTED_DIGEST = -12,
INCOMPATIBLE_DIGEST = -13,
INVALID_EXPIRATION_TIME = -14,
INVALID_USER_ID = -15,
INVALID_AUTHORIZATION_TIMEOUT = -16,
UNSUPPORTED_KEY_FORMAT = -17,
INCOMPATIBLE_KEY_FORMAT = -18,
UNSUPPORTED_KEY_ENCRYPTION_ALGORITHM = -19, /** For PKCS8 & PKCS12 */
UNSUPPORTED_KEY_VERIFICATION_ALGORITHM = -20, /** For PKCS8 & PKCS12 */
INVALID_INPUT_LENGTH = -21,
KEY_EXPORT_OPTIONS_INVALID = -22,
DELEGATION_NOT_ALLOWED = -23,
KEY_NOT_YET_VALID = -24,
KEY_EXPIRED = -25,
KEY_USER_NOT_AUTHENTICATED = -26,
OUTPUT_PARAMETER_NULL = -27,
INVALID_OPERATION_HANDLE = -28,
INSUFFICIENT_BUFFER_SPACE = -29,
VERIFICATION_FAILED = -30,
TOO_MANY_OPERATIONS = -31,
UNEXPECTED_NULL_POINTER = -32,
INVALID_KEY_BLOB = -33,
IMPORTED_KEY_NOT_ENCRYPTED = -34,
IMPORTED_KEY_DECRYPTION_FAILED = -35,
IMPORTED_KEY_NOT_SIGNED = -36,
IMPORTED_KEY_VERIFICATION_FAILED = -37,
INVALID_ARGUMENT = -38,
UNSUPPORTED_TAG = -39,
INVALID_TAG = -40,
MEMORY_ALLOCATION_FAILED = -41,
IMPORT_PARAMETER_MISMATCH = -44,
SECURE_HW_ACCESS_DENIED = -45,
OPERATION_CANCELLED = -46,
CONCURRENT_ACCESS_CONFLICT = -47,
SECURE_HW_BUSY = -48,
SECURE_HW_COMMUNICATION_FAILED = -49,
UNSUPPORTED_EC_FIELD = -50,
MISSING_NONCE = -51,
INVALID_NONCE = -52,
MISSING_MAC_LENGTH = -53,
KEY_RATE_LIMIT_EXCEEDED = -54,
CALLER_NONCE_PROHIBITED = -55,
KEY_MAX_OPS_EXCEEDED = -56,
INVALID_MAC_LENGTH = -57,
MISSING_MIN_MAC_LENGTH = -58,
UNSUPPORTED_MIN_MAC_LENGTH = -59,
UNSUPPORTED_KDF = -60,
UNSUPPORTED_EC_CURVE = -61,
KEY_REQUIRES_UPGRADE = -62,
ATTESTATION_CHALLENGE_MISSING = -63,
KEYMASTER_NOT_CONFIGURED = -64,
ATTESTATION_APPLICATION_ID_MISSING = -65,
CANNOT_ATTEST_IDS = -66,
ROLLBACK_RESISTANCE_UNAVAILABLE = -67,
HARDWARE_TYPE_UNAVAILABLE = -68,
PROOF_OF_PRESENCE_REQUIRED = -69,
CONCURRENT_PROOF_OF_PRESENCE_REQUESTED = -70,
NO_USER_CONFIRMATION = -71,
DEVICE_LOCKED = -72,
UNIMPLEMENTED = -100,
VERSION_MISMATCH = -101,
UNKNOWN_ERROR = -1000,
// Implementer's namespace for error codes starts at -10000.
};
/**
* Key derivation functions, mostly used in ECIES.
*/
enum KeyDerivationFunction : uint32_t {
/** Do not apply a key derivation function; use the raw agreed key */
NONE = 0,
/** HKDF defined in RFC 5869 with SHA256 */
RFC5869_SHA256 = 1,
/** KDF1 defined in ISO 18033-2 with SHA1 */
ISO18033_2_KDF1_SHA1 = 2,
/** KDF1 defined in ISO 18033-2 with SHA256 */
ISO18033_2_KDF1_SHA256 = 3,
/** KDF2 defined in ISO 18033-2 with SHA1 */
ISO18033_2_KDF2_SHA1 = 4,
/** KDF2 defined in ISO 18033-2 with SHA256 */
ISO18033_2_KDF2_SHA256 = 5,
};
/**
* Hardware authentication type, used by HardwareAuthTokens to specify the mechanism used to
* authentiate the user, and in KeyCharacteristics to specify the allowable mechanisms for
* authenticating to activate a key.
*/
enum HardwareAuthenticatorType : uint32_t {
NONE = 0,
PASSWORD = 1 << 0,
FINGERPRINT = 1 << 1,
// Additional entries must be powers of 2.
ANY = 0xFFFFFFFF,
};
/**
* Device security levels.
*/
enum SecurityLevel : uint32_t {
SOFTWARE = 0,
TRUSTED_ENVIRONMENT = 1,
/**
* STRONGBOX specifies that the secure hardware satisfies the requirements specified in CDD
* 9.11.2.
*/
STRONGBOX = 2,
};
/**
* Formats for key import and export.
*/
enum KeyFormat : uint32_t {
/** X.509 certificate format, for public key export. */
X509 = 0,
/** PCKS#8 format, asymmetric key pair import. */
PKCS8 = 1,
/** Raw bytes, for symmetric key import. */
RAW = 3,
};
struct KeyParameter {
/**
* Discriminates the union/blob field used. The blob cannot be placed in the union, but only
* one of "f" and "blob" may ever be used at a time.
*/
Tag tag;
union IntegerParams {
/* Enum types */
Algorithm algorithm;
BlockMode blockMode;
PaddingMode paddingMode;
Digest digest;
EcCurve ecCurve;
KeyOrigin origin;
KeyBlobUsageRequirements keyBlobUsageRequirements;
KeyPurpose purpose;
KeyDerivationFunction keyDerivationFunction;
HardwareAuthenticatorType hardwareAuthenticatorType;
SecurityLevel hardwareType;
/* Other types */
bool boolValue; // Always true, if a boolean tag is present.
uint32_t integer;
uint64_t longInteger;
uint64_t dateTime;
};
IntegerParams f; // Hidl does not support anonymous unions, so we have to name it.
vec<uint8_t> blob;
};
/**
* KeyCharacteristics defines the attributes of a key, including cryptographic parameters, and usage
* restrictions. It consits of two vectors of KeyParameters, one for "softwareEnforced" attributes
* and one for "hardwareEnforced" attributes.
*
* KeyCharacteristics objects are returned by generateKey, importKey, importWrappedKey and
* getKeyCharacteristics. The IKeymasterDevice secure environment is responsible for allocating the
* parameters, all of which are Tags with associated values, to the correct vector. The
* hardwareEnforced vector must contain only those attributes which are enforced by secure hardware.
* All others should be in the softwareEnforced vector. See the definitions of individual Tag enums
* for specification of which must be hardware-enforced, which may be software-enforced and which
* must never appear in KeyCharacteristics.
*/
struct KeyCharacteristics {
vec<KeyParameter> softwareEnforced;
vec<KeyParameter> hardwareEnforced;
};
/**
* HardwareAuthToken is used to prove successful user authentication, to unlock the use of a key.
*
* HardwareAuthTokens are produced by other secure environment applications, notably GateKeeper and
* Fingerprint, in response to successful user authentication events. These tokens are passed to
* begin(), update(), and finish() to prove that authentication occurred. See those methods for
* more details. It is up to the caller to determine which of the generated auth tokens is
* appropriate for a given key operation.
*/
struct HardwareAuthToken {
/**
* challenge is a value that's used to enable authentication tokens to authorize specific
* events. The primary use case for challenge is to authorize an IKeymasterDevice cryptographic
* operation, for keys that require authentication per operation. See begin() for details.
*/
uint64_t challenge;
/**
* userId is the a "secure" user ID. It is not related to any Android user ID or UID, but is
* created in the Gatekeeper application in the secure environment.
*/
uint64_t userId;
/**
* authenticatorId is the a "secure" user ID. It is not related to any Android user ID or UID,
* but is created in an authentication application in the secure environment, such as the
* Fingerprint application.
*/
uint64_t authenticatorId; // Secure authenticator ID.
/**
* authenticatorType describes the type of authentication that took place, e.g. password or
* fingerprint.
*/
HardwareAuthenticatorType authenticatorType;
/**
* timestamp indicates when the user authentication took place, in milliseconds since some
* starting point (generally the most recent device boot) which all of the applications within
* one secure environment must agree upon. This timestamp is used to determine whether or not
* the authentication occurred recently enough to unlock a key (see Tag::AUTH_TIMEOUT).
*/
Timestamp timestamp;
/**
* MACs are computed with a backward-compatible method, used by Keymaster 3.0, Gatekeeper 1.0
* and Fingerprint 1.0, as well as pre-treble HALs.
*
* The MAC is Constants::AUTH_TOKEN_MAC_LENGTH bytes in length and is computed as follows:
*
* HMAC_SHA256(
* H, 0 || challenge || user_id || authenticator_id || authenticator_type || timestamp)
*
* where ``||'' represents concatenation, the leading zero is a single byte, and all integers
* are represented as unsigned values, the full width of the type. The challenge, userId and
* authenticatorId values are in machine order, but authenticatorType and timestamp are in
* network order (big-endian). This odd construction is compatible with the hw_auth_token_t
* structure,
*
* Note that mac is a vec rather than an array, not because it's actually variable-length but
* because it could be empty. As documented in the IKeymasterDevice::begin,
* IKeymasterDevice::update and IKeymasterDevice::finish doc comments, an empty mac indicates
* that this auth token is empty.
*/
vec<uint8_t> mac;
};
typedef uint64_t OperationHandle;
/**
* HmacSharingParameters holds the data used in the process of establishing a shared HMAC key
* between multiple Keymaster instances. Sharing parameters are returned in this struct by
* getHmacSharingParameters() and send to computeSharedHmac(). See the named methods in IKeymaster
* for details of usage.
*/
struct HmacSharingParameters {
/**
* Either empty or contains a persistent value that is associated with the pre-shared HMAC
* agreement key (see documentation of computeSharedHmac in @4.0::IKeymaster). It is either
* empty or 32 bytes in length.
*/
vec<uint8_t> seed;
/**
* A 32-byte value which is guaranteed to be different each time
* getHmacSharingParameters() is called. Probabilistic uniqueness (i.e. random) is acceptable,
* though a stronger uniqueness guarantee (e.g. counter) is recommended where possible.
*/
uint8_t[32] nonce;
};
/**
* VerificationToken enables one Keymaster instance to validate authorizations for another. See
* verifyAuthorizations() in IKeymaster for details.
*/
struct VerificationToken {
/**
* The operation handle, used to ensure freshness.
*/
uint64_t challenge;
/**
* The current time of the secure environment that generates the VerificationToken. This can be
* checked against auth tokens generated by the same secure environment, which avoids needing to
* synchronize clocks.
*/
Timestamp timestamp;
/**
* A list of the parameters verified. Empty if the only parameters verified are time-related.
* In that case the timestamp is the payload.
*/
vec<KeyParameter> parametersVerified;
/**
* SecurityLevel of the secure environment that generated the token.
*/
SecurityLevel securityLevel;
/**
* 32-byte HMAC-SHA256 of the above values, computed as:
*
* HMAC(H,
* "Auth Verification" || challenge || timestamp || securityLevel || parametersVerified)
*
* where:
*
* ``HMAC'' is the shared HMAC key (see computeSharedHmac() in IKeymaster).
*
* ``||'' represents concatenation
*
* The representation of challenge and timestamp is as 64-bit unsigned integers in big-endian
* order. securityLevel is represented as a 32-bit unsigned integer in big-endian order.
*
* If parametersVerified is non-empty, the representation of parametersVerified is an ASN.1 DER
* encoded representation of the values. The ASN.1 schema used is the AuthorizationList schema
* from the Keystore attestation documentation. If parametersVerified is empty, it is simply
* omitted from the HMAC computation.
*/
vec<uint8_t> mac;
};