Package: android.hardware.keymaster@3.0

types

Properties

OperationHandle

typedef uint64_t OperationHandle

TagType

enum TagType: uint32_t
Details
Members
INVALID = 0 << 28
Invalid type, used to designate a tag as uninitialized
ENUM = 1 << 28
ENUM_REP = 2 << 28
Repeatable enumeration value.
UINT = 3 << 28
UINT_REP = 4 << 28
Repeatable integer value
ULONG = 5 << 28
DATE = 6 << 28
BOOL = 7 << 28
BIGNUM = 8 << 28
BYTES = 9 << 28
ULONG_REP = 10 << 28
Repeatable long value

Tag

enum Tag: uint32_t
Details
Members
INVALID = TagType : INVALID | 0
PURPOSE = TagType : ENUM_REP | 1
KeyPurpose.
ALGORITHM = TagType : ENUM | 2
Algorithm.
KEY_SIZE = TagType : UINT | 3
Key size in bits.
BLOCK_MODE = TagType : ENUM_REP | 4
BlockMode.
DIGEST = TagType : ENUM_REP | 5
Digest.
PADDING = TagType : ENUM_REP | 6
PaddingMode.
CALLER_NONCE = TagType : BOOL | 7
Allow caller to specify nonce or IV.
MIN_MAC_LENGTH = TagType : UINT | 8
KDF = TagType : ENUM_REP | 9
KeyDerivationFunction.
EC_CURVE = TagType : ENUM | 10
EcCurve.
RSA_PUBLIC_EXPONENT = TagType : ULONG | 200
ECIES_SINGLE_HASH_MODE = TagType : BOOL | 201
Whether the ephemeral public key is fed into the KDF.
INCLUDE_UNIQUE_ID = TagType : BOOL | 202
If true, attestation certificates for this key will contain an application-scoped and time-bounded device-unique ID.
BLOB_USAGE_REQUIREMENTS = TagType : ENUM | 301
KeyBlobUsageRequirements.
BOOTLOADER_ONLY = TagType : BOOL | 302
Usable only by bootloader.
ACTIVE_DATETIME = TagType : DATE | 400
Start of validity.
ORIGINATION_EXPIRE_DATETIME = TagType : DATE | 401
Date when new "messages" should no longer be created.
USAGE_EXPIRE_DATETIME = TagType : DATE | 402
Date when existing "messages" should no longer be trusted.
MIN_SECONDS_BETWEEN_OPS = TagType : UINT | 403
Minimum elapsed time between cryptographic operations with the key.
MAX_USES_PER_BOOT = TagType : UINT | 404
Number of times the key can be used per boot.
ALL_USERS = TagType : BOOL | 500
Reserved for future use -- ignore.
USER_ID = TagType : UINT | 501
Reserved for future use -- ignore.
USER_SECURE_ID = TagType : ULONG_REP | 502
Secure ID of authorized user or authenticator(s). Disallowed if ALL_USERS or NO_AUTH_REQUIRED is present.
NO_AUTH_REQUIRED = TagType : BOOL | 503
If key is usable without authentication.
USER_AUTH_TYPE = TagType : ENUM | 504
Bitmask of authenticator types allowed when USER_SECURE_ID contains a secure user ID, rather than a secure authenticator ID.Defined in HardwareAuthenticatorType.
AUTH_TIMEOUT = TagType : UINT | 505
Required freshness of user authentication for private/secret key operations, in seconds.Public key operations require no authentication.If absent, authentication is required for every use.Authentication state is lost when the device is powered off.
ALLOW_WHILE_ON_BODY = TagType : BOOL | 506
Allow key to be used after authentication timeout if device is still on-body(requires secure on-body sensor.
ALL_APPLICATIONS = TagType : BOOL | 600
Specified to indicate key is usable by all applications.
APPLICATION_ID = TagType : BYTES | 601
Byte string identifying the authorized application.
EXPORTABLE = TagType : BOOL | 602
If true, private/secret key can be exported, but only if all access control requirements for use are met .(keymaster2 )
APPLICATION_DATA = TagType : BYTES | 700
Data provided by authorized application.
CREATION_DATETIME = TagType : DATE | 701
Key creation time
ORIGIN = TagType : ENUM | 702
keymaster_key_origin_t.
ROLLBACK_RESISTANT = TagType : BOOL | 703
Whether key is rollback-resistant.
ROOT_OF_TRUST = TagType : BYTES | 704
Root of trust ID.
OS_VERSION = TagType : UINT | 705
Version of system(keymaster2 )
OS_PATCHLEVEL = TagType : UINT | 706
Patch level of system(keymaster2 )
UNIQUE_ID = TagType : BYTES | 707
Used to provide unique ID in attestation
ATTESTATION_CHALLENGE = TagType : BYTES | 708
Used to provide challenge in attestation
ATTESTATION_APPLICATION_ID = TagType : BYTES | 709
Used to identify the set of possible applications of which one has initiated a key attestation
ATTESTATION_ID_BRAND = TagType : BYTES | 710
Used to provide the device's brand name to be included in attestation
ATTESTATION_ID_DEVICE = TagType : BYTES | 711
Used to provide the device's device name to be included in attestation
ATTESTATION_ID_PRODUCT = TagType : BYTES | 712
Used to provide the device's product name to be included in attestation
ATTESTATION_ID_SERIAL = TagType : BYTES | 713
Used to provide the device's serial number to be included in attestation
ATTESTATION_ID_IMEI = TagType : BYTES | 714
Used to provide the device's IMEI to be included in attestation
ATTESTATION_ID_MEID = TagType : BYTES | 715
Used to provide the device's MEID to be included in attestation
ATTESTATION_ID_MANUFACTURER = TagType : BYTES | 716
Used to provide the device's manufacturer name to be included in attestation
ATTESTATION_ID_MODEL = TagType : BYTES | 717
Used to provide the device's model name to be included in attestation
ASSOCIATED_DATA = TagType : BYTES | 1000
Used to provide associated data for AEAD modes.
NONCE = TagType : BYTES | 1001
Nonce or Initialization Vector
AUTH_TOKEN = TagType : BYTES | 1002
Authentication token that proves secure user authentication has been performed.Structure defined in hw_auth_token_t in hw_auth_token.h.
MAC_LENGTH = TagType : UINT | 1003
MAC or AEAD authentication tag length in bits.
RESET_SINCE_ID_ROTATION = TagType : BOOL | 1004
Whether the device has beeen factory reset since the last unique ID rotation.Used for key attestation.

Algorithm

enum Algorithm: uint32_t
Details
Members
RSA = 1
Asymmetric algorithms.
EC = 3
AES = 32
Block ciphers algorithms
HMAC = 128
MAC algorithms

BlockMode

enum BlockMode: uint32_t

Symmetric block cipher modes provided by keymaster implementations.

Details
Members
ECB = 1
Unauthenticated modes, usable only for encryption/decryption and not generally recommended except for compatibility with existing other protocols.
CBC = 2
CTR = 3
GCM = 32
Authenticated modes, usable for encryption/decryption and signing/verification.Recommended over unauthenticated modes for all purposes.

PaddingMode

enum PaddingMode: uint32_t

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.

Details
Members
NONE = 1
RSA_OAEP = 2
deprecated
RSA_PSS = 3
RSA_PKCS1_1_5_ENCRYPT = 4
RSA_PKCS1_1_5_SIGN = 5
PKCS7 = 64

Digest

enum Digest: uint32_t

Digests provided by keymaster implementations.

Details
Members
NONE = 0
MD5 = 1
Optional, may not be implemented in hardware, will be handled in software if needed.
SHA1 = 2
SHA_2_224 = 3
SHA_2_256 = 4
SHA_2_384 = 5
SHA_2_512 = 6

EcCurve

enum EcCurve: uint32_t

Supported EC curves, used in ECDSA

Details
Members
P_224 = 0
P_256 = 1
P_384 = 2
P_521 = 3

KeyOrigin

enum KeyOrigin: uint32_t

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 is guaranteed never to have existed outide the secure hardware.

Details
Members
GENERATED = 0
Generated in keymaster.Should not exist outside the TEE.
DERIVED = 1
Derived inside keymaster.Likely exists off-device.
IMPORTED = 2
Imported into keymaster.Existed as cleartext in Android.
UNKNOWN = 3
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.

KeyBlobUsageRequirements

enum KeyBlobUsageRequirements: uint32_t

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.Other requirements entries will be added as needed for implementations.

Details
Members
STANDALONE = 0
REQUIRES_FILE_SYSTEM = 1

KeyPurpose

enum KeyPurpose: uint32_t

Possible purposes of a key(or pair).

Details
Members
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.
DERIVE_KEY = 4
Usable with EC keys.
WRAP_KEY = 5
Usable with wrapping keys.

ErrorCode

enum ErrorCode: uint32_t

Keymaster error codes.

Details
Members
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
UNIMPLEMENTED = -100
VERSION_MISMATCH = -101
UNKNOWN_ERROR = -1000

KeyDerivationFunction

enum KeyDerivationFunction: uint32_t

Key derivation functions, mostly used in ECIES.

Details
Members
NONE = 0
Do not apply a key derivation function;use the raw agreed key
RFC5869_SHA256 = 1
HKDF defined in RFC 5869 with SHA256
ISO18033_2_KDF1_SHA1 = 2
KDF1 defined in ISO 18033-2 with SHA1
ISO18033_2_KDF1_SHA256 = 3
KDF1 defined in ISO 18033-2 with SHA256
ISO18033_2_KDF2_SHA1 = 4
KDF2 defined in ISO 18033-2 with SHA1
ISO18033_2_KDF2_SHA256 = 5
KDF2 defined in ISO 18033-2 with SHA256

HardwareAuthenticatorType

enum HardwareAuthenticatorType: uint32_t

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.

Details
Members
NONE = 0
PASSWORD = 1 << 0
FINGERPRINT = 1 << 1
ANY = 0xFFFFFFFF

SecurityLevel

enum SecurityLevel: uint32_t
Details
Members
SOFTWARE = 0
TRUSTED_ENVIRONMENT = 1

KeyFormat

enum KeyFormat: uint32_t

Formats for key import and export.

Details
Members
X509 = 0
for public key export
PKCS8 = 1
for asymmetric key pair import
RAW = 3
for symmetric key import and export

KeyParameter

struct KeyParameter {Tag tag; union IntegerParams }; IntegerParams f; vec blob}
Details
Members
tag
Discriminates the uinon/blob field used.The blob cannot be coincided with the union, but only one of "f" and "blob" is ever used at a time.
}
f
blob

KeyCharacteristics

struct KeyCharacteristics {vec softwareEnforced; vec teeEnforced}
Details
Members
softwareEnforced
teeEnforced

HardwareAuthToken

struct HardwareAuthToken {uint64_t challenge; uint64_t userId; uint64_t authenticatorId; uint32_t authenticatorType; uint64_t timestamp; uint8_t hmac}

Data used to prove successful authentication.

Details
Members
challenge
userId
Secure User ID, not Android user ID.
authenticatorId
Secure authenticator ID.
authenticatorType
HardwareAuthenticatorType, in network order.
timestamp
In network order.
hmac
HMAC is computed over 0 || challenge || user_id || authenticator_id || authenticator_type || timestamp, with a prefixed 0 byte(which was a version field in Keymaster1 and Keymaster2)and the fields packed(no padding;so you probably can't just compute over the bytes of the struct).