1/*
2 * Copyright (C) 2016 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.hardware.keymaster@3.0;
18
19enum TagType : uint32_t {
20    INVALID = 0 << 28, /** Invalid type, used to designate a tag as uninitialized */
21    ENUM = 1 << 28,
22    ENUM_REP = 2 << 28, /** Repeatable enumeration value. */
23    UINT = 3 << 28,
24    UINT_REP = 4 << 28, /** Repeatable integer value */
25    ULONG = 5 << 28,
26    DATE = 6 << 28,
27    BOOL = 7 << 28,
28    BIGNUM = 8 << 28,
29    BYTES = 9 << 28,
30    ULONG_REP = 10 << 28, /** Repeatable long value */
31};
32
33enum Tag : uint32_t {
34    INVALID = TagType:INVALID | 0,
35
36    /**
37     * Tags that must be semantically enforced by hardware and software implementations.
38     */
39
40    /** Crypto parameters */
41    PURPOSE = TagType:ENUM_REP | 1,    /** KeyPurpose. */
42    ALGORITHM = TagType:ENUM | 2,      /** Algorithm. */
43    KEY_SIZE = TagType:UINT | 3,       /** Key size in bits. */
44    BLOCK_MODE = TagType:ENUM_REP | 4, /** BlockMode. */
45    DIGEST = TagType:ENUM_REP | 5,     /** Digest. */
46    PADDING = TagType:ENUM_REP | 6,    /** PaddingMode. */
47    CALLER_NONCE = TagType:BOOL | 7,   /** Allow caller to specify nonce or IV. */
48    MIN_MAC_LENGTH = TagType:UINT | 8, /* Minimum length of MAC or AEAD authentication tag in
49                                        * bits. */
50    KDF = TagType:ENUM_REP | 9,        /** KeyDerivationFunction. */
51    EC_CURVE = TagType:ENUM | 10,      /** EcCurve. */
52
53    /** Algorithm-specific. */
54    RSA_PUBLIC_EXPONENT = TagType:ULONG | 200,
55    ECIES_SINGLE_HASH_MODE = TagType:BOOL | 201, /* Whether the ephemeral public key is fed into the
56                                                  * KDF. */
57    INCLUDE_UNIQUE_ID = TagType:BOOL | 202,      /* If true, attestation certificates for this key
58                                                  * will contain an application-scoped and
59                                                  * time-bounded device-unique ID.*/
60
61    /** Other hardware-enforced. */
62    BLOB_USAGE_REQUIREMENTS = TagType:ENUM | 301, /** KeyBlobUsageRequirements. */
63    BOOTLOADER_ONLY = TagType:BOOL | 302,         /** Usable only by bootloader. */
64
65    /**
66     * Tags that should be semantically enforced by hardware if possible and will otherwise be
67     * enforced by software (keystore).
68     */
69
70    /** Key validity period */
71    ACTIVE_DATETIME = TagType:DATE | 400,             /** Start of validity. */
72    ORIGINATION_EXPIRE_DATETIME = TagType:DATE | 401, /* Date when new "messages" should no longer
73                                                       * be created. */
74    USAGE_EXPIRE_DATETIME = TagType:DATE | 402,       /* Date when existing "messages" should no
75                                                       * longer be trusted. */
76    MIN_SECONDS_BETWEEN_OPS = TagType:UINT | 403,     /* Minimum elapsed time between
77                                                       * cryptographic operations with the key. */
78    MAX_USES_PER_BOOT = TagType:UINT | 404,           /* Number of times the key can be used per
79                                                       * boot. */
80
81    /** User authentication */
82    ALL_USERS = TagType:BOOL | 500,           /** Reserved for future use -- ignore. */
83    USER_ID = TagType:UINT | 501,             /** Reserved for future use -- ignore. */
84    USER_SECURE_ID = TagType:ULONG_REP | 502, /* Secure ID of authorized user or authenticator(s).
85                                               * Disallowed if ALL_USERS or NO_AUTH_REQUIRED is
86                                               * present. */
87    NO_AUTH_REQUIRED = TagType:BOOL | 503,    /** If key is usable without authentication. */
88    USER_AUTH_TYPE = TagType:ENUM | 504,      /* Bitmask of authenticator types allowed when
89                                               * USER_SECURE_ID contains a secure user ID, rather
90                                               * than a secure authenticator ID.  Defined in
91                                               * HardwareAuthenticatorType. */
92    AUTH_TIMEOUT = TagType:UINT | 505,        /* Required freshness of user authentication for
93                                               * private/secret key operations, in seconds.  Public
94                                               * key operations require no authentication.  If
95                                               * absent, authentication is required for every use.
96                                               * Authentication state is lost when the device is
97                                               * powered off. */
98    ALLOW_WHILE_ON_BODY = TagType:BOOL | 506, /* Allow key to be used after authentication timeout
99                                               * if device is still on-body (requires secure on-body
100                                               * sensor. */
101
102    /** Application access control */
103    ALL_APPLICATIONS = TagType:BOOL | 600, /* Specified to indicate key is usable by all
104                                            * applications. */
105    APPLICATION_ID = TagType:BYTES | 601,  /** Byte string identifying the authorized application. */
106    EXPORTABLE = TagType:BOOL | 602,       /* If true, private/secret key can be exported, but only
107                                            * if all access control requirements for use are
108                                            * met. (keymaster2) */
109
110    /**
111     * Semantically unenforceable tags, either because they have no specific meaning or because
112     * they're informational only.
113     */
114    APPLICATION_DATA = TagType:BYTES | 700,      /** Data provided by authorized application. */
115    CREATION_DATETIME = TagType:DATE | 701,      /** Key creation time */
116    ORIGIN = TagType:ENUM | 702,                 /** keymaster_key_origin_t. */
117    ROLLBACK_RESISTANT = TagType:BOOL | 703,     /** Whether key is rollback-resistant. */
118    ROOT_OF_TRUST = TagType:BYTES | 704,         /** Root of trust ID. */
119    OS_VERSION = TagType:UINT | 705,             /** Version of system (keymaster2) */
120    OS_PATCHLEVEL = TagType:UINT | 706,          /** Patch level of system (keymaster2) */
121    UNIQUE_ID = TagType:BYTES | 707,             /** Used to provide unique ID in attestation */
122    ATTESTATION_CHALLENGE = TagType:BYTES | 708, /** Used to provide challenge in attestation */
123    ATTESTATION_APPLICATION_ID = TagType:BYTES | 709, /* Used to identify the set of possible
124                                                       * applications of which one has initiated a
125                                                       * key attestation */
126    ATTESTATION_ID_BRAND = TagType:BYTES | 710,  /* Used to provide the device's brand name to be
127                                                    included in attestation */
128    ATTESTATION_ID_DEVICE = TagType:BYTES | 711, /* Used to provide the device's device name to be
129                                                    included in attestation */
130    ATTESTATION_ID_PRODUCT = TagType:BYTES | 712, /* Used to provide the device's product name to be
131                                                     included in attestation */
132    ATTESTATION_ID_SERIAL = TagType:BYTES | 713, /* Used to provide the device's serial number to be
133                                                    included in attestation */
134    ATTESTATION_ID_IMEI = TagType:BYTES | 714,   /* Used to provide the device's IMEI to be included
135                                                    in attestation */
136    ATTESTATION_ID_MEID = TagType:BYTES | 715,   /* Used to provide the device's MEID to be included
137                                                    in attestation */
138    ATTESTATION_ID_MANUFACTURER = TagType:BYTES | 716, /* Used to provide the device's manufacturer
139                                                          name to be included in attestation */
140    ATTESTATION_ID_MODEL = TagType:BYTES | 717,  /* Used to provide the device's model name to be
141                                                    included in attestation */
142
143    /** Tags used only to provide data to or receive data from operations */
144    ASSOCIATED_DATA = TagType:BYTES | 1000, /** Used to provide associated data for AEAD modes. */
145    NONCE = TagType:BYTES | 1001,           /** Nonce or Initialization Vector */
146    AUTH_TOKEN = TagType:BYTES | 1002,      /* Authentication token that proves secure user
147                                             * authentication has been performed.  Structure defined
148                                             * in hw_auth_token_t in hw_auth_token.h. */
149    MAC_LENGTH = TagType:UINT | 1003,       /** MAC or AEAD authentication tag length in bits. */
150
151    RESET_SINCE_ID_ROTATION = TagType:BOOL | 1004, /* Whether the device has beeen factory reset
152                                                    * since the last unique ID rotation.  Used for
153                                                    * key attestation. */
154};
155
156enum Algorithm : uint32_t {
157    /** Asymmetric algorithms. */
158    RSA = 1,
159    // DSA = 2, -- Removed, do not re-use value 2.
160    EC = 3,
161
162    /** Block ciphers algorithms */
163    AES = 32,
164
165    /** MAC algorithms */
166    HMAC = 128,
167};
168
169/**
170 * Symmetric block cipher modes provided by keymaster implementations.
171 */
172enum BlockMode : uint32_t {
173    /**
174     * Unauthenticated modes, usable only for encryption/decryption and not generally recommended
175     * except for compatibility with existing other protocols. */
176    ECB = 1,
177    CBC = 2,
178    CTR = 3,
179
180    /**
181     * Authenticated modes, usable for encryption/decryption and signing/verification.  Recommended
182     * over unauthenticated modes for all purposes. */
183    GCM = 32,
184};
185
186/**
187 * Padding modes that may be applied to plaintext for encryption operations.  This list includes
188 * padding modes for both symmetric and asymmetric algorithms.  Note that implementations should not
189 * provide all possible combinations of algorithm and padding, only the
190 * cryptographically-appropriate pairs.
191 */
192enum PaddingMode : uint32_t {
193    NONE = 1, /** deprecated */
194    RSA_OAEP = 2,
195    RSA_PSS = 3,
196    RSA_PKCS1_1_5_ENCRYPT = 4,
197    RSA_PKCS1_1_5_SIGN = 5,
198    PKCS7 = 64,
199};
200
201/**
202 * Digests provided by keymaster implementations.
203 */
204enum Digest : uint32_t {
205    NONE = 0,
206    MD5 = 1, /* Optional, may not be implemented in hardware, will be handled in software if
207              * needed. */
208    SHA1 = 2,
209    SHA_2_224 = 3,
210    SHA_2_256 = 4,
211    SHA_2_384 = 5,
212    SHA_2_512 = 6,
213};
214
215/**
216 * Supported EC curves, used in ECDSA
217 */
218enum EcCurve : uint32_t {
219    P_224 = 0,
220    P_256 = 1,
221    P_384 = 2,
222    P_521 = 3,
223};
224
225/**
226 * The origin of a key (or pair), i.e. where it was generated.  Note that ORIGIN can be found in
227 * either the hardware-enforced or software-enforced list for a key, indicating whether the key is
228 * hardware or software-based.  Specifically, a key with GENERATED in the hardware-enforced list is
229 * guaranteed never to have existed outide the secure hardware.
230 */
231enum KeyOrigin : uint32_t {
232    GENERATED = 0, /** Generated in keymaster.  Should not exist outside the TEE. */
233    DERIVED = 1,   /** Derived inside keymaster.  Likely exists off-device. */
234    IMPORTED = 2,  /** Imported into keymaster.  Existed as cleartext in Android. */
235    UNKNOWN = 3,   /* Keymaster did not record origin.  This value can only be seen on keys in a
236                    * keymaster0 implementation.  The keymaster0 adapter uses this value to document
237                    * the fact that it is unkown whether the key was generated inside or imported
238                    * into keymaster. */
239};
240
241/**
242 * Usability requirements of key blobs.  This defines what system functionality must be available
243 * for the key to function.  For example, key "blobs" which are actually handles referencing
244 * encrypted key material stored in the file system cannot be used until the file system is
245 * available, and should have BLOB_REQUIRES_FILE_SYSTEM.  Other requirements entries will be added
246 * as needed for implementations.
247 */
248enum KeyBlobUsageRequirements : uint32_t {
249    STANDALONE = 0,
250    REQUIRES_FILE_SYSTEM = 1,
251};
252
253/**
254 * Possible purposes of a key (or pair).
255 */
256enum KeyPurpose : uint32_t {
257    ENCRYPT = 0,    /** Usable with RSA, EC and AES keys. */
258    DECRYPT = 1,    /** Usable with RSA, EC and AES keys. */
259    SIGN = 2,       /** Usable with RSA, EC and HMAC keys. */
260    VERIFY = 3,     /** Usable with RSA, EC and HMAC keys. */
261    DERIVE_KEY = 4, /** Usable with EC keys. */
262    WRAP_KEY = 5,   /** Usable with wrapping keys. */
263};
264
265/**
266 * Keymaster error codes.
267 */
268enum ErrorCode : uint32_t {
269    OK = 0,
270    ROOT_OF_TRUST_ALREADY_SET = -1,
271    UNSUPPORTED_PURPOSE = -2,
272    INCOMPATIBLE_PURPOSE = -3,
273    UNSUPPORTED_ALGORITHM = -4,
274    INCOMPATIBLE_ALGORITHM = -5,
275    UNSUPPORTED_KEY_SIZE = -6,
276    UNSUPPORTED_BLOCK_MODE = -7,
277    INCOMPATIBLE_BLOCK_MODE = -8,
278    UNSUPPORTED_MAC_LENGTH = -9,
279    UNSUPPORTED_PADDING_MODE = -10,
280    INCOMPATIBLE_PADDING_MODE = -11,
281    UNSUPPORTED_DIGEST = -12,
282    INCOMPATIBLE_DIGEST = -13,
283    INVALID_EXPIRATION_TIME = -14,
284    INVALID_USER_ID = -15,
285    INVALID_AUTHORIZATION_TIMEOUT = -16,
286    UNSUPPORTED_KEY_FORMAT = -17,
287    INCOMPATIBLE_KEY_FORMAT = -18,
288    UNSUPPORTED_KEY_ENCRYPTION_ALGORITHM = -19,   /** For PKCS8 & PKCS12 */
289    UNSUPPORTED_KEY_VERIFICATION_ALGORITHM = -20, /** For PKCS8 & PKCS12 */
290    INVALID_INPUT_LENGTH = -21,
291    KEY_EXPORT_OPTIONS_INVALID = -22,
292    DELEGATION_NOT_ALLOWED = -23,
293    KEY_NOT_YET_VALID = -24,
294    KEY_EXPIRED = -25,
295    KEY_USER_NOT_AUTHENTICATED = -26,
296    OUTPUT_PARAMETER_NULL = -27,
297    INVALID_OPERATION_HANDLE = -28,
298    INSUFFICIENT_BUFFER_SPACE = -29,
299    VERIFICATION_FAILED = -30,
300    TOO_MANY_OPERATIONS = -31,
301    UNEXPECTED_NULL_POINTER = -32,
302    INVALID_KEY_BLOB = -33,
303    IMPORTED_KEY_NOT_ENCRYPTED = -34,
304    IMPORTED_KEY_DECRYPTION_FAILED = -35,
305    IMPORTED_KEY_NOT_SIGNED = -36,
306    IMPORTED_KEY_VERIFICATION_FAILED = -37,
307    INVALID_ARGUMENT = -38,
308    UNSUPPORTED_TAG = -39,
309    INVALID_TAG = -40,
310    MEMORY_ALLOCATION_FAILED = -41,
311    IMPORT_PARAMETER_MISMATCH = -44,
312    SECURE_HW_ACCESS_DENIED = -45,
313    OPERATION_CANCELLED = -46,
314    CONCURRENT_ACCESS_CONFLICT = -47,
315    SECURE_HW_BUSY = -48,
316    SECURE_HW_COMMUNICATION_FAILED = -49,
317    UNSUPPORTED_EC_FIELD = -50,
318    MISSING_NONCE = -51,
319    INVALID_NONCE = -52,
320    MISSING_MAC_LENGTH = -53,
321    KEY_RATE_LIMIT_EXCEEDED = -54,
322    CALLER_NONCE_PROHIBITED = -55,
323    KEY_MAX_OPS_EXCEEDED = -56,
324    INVALID_MAC_LENGTH = -57,
325    MISSING_MIN_MAC_LENGTH = -58,
326    UNSUPPORTED_MIN_MAC_LENGTH = -59,
327    UNSUPPORTED_KDF = -60,
328    UNSUPPORTED_EC_CURVE = -61,
329    KEY_REQUIRES_UPGRADE = -62,
330    ATTESTATION_CHALLENGE_MISSING = -63,
331    KEYMASTER_NOT_CONFIGURED = -64,
332    ATTESTATION_APPLICATION_ID_MISSING = -65,
333    CANNOT_ATTEST_IDS = -66,
334
335    UNIMPLEMENTED = -100,
336    VERSION_MISMATCH = -101,
337
338    UNKNOWN_ERROR = -1000,
339};
340
341/**
342 * Key derivation functions, mostly used in ECIES.
343 */
344enum KeyDerivationFunction : uint32_t {
345    /** Do not apply a key derivation function; use the raw agreed key */
346    NONE = 0,
347    /** HKDF defined in RFC 5869 with SHA256 */
348    RFC5869_SHA256 = 1,
349    /** KDF1 defined in ISO 18033-2 with SHA1 */
350    ISO18033_2_KDF1_SHA1 = 2,
351    /** KDF1 defined in ISO 18033-2 with SHA256 */
352    ISO18033_2_KDF1_SHA256 = 3,
353    /** KDF2 defined in ISO 18033-2 with SHA1 */
354    ISO18033_2_KDF2_SHA1 = 4,
355    /** KDF2 defined in ISO 18033-2 with SHA256 */
356    ISO18033_2_KDF2_SHA256 = 5,
357};
358
359/**
360 * Hardware authentication type, used by HardwareAuthTokens to specify the mechanism used to
361 * authentiate the user, and in KeyCharacteristics to specify the allowable mechanisms for
362 * authenticating to activate a key.
363 */
364enum HardwareAuthenticatorType : uint32_t {
365    NONE = 0,
366    PASSWORD = 1 << 0,
367    FINGERPRINT = 1 << 1,
368    // Additional entries must be powers of 2.
369    ANY = 0xFFFFFFFF,
370};
371
372struct KeyParameter {
373    /**
374     * Discriminates the uinon/blob field used.  The blob cannot be coincided with the union, but
375     * only one of "f" and "blob" is ever used at a time. */
376    Tag tag;
377    union IntegerParams {
378        /** Enum types */
379        Algorithm algorithm;
380        BlockMode blockMode;
381        PaddingMode paddingMode;
382        Digest digest;
383        EcCurve ecCurve;
384        KeyOrigin origin;
385        KeyBlobUsageRequirements keyBlobUsageRequirements;
386        KeyPurpose purpose;
387        KeyDerivationFunction keyDerivationFunction;
388        HardwareAuthenticatorType hardwareAuthenticatorType;
389
390        /** Other types */
391        bool boolValue;  // Always true, if a boolean tag is present.
392        uint32_t integer;
393        uint64_t longInteger;
394        uint64_t dateTime;
395    };
396    IntegerParams f;  // Hidl does not support anonymous unions, so we have to name it.
397    vec<uint8_t> blob;
398};
399
400struct KeyCharacteristics {
401    vec<KeyParameter> softwareEnforced;
402    vec<KeyParameter> teeEnforced;
403};
404
405/**
406 * Data used to prove successful authentication.
407 */
408struct HardwareAuthToken {
409    uint64_t challenge;
410    uint64_t userId;             // Secure User ID, not Android user ID.
411    uint64_t authenticatorId;    // Secure authenticator ID.
412    uint32_t authenticatorType;  // HardwareAuthenticatorType, in network order.
413    uint64_t timestamp;          // In network order.
414    uint8_t[32] hmac;            // HMAC is computed over 0 || challenge || user_id ||
415                                 // authenticator_id || authenticator_type || timestamp, with a
416                                 // prefixed 0 byte (which was a version field in Keymaster1 and
417                                 // Keymaster2) and the fields packed (no padding; so you probably
418                                 // can't just compute over the bytes of the struct).
419};
420
421enum SecurityLevel : uint32_t {
422    SOFTWARE = 0,
423    TRUSTED_ENVIRONMENT = 1,
424};
425
426/**
427 * Formats for key import and export.
428 */
429enum KeyFormat : uint32_t {
430    X509 = 0,  /** for public key export */
431    PKCS8 = 1, /** for asymmetric key pair import */
432    RAW = 3,   /* for symmetric key import and export*/
433};
434
435typedef uint64_t OperationHandle;
436