/*
|
* Copyright (C) 2016 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@3.0;
|
|
enum TagType : uint32_t {
|
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 */
|
};
|
|
enum Tag : uint32_t {
|
INVALID = TagType:INVALID | 0,
|
|
/**
|
* Tags that must be semantically enforced by hardware and software implementations.
|
*/
|
|
/** Crypto parameters */
|
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, /* Minimum length of MAC or AEAD authentication tag in
|
* bits. */
|
KDF = TagType:ENUM_REP | 9, /** KeyDerivationFunction. */
|
EC_CURVE = TagType:ENUM | 10, /** EcCurve. */
|
|
/** Algorithm-specific. */
|
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.*/
|
|
/** Other hardware-enforced. */
|
BLOB_USAGE_REQUIREMENTS = TagType:ENUM | 301, /** KeyBlobUsageRequirements. */
|
BOOTLOADER_ONLY = TagType:BOOL | 302, /** Usable only by bootloader. */
|
|
/**
|
* Tags that should be semantically enforced by hardware if possible and will otherwise be
|
* enforced by software (keystore).
|
*/
|
|
/** Key validity period */
|
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. */
|
|
/** User authentication */
|
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. */
|
|
/** Application access control */
|
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) */
|
|
/**
|
* Semantically unenforceable tags, either because they have no specific meaning or because
|
* they're informational only.
|
*/
|
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 */
|
|
/** Tags used only to provide data to or receive data from operations */
|
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. */
|
};
|
|
enum Algorithm : uint32_t {
|
/** Asymmetric algorithms. */
|
RSA = 1,
|
// DSA = 2, -- Removed, do not re-use value 2.
|
EC = 3,
|
|
/** Block ciphers algorithms */
|
AES = 32,
|
|
/** 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, /* 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,
|
};
|
|
/**
|
* 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 is
|
* guaranteed never to have existed outide the secure hardware.
|
*/
|
enum KeyOrigin : uint32_t {
|
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. */
|
};
|
|
/**
|
* 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.
|
*/
|
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. */
|
DERIVE_KEY = 4, /* Usable with EC keys. */
|
WRAP_KEY = 5, /* Usable with wrapping keys. */
|
};
|
|
/**
|
* Keymaster error codes.
|
*/
|
enum ErrorCode : uint32_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,
|
|
UNIMPLEMENTED = -100,
|
VERSION_MISMATCH = -101,
|
|
UNKNOWN_ERROR = -1000,
|
};
|
|
/**
|
* 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,
|
};
|
|
struct KeyParameter {
|
/**
|
* 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. */
|
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;
|
|
/** 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;
|
};
|
|
struct KeyCharacteristics {
|
vec<KeyParameter> softwareEnforced;
|
vec<KeyParameter> teeEnforced;
|
};
|
|
/**
|
* Data used to prove successful authentication.
|
*/
|
struct HardwareAuthToken {
|
uint64_t challenge;
|
uint64_t userId; // Secure User ID, not Android user ID.
|
uint64_t authenticatorId; // Secure authenticator ID.
|
uint32_t authenticatorType; // HardwareAuthenticatorType, in network order.
|
uint64_t timestamp; // In network order.
|
uint8_t[32] 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).
|
};
|
|
enum SecurityLevel : uint32_t {
|
SOFTWARE = 0,
|
TRUSTED_ENVIRONMENT = 1,
|
};
|
|
/**
|
* Formats for key import and export.
|
*/
|
enum KeyFormat : uint32_t {
|
X509 = 0, /** for public key export */
|
PKCS8 = 1, /** for asymmetric key pair import */
|
RAW = 3, /* for symmetric key import and export*/
|
};
|
|
typedef uint64_t OperationHandle;
|
