/*
 * 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;