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

import android.hardware.keymaster@3.0::ErrorCode;
import android.hardware.keymaster@3.0::KeyFormat;

/**
 * Keymaster device definition.
 *
 * == Features ==
 *
 * An IKeymasterDevice provides cryptographic services, including the following categories of
 * operations:
 *
 * o   Key generation
 * o   Import and export (public only) of asymmetric keys
 * o   Import of raw symmetric keys
 * o   Asymmetric encryption and decryption with appropriate padding modes
 * o   Asymmetric signing and verification with digesting and appropriate padding modes
 * o   Symmetric encryption and decryption in appropriate modes, including an AEAD mode
 * o   Generation and verification of symmetric message authentication codes
 * o   Attestation to the presence and configuration of asymmetric keys.
 *
 * Protocol elements, such as purpose, mode and padding, as well as access control constraints, must
 * be specified by the caller when keys are generated or imported and must be permanently bound to
 * the key, ensuring that the key cannot be used in any other way.
 *
 * In addition to the list above, IKeymasterDevice implementations must provide one more service
 * which is not exposed as an API but used internally: Random number generation.  The random number
 * generator must be high-quality and must be used for generation of keys, initialization vectors,
 * random padding and other elements of secure protocols that require randomness.
 *
 * == Types of IKeymasterDevices ==
 *
 * All of the operations and storage of key material must occur in a secure environment.  Secure
 * environments may be either:
 *
 * 1.  Isolated execution environments, such as a separate virtual machine, hypervisor or
 *      purpose-built trusted execution environment like ARM TrustZone.  The isolated environment
 *      must provide complete separation from the Android kernel and user space (collectively called
 *      the "non-secure world", or NSW) so that nothing running in the NSW can observe or manipulate
 *      the results of any computation in the isolated environment.  Isolated execution environments
 *      are identified by the SecurityLevel TRUSTED_ENVIRONMENT.
 *
 * 2.  Completely separate, purpose-built and certified secure CPUs, called "StrongBox" devices.
 *      Examples of StrongBox devices are embedded Secure Elements (eSE) or on-SoC secure processing
 *      units (SPU).  StrongBox environments are identified by the SecurityLevel STRONGBOX.  To
 *      qualify as a StrongBox, a device must meet the requirements specified in CDD 9.11.2.
 *
 * == Necessary Primitives ==
 *
 * All IKeymasterDevice implementations must provide support for the following:
 *
 * o   RSA
 *
 *      - TRUSTED_ENVIRONMENT IKeymasterDevices must support 2048, 3072 and 4096-bit keys.
 *        STRONGBOX IKeymasterDevices must support 2048-bit keys.
 *      - Public exponent F4 (2^16+1)
 *      - Unpadded, RSASSA-PSS and RSASSA-PKCS1-v1_5 padding modes for RSA signing
 *      - TRUSTED_ENVIRONMENT IKeymasterDevices must support MD5, SHA1, SHA-2 224, SHA-2 256, SHA-2
 *        384 and SHA-2 512 digest modes for RSA signing.  STRONGBOX IKeymasterDevices must support
 *        SHA-2 256.
 *      - Unpadded, RSAES-OAEP and RSAES-PKCS1-v1_5 padding modes for RSA encryption.
 *
 * o   ECDSA
 *
 *      - TRUSTED_ENVIRONMENT IKeymasterDevices must support NIST curves P-224, P-256, P-384 and
 *        P-521.  STRONGBOX IKeymasterDevices must support NIST curve P-256.
 *      - TRUSTED_ENVIRONMENT IKeymasterDevices must support SHA1, SHA-2 224, SHA-2 256, SHA-2
 *        384 and SHA-2 512 digest modes.  STRONGBOX IKeymasterDevices must support SHA-2 256.
 *
 * o   AES
 *
 *      - 128 and 256-bit keys
 *      - CBC, CTR, ECB and GCM modes.  The GCM mode must not allow the use of tags smaller than 96
 *        bits or nonce lengths other than 96 bits.
 *      - CBC and ECB modes must support unpadded and PKCS7 padding modes.  With no padding CBC and
 *        ECB-mode operations must fail with ErrorCode::INVALID_INPUT_LENGTH if the input isn't a
 *        multiple of the AES block size.  With PKCS7 padding, GCM and CTR operations must fail with
 *        ErrorCode::INCOMPATIBLE_PADDING_MODE.
 *
 * o   3DES
 *
 *      - 168-bit keys.
 *      - CBC and ECB mode.

 *      - CBC and ECB modes must support unpadded and PKCS7 padding modes.  With no padding CBC and
 *        ECB-mode operations must fail with ErrorCode::INVALID_INPUT_LENGTH if the input isn't a
 *        multiple of the DES block size.
 *
 * o   HMAC
 *
 *      - Any key size that is between 64 and 512 bits (inclusive) and a multiple of 8 must be
 *        supported.  STRONGBOX IKeymasterDevices must not support keys larger than 512 bits.
 *      - TRUSTED_ENVIRONMENT IKeymasterDevices must support MD-5, SHA1, SHA-2-224, SHA-2-256,
 *        SHA-2-384 and SHA-2-512.  STRONGBOX IKeymasterDevices must support SHA-2-256.
 *
 * == Key Access Control ==
 *
 * Hardware-based keys that can never be extracted from the device don't provide much security if an
 * attacker can use them at will (though they're more secure than keys which can be
 * exfiltrated).  Therefore, IKeymasterDevice must enforce access controls.
 *
 * Access controls are defined as an "authorization list" of tag/value pairs.  Authorization tags
 * are 32-bit integers from the Tag enum, and the values are a variety of types, defined in the
 * TagType enum.  Some tags may be repeated to specify multiple values.  Whether a tag may be
 * repeated is specified in the documentation for the tag and in the TagType.  When a key is created
 * or imported, the caller specifies an authorization list.  The IKeymasterDevice must divide the
 * caller-provided authorizations into two lists, those it enforces in hardware and those it does
 * not.  These two lists are returned as the "hardwareEnforced" and "softwareEnforced" elements of
 * the KeyCharacteristics struct.  The IKeymasterDevice must also add the following authorizations
 * to the appropriate list:
 *
 * o    Tag::OS_VERSION, must be hardware-enforced.
 * o    Tag::OS_PATCHLEVEL, must be hardware-enforced.
 * o    Tag::VENDOR_PATCHLEVEL, must be hardware-enforced.
 * o    Tag::BOOT_PATCHLEVEL, must be hardware-enforced.
 * o    Tag::CREATION_DATETIME, must be software-enforced, unless the IKeymasterDevice has access to
 *      a secure time service.
 * o    Tag::ORIGIN, must be hardware-enforced.
 *
 * The IKeymasterDevice must accept arbitrary, unknown tags and return them in the softwareEnforced
 * list.
 *
 * All authorization tags and their values, both hardwareEnforced and softwareEnforced, including
 * unknown tags, must be cryptographically bound to the private/secret key material such that any
 * modification of the portion of the key blob that contains the authorization list makes it
 * impossible for the secure environment to obtain the private/secret key material.  The recommended
 * approach to meet this requirement is to use the full set of authorization tags associated with a
 * key as input to a secure key derivation function used to derive a key that is used to encrypt the
 * private/secret key material.
 *
 * IKeymasterDevice implementations must place any tags they cannot fully and completely enforce in
 * the softwareEnforced list.  For example, Tag::ORIGINATION_EXPIRE_DATETIME provides the date and
 * time after which a key may not be used to encrypt or sign new messages.  Unless the
 * IKeymasterDevice has access to a secure source of current date/time information, it is not
 * possible for the IKeymasterDevice to enforce this tag.  An IKeymasterDevice implementation may
 * not rely on the non-secure world's notion of time, because it could be controlled by an attacker.
 * Similarly, it cannot rely on GPSr time, even if it has exclusive control of the GPSr, because
 * that might be spoofed by attacker RF signals.
 *
 * It is recommended that IKeymasterDevices not enforce any tags they place in the softwareEnforced
 * list.  The IKeymasterDevice caller must enforce them, and it is unnecessary to enforce them
 * twice.
 *
 * Some tags must be enforced by the IKeymasterDevice.  See the detailed documentation on each Tag
 * in types.hal.
 *
 * == Root of Trust Binding ==
 *
 * IKeymasterDevice keys must be bound to a root of trust, which is a bitstring that must be
 * provided to the secure environment (by an unspecified, implementation-defined mechanism) during
 * startup, preferably by the bootloader.  This bitstring must be cryptographically bound to every
 * key managed by the IKeymasterDevice.  As above, the recommended mechanism for this cryptographic
 * binding is to include the Root of Trust data in the input to the key derivation function used to
 * derive a key that is used to encrypt the private/secret key material.
 *
 * The root of trust consists of a bitstring that must be derived from the public key used by
 * Verified Boot to verify the signature on the boot image and from the the lock state of the
 * device.  If the public key is changed to allow a different system image to be used or if the lock
 * state is changed, then all of the IKeymasterDevice-protected keys created by the previous system
 * state must be unusable, unless the previous state is restored.  The goal is to increase the value
 * of the software-enforced key access controls by making it impossible for an attacker-installed
 * operating system to use IKeymasterDevice keys.
 *
 * == Version Binding ==
 *
 * All keys must also be bound to the operating system and patch level of the system image and the
 * patch levels of the vendor image and boot image.  This ensures that an attacker who discovers a
 * weakness in an old version of the software cannot roll a device back to the vulnerable version
 * and use keys created with the newer version.  In addition, when a key with a given version and
 * patch level is used on a device that has been upgraded to a newer version or patch level, the key
 * must be upgraded (See IKeymasterDevice::upgradeKey()) before it can be used, and the previous
 * version of the key must be invalidated.  In this way, as the device is upgraded, the keys will
 * "ratchet" forward along with the device, but any reversion of the device to a previous release
 * will cause the keys to be unusable.
 *
 * This version information must be associated with every key as a set of tag/value pairs in the
 * hardwareEnforced authorization list.  Tag::OS_VERSION, Tag::OS_PATCHLEVEL,
 * Tag::VENDOR_PATCHLEVEL, and Tag::BOOT_PATCHLEVEL must be cryptographically bound to every
 * IKeymasterDevice key, as described in the Key Access Control section above.
 */

interface IKeymasterDevice {

    /**
     * Returns information about the underlying IKeymasterDevice hardware.
     *
     * @return security level of the IKeymasterDevice implementation accessed through this HAL.
     *
     * @return keymasterName is the name of the IKeymasterDevice implementation.
     *
     * @return keymasterAuthorName is the name of the author of the IKeymasterDevice implementation
     *         (organization name, not individual).
     */
    getHardwareInfo()
        generates (SecurityLevel securityLevel, string keymasterName, string keymasterAuthorName);

    /**
     * Start the creation of an HMAC key, shared with another IKeymasterDevice implementation.  Any
     * device with a StrongBox IKeymasterDevice has two IKeymasterDevice instances, because there
     * must be a TEE Keymaster as well.  The HMAC key used to MAC and verify authentication tokens
     * (HardwareAuthToken, VerificationToken and ConfirmationToken all use this HMAC key) must be
     * shared between TEE and StrongBox so they can each validate tokens produced by the other.
     * This method is the first step in the process for agreeing on a shared key.  It is called by
     * Android during startup.  The system calls it on each of the HAL instances and collects the
     * results in preparation for the second step.
     *
     * @return error ErrorCode::OK on success, ErrorCode::UNIMPLEMENTED if HMAC agreement is not
     *         implemented (note that all 4.0::IKeymasterDevice HALS must implement HMAC agreement,
     *         regardless of whether or not the HAL will be used on a device with StrongBox), or
     *         ErrorCode::UNKNOWN_ERROR if the parameters cannot be returned.
     *
     * @return params The HmacSharingParameters to use.  As specified in the HmacSharingParameters
     *         documentation in types.hal, the seed must contain the same value in every invocation
     *         of the method on a given device, and the nonce must return the same value for every
     *         invocation during a boot session.
     */
    getHmacSharingParameters() generates (ErrorCode error, HmacSharingParameters params);

    /**
     * Complete the creation of an HMAC key, shared with another IKeymasterDevice implementation.
     * Any device with a StrongBox IKeymasterDevice has two IKeymasterDevice instances, because
     * there must be a TEE IKeymasterDevice as well.  The HMAC key used to MAC and verify
     * authentication tokens must be shared between TEE and StrongBox so they can each validate
     * tokens produced by the other.  This method is the second and final step in the process for
     * agreeing on a shared key.  It is called by Android during startup.  The system calls it on
     * each of the HAL instances, and sends to it all of the HmacSharingParameters returned by all
     * HALs.
     *
     * To ensure consistent ordering of the HmacSharingParameters, the caller must sort the
     * parameters lexicographically.  See the support/keymaster_utils.cpp for an operator< that
     * defines the appropriate ordering.
     *
     * This method computes the shared 32-byte HMAC ``H'' as follows (all IKeymasterDevice instances
     * perform the same computation to arrive at the same result):
     *
     *     H = CKDF(key = K,
     *              context = P1 || P2 || ... || Pn,
     *              label = "KeymasterSharedMac")
     *
     * where:
     *
     *     ``CKDF'' is the standard AES-CMAC KDF from NIST SP 800-108 in counter mode (see Section
     *           5.1 of the referenced publication).  ``key'', ``context'', and ``label'' are
     *           defined in the standard.  The counter is prefixed and length L appended, as shown
     *           in the construction on page 12 of the standard.  The label string is UTF-8 encoded.
     *
     *     ``K'' is a pre-established shared secret, set up during factory reset.  The mechanism for
     *           establishing this shared secret is implementation-defined, but see below for a
     *           recommended approach, which assumes that the TEE IKeymasterDevice does not have
     *           storage available to it, but the StrongBox IKeymasterDevice does.
     *
     *           CRITICAL SECURITY REQUIREMENT: All keys created by a IKeymasterDevice instance must
     *           be cryptographically bound to the value of K, such that establishing a new K
     *           permanently destroys them.
     *
     *     ``||'' represents concatenation.
     *
     *     ``Pi'' is the i'th HmacSharingParameters value in the params vector.  Note that at
     *           present only two IKeymasterDevice implementations are supported, but this mechanism
     *           extends without modification to any number of implementations.  Encoding of an
     *           HmacSharingParameters is the concatenation of its two fields, i.e. seed || nonce.
     *
     * Note that the label "KeymasterSharedMac" is the 18-byte UTF-8 encoding of the string.
     *
     * Process for establishing K:
     *
     *     Any method of securely establishing K that ensures that an attacker cannot obtain or
     *     derive its value is acceptable.  What follows is a recommended approach, to be executed
     *     during each factory reset.  It relies on use of the factory-installed attestation keys to
     *     mitigate man-in-the-middle attacks.  This protocol requires that one of the instances
     *     have secure persistent storage.  This model was chosen because StrongBox has secure
     *     persistent storage (by definition), but the TEE may not.  The instance without storage is
     *     assumed to be able to derive a unique hardware-bound key (HBK) which is used only for
     *     this purpose, and is not derivable outside the secure environment.
     *
     *     In what follows, T is the IKeymasterDevice instance without storage, S is the
     *     IKeymasterDevice instance with storage:
     *
     *     1. T generates an ephemeral EC P-256 key pair K1.
     *     2. T sends K1_pub to S, signed with T's attestation key.
     *     3. S validates the signature on K1_pub.
     *     4. S generates an ephemeral EC P-256 key pair K2.
     *     5. S sends {K1_pub, K2_pub}, to T, signed with S's attestation key.
     *     6. T validates the signature on {K1_pub, K2_pub}.
     *     7. T uses {K1_priv, K2_pub} with ECDH to compute session secret Q.
     *     8. T generates a random seed S.
     *     9. T computes K = KDF(HBK, S), where KDF is some secure key derivation function.
     *     10. T sends M = AES-GCM-ENCRYPT(Q, {S || K}) to S.
     *     10. S uses {K2_priv, K1_pub} with ECDH to compute session secret Q.
     *     11. S computes S || K = AES-GCM-DECRYPT(Q, M) and stores S and K.
     *
     *     When S receives the getHmacSharingParameters call, it returns the stored S as the seed
     *     and a nonce.  When T receives the same call, it returns an empty seed and a nonce.  When
     *     T receives the computeSharedHmac call, it uses the seed provided by S to compute K.  S,
     *     of course, has K stored.
     *
     * @param params The HmacSharingParameters data returned by all IKeymasterDevice instances when
     *        getHmacSharingParameters was called.
     *
     * @return error ErrorCode::OK in the event that there is no error.  ErrorCode::INVALID_ARGUMENT
     *         if one of the provided parameters is not the value returned by the prior call to
     *         getHmacParameters().
     *
     * @return sharingCheck A 32-byte value used to verify that all IKeymasterDevice instances have
     *         computed the same shared HMAC key.  The sharingCheck value is computed as follows:
     *
     *             sharingCheck = HMAC(H, "Keymaster HMAC Verification")
     *
     *         The string is UTF-8 encoded, 27 bytes in length.  If the returned values of all
     *         IKeymasterDevice instances don't match, clients must assume that HMAC agreement
     *         failed.
     */
    computeSharedHmac(vec<HmacSharingParameters> params)
        generates (ErrorCode error, vec<uint8_t> sharingCheck);

    /**
     * Verify authorizations for another IKeymasterDevice instance.
     *
     * On systems with both a StrongBox and a TEE IKeymasterDevice instance it is sometimes useful
     * to ask the TEE IKeymasterDevice to verify authorizations for a key hosted in StrongBox.
     *
     * For every StrongBox operation, Keystore is required to call this method on the TEE Keymaster,
     * passing in the StrongBox key's hardwareEnforced authorization list and the operation handle
     * returned by StrongBox begin().  The TEE IKeymasterDevice must validate all of the
     * authorizations it can and return those it validated in the VerificationToken.  If it cannot
     * verify any, the parametersVerified field of the VerificationToken must be empty.  Keystore
     * must then pass the VerificationToken to the subsequent invocations of StrongBox update() and
     * finish().
     *
     * StrongBox implementations must return ErrorCode::UNIMPLEMENTED.
     *
     * @param operationHandle the operation handle returned by StrongBox Keymaster's begin().
     *
     * @param parametersToVerify Set of authorizations to verify.  The caller may provide an empty
     *        vector if the only required information is the TEE timestamp.
     *
     * @param authToken A HardwareAuthToken if needed to authorize key usage.
     *
     * @return error ErrorCode::OK on success or ErrorCode::UNIMPLEMENTED if the IKeymasterDevice is
     *         a StrongBox.  If the IKeymasterDevice cannot verify one or more elements of
     *         parametersToVerify it must not return an error code, but just omit the unverified
     *         parameter from the VerificationToken.
     *
     * @return token the verification token.  See VerificationToken in types.hal for details.
     */
    verifyAuthorization(uint64_t operationHandle, vec<KeyParameter> parametersToVerify,
                        HardwareAuthToken authToken)
        generates (ErrorCode error, VerificationToken token);


    /**
     * Adds entropy to the RNG used by Keymaster.  Entropy added through this method must not be the
     * only source of entropy used, and a secure mixing function must be used to mix the entropy
     * provided by this method with internally-generated entropy.  The mixing function must be
     * secure in the sense that if any one of the mixing function inputs is provided with any data
     * the attacker cannot predict (or control), then the output of the seeded CRNG is
     * indistinguishable from random.  Thus, if the entropy from any source is good, the output must
     * be good.
     *
     * @param data Bytes to be mixed into the CRNG seed.  The caller must not provide more than 2
     *        KiB of data per invocation.
     *
     * @return error ErrorCode::OK on success; ErrorCode::INVALID_INPUT_LENGTH if the caller
     *         provides more than 2 KiB of data.
     */
    addRngEntropy(vec<uint8_t> data) generates (ErrorCode error);

    /**
     * Generates a new cryptographic key, specifying associated parameters, which must be
     * cryptographically bound to the key.  IKeymasterDevice implementations must disallow any use
     * of a key in any way inconsistent with the authorizations specified at generation time.  With
     * respect to parameters that the secure environment cannot enforce, the secure environment's
     * obligation is limited to ensuring that the unenforceable parameters associated with the key
     * cannot be modified, so that every call to getKeyCharacteristics returns the original
     * values.  In addition, the characteristics returned by generateKey places parameters correctly
     * in the hardware-enforced and software-enforced lists.  See getKeyCharacteristics for more
     * details.
     *
     * In addition to the parameters provided, generateKey must add the following to the returned
     * characteristics.
     *
     * o Tag::ORIGIN with the value KeyOrigin::GENERATED.
     *
     * o Tag::BLOB_USAGE_REQUIREMENTS with the appropriate value (see KeyBlobUsageRequirements in
     *   types.hal).
     *
     * o Tag::CREATION_DATETIME with the appropriate value.  Note that it is expected that this will
     *   generally be added by the HAL, not by the secure environment, and that it will be in the
     *   software-enforced list.  It must be cryptographically bound to the key, like all tags.
     *
     * o Tag::OS_VERSION, Tag::OS_PATCHLEVEL, Tag::VENDOR_PATCHLEVEL and Tag::BOOT_PATCHLEVEL with
     *   appropriate values.
     *
     * The parameters provided to generateKey depend on the type of key being generated.  This
     * section summarizes the necessary and optional tags for each type of key.  Tag::ALGORITHM is
     * always necessary, to specify the type.
     *
     * == RSA Keys ==
     *
     * The following parameters are required to generate an RSA key:
     *
     * o Tag::Key_SIZE specifies the size of the public modulus, in bits.  If omitted, generateKey
     *   must return ErrorCode::UNSUPPORTED_KEY_SIZE.  Required values for TEE IKeymasterDevice
     *   implementations are 1024, 2048, 3072 and 4096.  StrongBox IKeymasterDevice implementations
     *   must support 2048.
     *
     * o Tag::RSA_PUBLIC_EXPONENT specifies the RSA public exponent value.  If omitted, generateKey
     *   must return ErrorCode::INVALID_ARGUMENT.  The values 3 and 65537 must be supported.  It is
     *   recommended to support all prime values up to 2^64.  If provided with a non-prime value,
     *   generateKey must return ErrorCode::INVALID_ARGUMENT.
     *
     * The following parameters are not necessary to generate a usable RSA key, but generateKey must
     * not return an error if they are omitted:
     *
     * o Tag::PURPOSE specifies allowed purposes.  All KeyPurpose values (see types.hal) must be
     *   supported for RSA keys.
     *
     * o Tag::DIGEST specifies digest algorithms that may be used with the new key.  TEE
     *   IKeymasterDevice implementations must support all Digest values (see types.hal) for RSA
     *   keys.  StrongBox IKeymasterDevice implementations must support SHA_2_256.
     *
     * o Tag::PADDING specifies the padding modes that may be used with the new
     *   key.  IKeymasterDevice implementations must support PaddingMode::NONE,
     *   PaddingMode::RSA_OAEP, PaddingMode::RSA_PSS, PaddingMode::RSA_PKCS1_1_5_ENCRYPT and
     *   PaddingMode::RSA_PKCS1_1_5_SIGN for RSA keys.
     *
     * == ECDSA Keys ==
     *
     * Either Tag::KEY_SIZE or Tag::EC_CURVE must be provided to generate an ECDSA key.  If neither
     * is provided, generateKey must return ErrorCode::UNSUPPORTED_KEY_SIZE.  If Tag::KEY_SIZE is
     * provided, the possible values are 224, 256, 384 and 521, and must be mapped to Tag::EC_CURVE
     * values P_224, P_256, P_384 and P_521, respectively.  TEE IKeymasterDevice implementations
     * must support all curves.  StrongBox implementations must support P_256.
     *
     * == AES Keys ==
     *
     * Only Tag::KEY_SIZE is required to generate an AES key.  If omitted, generateKey must return
     * ErrorCode::UNSUPPORTED_KEY_SIZE.  128 and 256-bit key sizes must be supported.
     *
     * If Tag::BLOCK_MODE is specified with value BlockMode::GCM, then the caller must also provide
     * Tag::MIN_MAC_LENGTH.  If omitted, generateKey must return ErrorCode::MISSING_MIN_MAC_LENGTH.
     *
     *
     * @param keyParams Key generation parameters are defined as IKeymasterDevice tag/value pairs,
     *        provided in params.  See above for detailed specifications of which tags are required
     *        for which types of keys.
     *
     * @return keyBlob Opaque descriptor of the generated key.  The recommended implementation
     *         strategy is to include an encrypted copy of the key material, wrapped in a key
     *         unavailable outside secure hardware.
     *
     * @return keyCharacteristics Description of the generated key.  See the getKeyCharacteristics
     *         method below.
     */
    generateKey(vec<KeyParameter> keyParams)
        generates (ErrorCode error, vec<uint8_t> keyBlob, KeyCharacteristics keyCharacteristics);

    /**
     * Imports key material into an IKeymasterDevice.  Key definition parameters and return values
     * are the same as for generateKey, with the following exceptions:
     *
     * o Tag::KEY_SIZE is not necessary in the input parameters.  If not provided, the
     *   IKeymasterDevice must deduce the value from the provided key material and add the tag and
     *   value to the key characteristics.  If Tag::KEY_SIZE is provided, the IKeymasterDevice must
     *   validate it against the key material.  In the event of a mismatch, importKey must return
     *   ErrorCode::IMPORT_PARAMETER_MISMATCH.
     *
     * o Tag::RSA_PUBLIC_EXPONENT (for RSA keys only) is not necessary in the input parameters.  If
     *   not provided, the IKeymasterDevice must deduce the value from the provided key material and
     *   add the tag and value to the key characteristics.  If Tag::RSA_PUBLIC_EXPONENT is provided,
     *   the IKeymasterDevice must validate it against the key material.  In the event of a
     *   mismatch, importKey must return ErrorCode::IMPORT_PARAMETER_MISMATCH.
     *
     * o Tag::ORIGIN (returned in keyCharacteristics) must have the value KeyOrigin::IMPORTED.
     *
     * @param keyParams Key generation parameters are defined as IKeymasterDevice tag/value pairs,
     *        provided in params.
     *
     * @param keyFormat The format of the key material to import.  See KeyFormat in types.hal.
     *
     * @pram keyData The key material to import, in the format specified in keyFormat.
     *
     * @return keyBlob Opaque descriptor of the imported key.  The recommended implementation
     *         strategy is to include an encrypted copy of the key material, wrapped in a key
     *         unavailable outside secure hardware.
     *
     * @return keyCharacteristics Description of the generated key.  See the getKeyCharacteristics
     *         method below.
     */
    importKey(vec<KeyParameter> keyParams, KeyFormat keyFormat, vec<uint8_t> keyData)
        generates (ErrorCode error, vec<uint8_t> keyBlob, KeyCharacteristics keyCharacteristics);

    /**
     * Securely imports a key, or key pair, returning a key blob and a description of the imported
     * key.
     *
     * @param wrappedKeyData The wrapped key material to import.  The wrapped key is in DER-encoded
     * ASN.1 format, specified by the following schema:
     *
     *     KeyDescription ::= SEQUENCE(
     *         keyFormat INTEGER,                   # Values from KeyFormat enum.
     *         keyParams AuthorizationList,
     *     )
     *
     *     SecureKeyWrapper ::= SEQUENCE(
     *         version INTEGER,                     # Contains value 0
     *         encryptedTransportKey OCTET_STRING,
     *         initializationVector OCTET_STRING,
     *         keyDescription KeyDescription,
     *         encryptedKey OCTET_STRING,
     *         tag OCTET_STRING
     *     )
     *
     *     Where:
     *
     *     o keyFormat is an integer from the KeyFormat enum, defining the format of the plaintext
     *       key material.
     *     o keyParams is the characteristics of the key to be imported (as with generateKey or
     *       importKey).  If the secure import is successful, these characteristics must be
     *       associated with the key exactly as if the key material had been insecurely imported
     *       with the @3.0::IKeymasterDevice::importKey.  See attestKey() for documentation of the
     *       AuthorizationList schema.
     *     o encryptedTransportKey is a 256-bit AES key, XORed with a masking key and then encrypted
     *       with the wrapping key specified by wrappingKeyBlob.
     *     o keyDescription is a KeyDescription, above.
     *     o encryptedKey is the key material of the key to be imported, in format keyFormat, and
     *       encrypted with encryptedEphemeralKey in AES-GCM mode, with the DER-encoded
     *       representation of keyDescription provided as additional authenticated data.
     *     o tag is the tag produced by the AES-GCM encryption of encryptedKey.
     *
     * So, importWrappedKey does the following:
     *
     *     1. Get the private key material for wrappingKeyBlob, verifying that the wrapping key has
     *        purpose KEY_WRAP, padding mode RSA_OAEP, and digest SHA_2_256, returning the
     *        appropriate error if any of those requirements fail.
     *     2. Extract the encryptedTransportKey field from the SecureKeyWrapper, and decrypt
     *        it with the wrapping key.
     *     3. XOR the result of step 2 with maskingKey.
     *     4. Use the result of step 3 as an AES-GCM key to decrypt encryptedKey, using the encoded
     *        value of keyDescription as the additional authenticated data.  Call the result
     *        "keyData" for the next step.
     *     5. Perform the equivalent of calling importKey(keyParams, keyFormat, keyData), except
     *        that the origin tag should be set to SECURELY_IMPORTED.
     *
     * @param wrappingKeyBlob The opaque key descriptor returned by generateKey() or importKey().
     *        This key must have been created with Purpose::WRAP_KEY.
     *
     * @param maskingKey The 32-byte value XOR'd with the transport key in the SecureWrappedKey
     *        structure.
     *
     * @param unwrappingParams must contain any parameters needed to perform the unwrapping
     *        operation.  For example, if the wrapping key is an AES key the block and padding modes
     *        must be specified in this argument.
     *
     * @param passwordSid specifies the password secure ID (SID) of the user that owns the key being
     *        installed.  If the authorization list in wrappedKeyData contains a Tag::USER_SECURE_ID
     *        with a value that has the HardwareAuthenticatorType::PASSWORD bit set, the constructed
     *        key must be bound to the SID value provided by this argument.  If the wrappedKeyData
     *        does not contain such a tag and value, this argument must be ignored.
     *
     * @param biometricSid specifies the biometric secure ID (SID) of the user that owns the key
     *        being installed.  If the authorization list in wrappedKeyData contains a
     *        Tag::USER_SECURE_ID with a value that has the HardwareAuthenticatorType::FINGERPRINT
     *        bit set, the constructed key must be bound to the SID value provided by this argument.
     *        If the wrappedKeyData does not contain such a tag and value, this argument must be
     *        ignored.
     *
     * @return keyBlob Opaque descriptor of the imported key.  It is recommended that the keyBlob
     *         contain a copy of the key material, wrapped in a key unavailable outside secure
     *         hardware.
     */
    importWrappedKey(vec<uint8_t> wrappedKeyData, vec<uint8_t> wrappingKeyBlob,
                     vec<uint8_t> maskingKey, vec<KeyParameter> unwrappingParams,
                     uint64_t passwordSid, uint64_t biometricSid)
        generates(ErrorCode error, vec<uint8_t> keyBlob, KeyCharacteristics keyCharacteristics);

    /**
     * Returns parameters associated with the provided key, divided into two sets: hardware-enforced
     * and software-enforced.  The description here applies equally to the key characteristics lists
     * returned by generateKey, importKey and importWrappedKey.  The characteristics returned by
     * this method completely describe the type and usage of the specified key.
     *
     * The rule that IKeymasterDevice implementations must use for deciding whether a given tag
     * belongs in the hardware-enforced or software-enforced list is that if the meaning of the tag
     * is fully assured by secure hardware, it is hardware enforced.  Otherwise, it's software
     * enforced.
     *
     *
     * @param keyBlob The opaque descriptor returned by generateKey, importKey or importWrappedKey.
     *
     * @param clientId An opaque byte string identifying the client.  This value must match the
     *        Tag::APPLICATION_ID data provided during key generation/import.  Without the correct
     *        value, it must be computationally infeasible for the secure hardware to obtain the key
     *        material.
     *
     * @param appData An opaque byte string provided by the application.  This value must match the
     *        Tag::APPLICATION_DATA data provided during key generation/import.  Without the correct
     *        value, it must be computationally infeasible for the secure hardware to obtain the key
     *        material.
     *
     * @return keyCharacteristics Description of the generated key.  See KeyCharacteristics in
     *         types.hal.
     */
    getKeyCharacteristics(vec<uint8_t> keyBlob, vec<uint8_t> clientId, vec<uint8_t> appData)
        generates (ErrorCode error, KeyCharacteristics keyCharacteristics);

    /**
     * Exports a public key, returning the key in the specified format.
     *
     * @parm keyFormat The format used for export.  Must be KeyFormat::X509.
     *
     * @param keyBlob The opaque descriptor returned by generateKey() or importKey().  The
     *        referenced key must be asymmetric.
     *
     * @param clientId An opaque byte string identifying the client.  This value must match the
     *        Tag::APPLICATION_ID data provided during key generation/import.  Without the correct
     *        value, it must be computationally infeasible for the secure hardware to obtain the key
     *        material.
     *
     * @param appData An opaque byte string provided by the application.  This value must match the
     *        Tag::APPLICATION_DATA data provided during key generation/import.  Without the correct
     *        value, it must be computationally infeasible for the secure hardware to obtain the key
     *        material.
     *
     * @return keyMaterial The public key material in X.509 format.
     */
    exportKey(KeyFormat keyFormat, vec<uint8_t> keyBlob, vec<uint8_t> clientId,
              vec<uint8_t> appData) generates (ErrorCode error, vec<uint8_t> keyMaterial);

    /**
     * Generates a signed X.509 certificate chain attesting to the presence of keyToAttest in
     * Keymaster.
     *
     * The certificates in the chain must be ordered such that each certificate is signed by the
     * subsequent one, up to the root which must be self-signed.  The first certificate in the chain
     * signs the public key info of the attested key and must contain the following entries (see RFC
     * 5280 for details on each):
     *
     * o version -- with value 2
     *
     * o serialNumber -- with value 1 (same value for all keys)
     *
     * o signature -- contains an the AlgorithmIdentifier of the algorithm used to sign, must be
     *   ECDSA for EC keys, RSA for RSA keys.
     *
     * o issuer -- must contain the same value as the Subject field of the next certificate.
     *
     * o validity -- SEQUENCE of two dates, containing the values of Tag::ACTIVE_DATETIME and
     *   Tag::USAGE_EXPIRE_DATETIME.  The tag values are in milliseconds since Jan 1, 1970; see RFD
     *   5280 for the correct representation in certificates.  If Tag::ACTIVE_DATETIME is not
     *   present in the key, the IKeymasterDevice must use the value of Tag::CREATION_DATETIME.  If
     *   Tag::USAGE_EXPIRE_DATETIME is not present, the IKeymasterDevice must use the expiration
     *   date of the batch attestation certificate (see below).
     *
     * o subject -- CN="Android Keystore Key" (same value for all keys)
     *
     * o subjectPublicKeyInfo -- X.509 SubjectPublicKeyInfo containing the attested public key.
     *
     * o Key Usage extension -- digitalSignature bit must be set iff the attested key has
     *   KeyPurpose::SIGN.  dataEncipherment bit must be set iff the attested key has
     *   KeyPurpose::DECRYPT.  keyEncipherment bit must be set iff the attested key has
     *   KeyPurpose::KEY_WRAP.  All other bits must be clear.
     *
     * In addition to the above, the attestation certificate must contain an extension with OID
     * 1.3.6.1.4.1.11129.2.1.17 and value according to the KeyDescription schema defined as:
     *
     * KeyDescription ::= SEQUENCE {
     *     attestationVersion         INTEGER, # Value 3
     *     attestationSecurityLevel   SecurityLevel, # See below
     *     keymasterVersion           INTEGER, # Value 4
     *     keymasterSecurityLevel     SecurityLevel, # See below
     *     attestationChallenge       OCTET_STRING, # Tag::ATTESTATION_CHALLENGE from attestParams
     *     uniqueId                   OCTET_STRING, # Empty unless key has Tag::INCLUDE_UNIQUE_ID
     *     softwareEnforced           AuthorizationList, # See below
     *     hardwareEnforced           AuthorizationList, # See below
     * }
     *
     * SecurityLevel ::= ENUMERATED {
     *     Software                   (0),
     *     TrustedEnvironment         (1),
     *     StrongBox                  (2),
     * }
     *
     * RootOfTrust ::= SEQUENCE {
     *     verifiedBootKey            OCTET_STRING,
     *     deviceLocked               BOOLEAN,
     *     verifiedBootState          VerifiedBootState,
     *     # verifiedBootHash must contain 32-byte value that represents the state of all binaries
     *     # or other components validated by verified boot.  Updating any verified binary or
     *     # component must cause this value to change.
     *     verifiedBootHash           OCTET_STRING,
     * }
     *
     * VerifiedBootState ::= ENUMERATED {
     *     Verified                   (0),
     *     SelfSigned                 (1),
     *     Unverified                 (2),
     *     Failed                     (3),
     * }
     *
     * AuthorizationList ::= SEQUENCE {
     *     purpose                    [1] EXPLICIT SET OF INTEGER OPTIONAL,
     *     algorithm                  [2] EXPLICIT INTEGER OPTIONAL,
     *     keySize                    [3] EXPLICIT INTEGER OPTIONAL,
     *     blockMode                  [4] EXPLICIT SET OF INTEGER OPTIONAL,
     *     digest                     [5] EXPLICIT SET OF INTEGER OPTIONAL,
     *     padding                    [6] EXPLICIT SET OF INTEGER OPTIONAL,
     *     callerNonce                [7] EXPLICIT NULL OPTIONAL,
     *     minMacLength               [8] EXPLICIT INTEGER OPTIONAL,
     *     ecCurve                    [10] EXPLICIT INTEGER OPTIONAL,
     *     rsaPublicExponent          [200] EXPLICIT INTEGER OPTIONAL,
     *     rollbackResistance         [303] EXPLICIT NULL OPTIONAL,
     *     activeDateTime             [400] EXPLICIT INTEGER OPTIONAL,
     *     originationExpireDateTime  [401] EXPLICIT INTEGER OPTIONAL,
     *     usageExpireDateTime        [402] EXPLICIT INTEGER OPTIONAL,
     *     userSecureId               [502] EXPLICIT INTEGER OPTIONAL,
     *     noAuthRequired             [503] EXPLICIT NULL OPTIONAL,
     *     userAuthType               [504] EXPLICIT INTEGER OPTIONAL,
     *     authTimeout                [505] EXPLICIT INTEGER OPTIONAL,
     *     allowWhileOnBody           [506] EXPLICIT NULL OPTIONAL,
     *     trustedUserPresenceReq     [507] EXPLICIT NULL OPTIONAL,
     *     trustedConfirmationReq     [508] EXPLICIT NULL OPTIONAL,
     *     unlockedDeviceReq          [509] EXPLICIT NULL OPTIONAL,
     *     creationDateTime           [701] EXPLICIT INTEGER OPTIONAL,
     *     origin                     [702] EXPLICIT INTEGER OPTIONAL,
     *     rootOfTrust                [704] EXPLICIT RootOfTrust OPTIONAL,
     *     osVersion                  [705] EXPLICIT INTEGER OPTIONAL,
     *     osPatchLevel               [706] EXPLICIT INTEGER OPTIONAL,
     *     attestationApplicationId   [709] EXPLICIT OCTET_STRING OPTIONAL,
     *     attestationIdBrand         [710] EXPLICIT OCTET_STRING OPTIONAL,
     *     attestationIdDevice        [711] EXPLICIT OCTET_STRING OPTIONAL,
     *     attestationIdProduct       [712] EXPLICIT OCTET_STRING OPTIONAL,
     *     attestationIdSerial        [713] EXPLICIT OCTET_STRING OPTIONAL,
     *     attestationIdImei          [714] EXPLICIT OCTET_STRING OPTIONAL,
     *     attestationIdMeid          [715] EXPLICIT OCTET_STRING OPTIONAL,
     *     attestationIdManufacturer  [716] EXPLICIT OCTET_STRING OPTIONAL,
     *     attestationIdModel         [717] EXPLICIT OCTET_STRING OPTIONAL,
     *     vendorPatchLevel           [718] EXPLICIT INTEGER OPTIONAL,
     *     bootPatchLevel             [719] EXPLICIT INTEGER OPTIONAL,
     * }
     *
     * The above schema is mostly a straightforward translation of the IKeymasterDevice tag/value
     * parameter lists to ASN.1:
     *
     * o TagType::ENUM, TagType::UINT, TagType::ULONG and TagType::DATE tags are represented as
     *   ASN.1 INTEGER.
     *
     * o TagType::ENUM_REP, TagType::UINT_REP and TagType::ULONG_REP tags are represented as ASN.1
     *   SET of INTEGER.
     *
     * o TagType::BOOL tags are represented as ASN.1 NULL.  All entries in AuthorizationList are
     *   OPTIONAL, so the presence of the tag means "true", absence means "false".
     *
     * o TagType::BYTES tags are represented as ASN.1 OCTET_STRING.
     *
     * The numeric ASN.1 tag numbers are the same values as the IKeymasterDevice Tag enum values,
     * except with the TagType modifier stripped.
     *
     * The attestation certificate must be signed by a "batch" key, which must be securely
     * pre-installed into the device, generally in the factory, and securely stored to prevent
     * access or extraction.  The batch key must be used only for signing attestation certificates.
     * The batch attestation certificate must be signed by a chain or zero or more intermediates
     * leading to a self-signed roots.  The intermediate and root certificate signing keys must not
     * exist anywhere on the device.
     *
     * == ID Attestation ==
     *
     * ID attestation is a special case of key attestation in which unique device ID values are
     * included in the signed attestation certificate.
     *
     * @param keyToAttest The opaque descriptor returned by generateKey() or importKey().  The
     *        referenced key must be asymmetric.
     *
     * @param attestParams Parameters for the attestation.  Must contain Tag::ATTESTATION_CHALLENGE,
     *        the value of which must be put in the attestationChallenge field of the KeyDescription
     *        ASN.1 structure defined above.
     *
     * @return certChain The attestation certificate, and additional certificates back to the root
     *         attestation certificate, which clients will need to check against a known-good value.
     *         The certificates must be DER-encoded.
     */
    attestKey(vec<uint8_t> keyToAttest, vec<KeyParameter> attestParams)
        generates (ErrorCode error, vec<vec<uint8_t>> certChain);

    /**
     * Upgrades an old key blob.  Keys can become "old" in two ways: IKeymasterDevice can be
     * upgraded to a new version with an incompatible key blob format, or the system can be updated
     * to invalidate the OS version (OS_VERSION tag), system patch level (OS_PATCHLEVEL tag), vendor
     * patch level (VENDOR_PATCH_LEVEL tag), boot patch level (BOOT_PATCH_LEVEL tag) or other,
     * implementation-defined patch level (keymaster implementers are encouraged to extend this HAL
     * with a minor version extension to define validatable patch levels for other images; tags must
     * be defined in the implementer's namespace, starting at 10000).  In either case, attempts to
     * use an old key blob with getKeyCharacteristics(), exportKey(), attestKey() or begin() must
     * result in IKeymasterDevice returning ErrorCode::KEY_REQUIRES_UPGRADE.  The caller must use
     * this method to upgrade the key blob.
     *
     * The upgradeKey method must examine each version or patch level associated with the key.  If
     * any one of them is higher than the corresponding current device value upgradeKey() must
     * return ErrorCode::INVALID_ARGUMENT.  There is one exception: it is always permissible to
     * "downgrade" from any OS_VERSION number to OS_VERSION 0.  For example, if the key has
     * OS_VERSION 080001, it is permissible to upgrade the key if the current system version is
     * 080100, because the new version is larger, or if the current system version is 0, because
     * upgrades to 0 are always allowed.  If the system version were 080000, however, keymaster must
     * return ErrorCode::INVALID_ARGUMENT because that value is smaller than 080001.  Values other
     * than OS_VERSION must never be downgraded.
     *
     * Note that Keymaster versions 2 and 3 required that the system and boot images have the same
     * patch level and OS version.  This requirement is relaxed for 4.0::IKeymasterDevice, and the
     * OS version in the boot image footer is no longer used.
     *
     * @param keyBlobToUpgrade The opaque descriptor returned by generateKey() or importKey();
     *
     * @param upgradeParams A parameter list containing any parameters needed to complete the
     *        upgrade, including Tag::APPLICATION_ID and Tag::APPLICATION_DATA.
     *
     * @return upgradedKeyBlob A new key blob that references the same key as keyBlobToUpgrade, but
     *         is in the new format, or has the new version data.
     */
    upgradeKey(vec<uint8_t> keyBlobToUpgrade, vec<KeyParameter> upgradeParams)
        generates (ErrorCode error, vec<uint8_t> upgradedKeyBlob);

    /**
     * Deletes the key, or key pair, associated with the key blob.  Calling this function on a key
     * with Tag::ROLLBACK_RESISTANCE in its hardware-enforced authorization list must render the key
     * permanently unusable.  Keys without Tag::ROLLBACK_RESISTANCE may or may not be rendered
     * unusable.
     *
     * @param keyBlob The opaque descriptor returned by generateKey() or importKey();
     */
    deleteKey(vec<uint8_t> keyBlob) generates (ErrorCode error);

    /**
     * Deletes all keys in the hardware keystore.  Used when keystore is reset completely.  After
     * this function is called all keys with Tag::ROLLBACK_RESISTANCE in their hardware-enforced
     * authorization lists must be rendered permanently unusable.  Keys without
     * Tag::ROLLBACK_RESISTANCE may or may not be rendered unusable.
     *
     * @return error See the ErrorCode enum.
     */
    deleteAllKeys() generates (ErrorCode error);

    /**
     * Destroys knowledge of the device's ids.  This prevents all device id attestation in the
     * future.  The destruction must be permanent so that not even a factory reset will restore the
     * device ids.
     *
     * Device id attestation may be provided only if this method is fully implemented, allowing the
     * user to permanently disable device id attestation.  If this cannot be guaranteed, the device
     * must never attest any device ids.
     *
     * This is a NOP if device id attestation is not supported.
     */
    destroyAttestationIds() generates (ErrorCode error);

    /**
     * Begins a cryptographic operation using the specified key.  If all is well, begin() must
     * return ErrorCode::OK and create an operation handle which must be passed to subsequent calls
     * to update(), finish() or abort().
     *
     * It is critical that each call to begin() be paired with a subsequent call to finish() or
     * abort(), to allow the IKeymasterDevice implementation to clean up any internal operation
     * state.  The caller's failure to do this may leak internal state space or other internal
     * resources and may eventually cause begin() to return ErrorCode::TOO_MANY_OPERATIONS when it
     * runs out of space for operations.  Any result other than ErrorCode::OK from begin(), update()
     * or finish() implicitly aborts the operation, in which case abort() need not be called (and
     * must return ErrorCode::INVALID_OPERATION_HANDLE if called).  IKeymasterDevice implementations
     * must support 16 concurrent operations.
     *
     * If Tag::APPLICATION_ID or Tag::APPLICATION_DATA were specified during key generation or
     * import, calls to begin must include those tags with the originally-specified values in the
     * inParams argument to this method.  If not, begin() must return ErrorCode::INVALID_KEY_BLOB.
     *
     * == Authorization Enforcement ==
     *
     * The following key authorization parameters must be enforced by the IKeymasterDevice secure
     * environment if the tags were returned in the "hardwareEnforced" list in the
     * KeyCharacteristics.  Public key operations, meaning KeyPurpose::ENCRYPT and
     * KeyPurpose::VERIFY must be allowed to succeed even if authorization requirements are not met.
     *
     * -- All Key Types --
     *
     * The tags in this section apply to all key types.  See below for additional key type-specific
     * tags.
     *
     * o Tag::PURPOSE: The purpose specified in the begin() call must match one of the purposes in
     *   the key authorizations.  If the specified purpose does not match, begin() must return
     *   ErrorCode::UNSUPPORTED_PURPOSE.
     *
     * o Tag::ACTIVE_DATETIME can only be enforced if a trusted UTC time source is available.  If
     *   the current date and time is prior to the tag value, begin() must return
     *   ErrorCode::KEY_NOT_YET_VALID.
     *
     * o Tag::ORIGINATION_EXPIRE_DATETIME can only be enforced if a trusted UTC time source is
     *   available.  If the current date and time is later than the tag value and the purpose is
     *   KeyPurpose::ENCRYPT or KeyPurpose::SIGN, begin() must return ErrorCode::KEY_EXPIRED.
     *
     * o Tag::USAGE_EXPIRE_DATETIME can only be enforced if a trusted UTC time source is
     *   available.  If the current date and time is later than the tag value and the purpose is
     *   KeyPurpose::DECRYPT or KeyPurpose::VERIFY, begin() must return ErrorCode::KEY_EXPIRED.

     * o Tag::MIN_SECONDS_BETWEEN_OPS must be compared with a trusted relative timer indicating the
     *   last use of the key.  If the last use time plus the tag value is less than the current
     *   time, begin() must return ErrorCode::KEY_RATE_LIMIT_EXCEEDED.  See the tag description for
     *   important implementation details.

     * o Tag::MAX_USES_PER_BOOT must be compared against a secure counter that tracks the uses of
     *   the key since boot time.  If the count of previous uses exceeds the tag value, begin() must
     *   return ErrorCode::KEY_MAX_OPS_EXCEEDED.
     *
     * o Tag::USER_SECURE_ID must be enforced by this method if and only if the key also has
     *   Tag::AUTH_TIMEOUT (if it does not have Tag::AUTH_TIMEOUT, the Tag::USER_SECURE_ID
     *   requirement must be enforced by update() and finish()).  If the key has both, then this
     *   method must receive a non-empty HardwareAuthToken in the authToken argument.  For the auth
     *   token to be valid, all of the following have to be true:
     *
     *   o The HMAC field must validate correctly.
     *
     *   o At least one of the Tag::USER_SECURE_ID values from the key must match at least one of
     *     the secure ID values in the token.
     *
     *   o The key must have a Tag::USER_AUTH_TYPE that matches the auth type in the token.
     *
     *   o The timestamp in the auth token plus the value of the Tag::AUTH_TIMEOUT must be less than
     *     the current secure timestamp (which is a monotonic timer counting milliseconds since
     *     boot.)
     *
     *   If any of these conditions are not met, begin() must return
     *   ErrorCode::KEY_USER_NOT_AUTHENTICATED.
     *
     * o Tag::CALLER_NONCE allows the caller to specify a nonce or initialization vector (IV).  If
     *   the key doesn't have this tag, but the caller provided Tag::NONCE to this method,
     *   ErrorCode::CALLER_NONCE_PROHIBITED must be returned.
     *
     * o Tag::BOOTLOADER_ONLY specifies that only the bootloader may use the key.  If this method is
     *   called with a bootloader-only key after the bootloader has finished executing, it must
     *   return ErrorCode::INVALID_KEY_BLOB.  The mechanism for notifying the IKeymasterDevice that
     *   the bootloader has finished executing is implementation-defined.
     *
     * -- RSA Keys --
     *
     * All RSA key operations must specify exactly one padding mode in inParams.  If unspecified or
     * specified more than once, the begin() must return ErrorCode::UNSUPPORTED_PADDING_MODE.
     *
     * RSA signing and verification operations need a digest, as do RSA encryption and decryption
     * operations with OAEP padding mode.  For those cases, the caller must specify exactly one
     * digest in inParams.  If unspecified or specified more than once, begin() must return
     * ErrorCode::UNSUPPORTED_DIGEST.
     *
     * Private key operations (KeyPurpose::DECRYPT and KeyPurpose::SIGN) need authorization of
     * digest and padding, which means that the key authorizations need to contain the specified
     * values.  If not, begin() must return ErrorCode::INCOMPATIBLE_DIGEST or
     * ErrorCode::INCOMPATIBLE_PADDING, as appropriate.  Public key operations (KeyPurpose::ENCRYPT
     * and KeyPurpose::VERIFY) are permitted with unauthorized digest or padding modes.
     *
     * With the exception of PaddingMode::NONE, all RSA padding modes are applicable only to certain
     * purposes.  Specifically, PaddingMode::RSA_PKCS1_1_5_SIGN and PaddingMode::RSA_PSS only
     * support signing and verification, while PaddingMode::RSA_PKCS1_1_5_ENCRYPT and
     * PaddingMode::RSA_OAEP only support encryption and decryption.  begin() must return
     * ErrorCode::UNSUPPORTED_PADDING_MODE if the specified mode does not support the specified
     * purpose.
     *
     * There are some important interactions between padding modes and digests:
     *
     * o PaddingMode::NONE indicates that a "raw" RSA operation is performed.  If signing or
     *   verifying, Digest::NONE is specified for the digest.  No digest is necessary for unpadded
     *   encryption or decryption.
     *
     * o PaddingMode::RSA_PKCS1_1_5_SIGN padding requires a digest.  The digest may be Digest::NONE,
     *   in which case the Keymaster implementation cannot build a proper PKCS#1 v1.5 signature
     *   structure, because it cannot add the DigestInfo structure.  Instead, the IKeymasterDevice
     *   must construct 0x00 || 0x01 || PS || 0x00 || M, where M is the provided message and PS is a
     *   random padding string at least eight bytes in length.  The size of the RSA key has to be at
     *   least 11 bytes larger than the message, otherwise begin() must return
     *   ErrorCode::INVALID_INPUT_LENGTH.
     *
     * o PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT padding does not require a digest.
     *
     * o PaddingMode::RSA_PSS padding requires a digest, which may not be Digest::NONE.  If
     *   Digest::NONE is specified, the begin() must return ErrorCode::INCOMPATIBLE_DIGEST.  In
     *   addition, the size of the RSA key must be at least 2 + D bytes larger than the output size
     *   of the digest, where D is the size of the digest, in bytes.  Otherwise begin() must
     *   return ErrorCode::INCOMPATIBLE_DIGEST.  The salt size must be D.
     *
     * o PaddingMode::RSA_OAEP padding requires a digest, which may not be Digest::NONE.  If
     *   Digest::NONE is specified, begin() must return ErrorCode::INCOMPATIBLE_DIGEST.  The OAEP
     *   mask generation function must be MGF1 and the MGF1 digest must be SHA1, regardless of the
     *   OAEP digest specified.
     *
     * -- EC Keys --
     *
     * EC private key operations must specify exactly one digest in inParams.  If unspecified or
     * specified more than once, begin() must return ErrorCode::UNSUPPORTED_DIGEST.  For private key
     * operations, (KeyPurpose::SIGN), if the specified digest is not in the key's authorization
     * list, begin() must return ErrorCode::INCOMPATIBLE_DIGEST.  Public key operations
     * (KeyPurpose::VERIFY) are permitted with unauthorized digest.
     *
     * -- AES Keys --
     *
     * AES key operations must specify exactly one block mode (Tag::BLOCK_MODE) and one padding mode
     * (Tag::PADDING) in inParams.  If either value is unspecified or specified more than once,
     * begin() must return ErrorCode::UNSUPPORTED_BLOCK_MODE or
     * ErrorCode::UNSUPPORTED_PADDING_MODE.  The specified modes must be authorized by the key,
     * otherwise begin() must return ErrorCode::INCOMPATIBLE_BLOCK_MODE or
     * ErrorCode::INCOMPATIBLE_PADDING_MODE.
     *
     * If the block mode is BlockMode::GCM, inParams must specify Tag::MAC_LENGTH, and the specified
     * value must be a multiple of 8 that is not greater than 128 or less than the value of
     * Tag::MIN_MAC_LENGTH in the key authorizations.  For MAC lengths greater than 128 or
     * non-multiples of 8, begin() must return ErrorCode::UNSUPPORTED_MAC_LENGTH.  For values less
     * than the key's minimum length, begin() must return ErrorCode::INVALID_MAC_LENGTH.
     *
     * If the block mode is BlockMode::GCM or BlockMode::CTR, the specified padding mode must be
     * PaddingMode::NONE.  For BlockMode::ECB or BlockMode::CBC, the mode may be PaddingMode::NONE
     * or PaddingMode::PKCS7.  If the padding mode doesn't meet these conditions, begin() must
     * return ErrorCode::INCOMPATIBLE_PADDING_MODE.
     *
     * If the block mode is BlockMode::CBC, BlockMode::CTR, or BlockMode::GCM, an initialization
     * vector or nonce is required.  In most cases, callers shouldn't provide an IV or nonce and the
     * IKeymasterDevice implementation must generate a random IV or nonce and return it via
     * Tag::NONCE in outParams.  CBC and CTR IVs are 16 bytes.  GCM nonces are 12 bytes.  If the key
     * authorizations contain Tag::CALLER_NONCE, then the caller may provide an IV/nonce with
     * Tag::NONCE in inParams.  If a nonce is provided when Tag::CALLER_NONCE is not authorized,
     * begin() must return ErrorCode::CALLER_NONCE_PROHIBITED.  If a nonce is not provided when
     * Tag::CALLER_NONCE is authorized, IKeymasterDevice must generate a random IV/nonce.
     *
     * -- HMAC keys --
     *
     * HMAC key operations must specify Tag::MAC_LENGTH in inParams.  The specified value must be a
     * multiple of 8 that is not greater than the digest length or less than the value of
     * Tag::MIN_MAC_LENGTH in the key authorizations.  For MAC lengths greater than the digest
     * length or non-multiples of 8, begin() must return ErrorCode::UNSUPPORTED_MAC_LENGTH.  For
     * values less than the key's minimum length, begin() must return ErrorCode::INVALID_MAC_LENGTH.
     *
     * @param purpose The purpose of the operation, one of KeyPurpose::ENCRYPT, KeyPurpose::DECRYPT,
     *        KeyPurpose::SIGN or KeyPurpose::VERIFY.  Note that for AEAD modes, encryption and
     *        decryption imply signing and verification, respectively, but must be specified as
     *        KeyPurpose::ENCRYPT and KeyPurpose::DECRYPT.
     *
     * @param keyBlob The opaque key descriptor returned by generateKey() or importKey().  The key
     *        must have a purpose compatible with purpose and all of its usage requirements must be
     *        satisfied, or begin() must return an appropriate error code (see above).
     *
     * @param inParams Additional parameters for the operation.  If Tag::APPLICATION_ID or
     *        Tag::APPLICATION_DATA were provided during generation, they must be provided here, or
     *        the operation must fail with ErrorCode::INVALID_KEY_BLOB.  For operations that require
     *        a nonce or IV, on keys that were generated with Tag::CALLER_NONCE, inParams may
     *        contain a tag Tag::NONCE.  If Tag::NONCE is provided for a key without
     *        Tag:CALLER_NONCE, ErrorCode::CALLER_NONCE_PROHIBITED must be returned.
     *
     * @param authToken Authentication token.  Callers that provide no token must set all numeric
     *        fields to zero and the MAC must be an empty vector.
     *
     * @return outParams Output parameters.  Used to return additional data from the operation
     *         initialization, notably to return the IV or nonce from operations that generate an IV
     *         or nonce.
     *
     * @return operationHandle The newly-created operation handle which must be passed to update(),
     *         finish() or abort().
     */
    begin(KeyPurpose purpose, vec<uint8_t> keyBlob, vec<KeyParameter> inParams,
          HardwareAuthToken authToken)
        generates (ErrorCode error, vec<KeyParameter> outParams, OperationHandle operationHandle);

    /**
     * Provides data to, and possibly receives output from, an ongoing cryptographic operation begun
     * with begin().  The operation is specified by the operationHandle parameter.
     *
     * If operationHandle is invalid, update() must return ErrorCode::INVALID_OPERATION_HANDLE.
     *
     * To provide more flexibility for buffer handling, implementations of this method have the
     * option of consuming less data than was provided.  The caller is responsible for looping to
     * feed the rest of the data in subsequent calls.  The amount of input consumed must be returned
     * in the inputConsumed parameter.  Implementations must always consume at least one byte, unless
     * the operation cannot accept any more; if more than zero bytes are provided and zero bytes are
     * consumed, callers must consider this an error and abort the operation.
     *
     * Implementations may also choose how much data to return, as a result of the update.  This is
     * only relevant for encryption and decryption operations, because signing and verification
     * return no data until finish.  It is recommended to return data as early as possible, rather
     * than buffer it.
     *
     * If this method returns an error code other than ErrorCode::OK, the operation is aborted and
     * the operation handle must be invalidated.  Any future use of the handle, with this method,
     * finish, or abort, must return ErrorCode::INVALID_OPERATION_HANDLE.
     *
     * == Authorization Enforcement ==
     *
     * Key authorization enforcement is performed primarily in begin().  The one exception is the
     * case where the key has:

     * o One or more Tag::USER_SECURE_IDs, and
     *
     * o Does not have a Tag::AUTH_TIMEOUT
     *
     * In this case, the key requires an authorization per operation, and the update method must
     * receive a non-empty and valid HardwareAuthToken.  For the auth token to be valid, all of the
     * following has to be true:
     *
     *   o The HMAC field must validate correctly.
     *
     *   o At least one of the Tag::USER_SECURE_ID values from the key must match at least one of
     *     the secure ID values in the token.
     *
     *   o The key must have a Tag::USER_AUTH_TYPE that matches the auth type in the token.
     *
     *   o The challenge field in the auth token must contain the operationHandle
     *
     *   If any of these conditions are not met, update() must return
     *   ErrorCode::KEY_USER_NOT_AUTHENTICATED.
     *
     * The caller must provide the auth token on every call to update() and finish().
     *
     * -- RSA keys --
     *
     * For signing and verification operations with Digest::NONE, this method must accept the entire
     * block to be signed or verified in a single update.  It may not consume only a portion of the
     * block in these cases.  However, the caller may choose to provide the data in multiple updates,
     * and update() must accept the data this way as well.  If the caller provides more data to sign
     * than can be used (length of data exceeds RSA key size), update() must return
     * ErrorCode::INVALID_INPUT_LENGTH.
     *
     * -- ECDSA keys --
     *
     * For signing and verification operations with Digest::NONE, this method must accept the entire
     * block to be signed or verified in a single update.  This method may not consume only a
     * portion of the block.  However, the caller may choose to provide the data in multiple updates
     * and update() must accept the data this way as well.  If the caller provides more data to sign
     * than can be used, the data is silently truncated.  (This differs from the handling of excess
     * data provided in similar RSA operations.  The reason for this is compatibility with legacy
     * clients.)
     *
     * -- AES keys --
     *
     * AES GCM mode supports "associated authentication data," provided via the Tag::ASSOCIATED_DATA
     * tag in the inParams argument.  The associated data may be provided in repeated calls
     * (important if the data is too large to send in a single block) but must always precede data
     * to be encrypted or decrypted.  An update call may receive both associated data and data to
     * encrypt/decrypt, but subsequent updates must not include associated data.  If the caller
     * provides associated data to an update call after a call that includes data to
     * encrypt/decrypt, update() must return ErrorCode::INVALID_TAG.
     *
     * For GCM encryption, the AEAD tag must be appended to the ciphertext by finish().  During
     * decryption, the last Tag::MAC_LENGTH bytes of the data provided to the last update call must
     * be the AEAD tag.  Since a given invocation of update cannot know if it's the last invocation,
     * it must process all but the tag length and buffer the possible tag data for processing during
     * finish().
     *
     * @param operationHandle The operation handle returned by begin().
     *
     * @param inParams Additional parameters for the operation.  For AEAD modes, this is used to
     *        specify Tag::ADDITIONAL_DATA.  Note that additional data may be provided in multiple
     *        calls to update(), but only until input data has been provided.
     *
     * @param input Data to be processed.  Note that update() may or may not consume all of the data
     *        provided.  See inputConsumed.
     *
     * @param authToken Authentication token.  Callers that provide no token must set all numeric
     *        fields to zero and the MAC must be an empty vector.
     *
     * @param verificationToken Verification token, used to prove that another IKeymasterDevice HAL
     *        has verified some parameters, and to deliver the other HAL's current timestamp, if
     *        needed.  If not provided, all fields must be initialized to zero and vectors must be
     *        empty.
     *
     * @return error See the ErrorCode enum in types.hal.
     *
     * @return inputConsumed Amount of data that was consumed by update().  If this is less than the
     *         amount provided, the caller may provide the remainder in a subsequent call to
     *         update() or finish().  Every call to update must consume at least one byte, unless
     *         the input is empty, and implementations should consume as much data as reasonably
     *         possible for each call.
     *
     * @return outParams Output parameters, used to return additional data from the operation.
     *
     * @return output The output data, if any.
     */
    update(OperationHandle operationHandle, vec<KeyParameter> inParams, vec<uint8_t> input,
           HardwareAuthToken authToken, VerificationToken verificationToken)
        generates (ErrorCode error, uint32_t inputConsumed, vec<KeyParameter> outParams,
                   vec<uint8_t> output);

    /**
     * Finalizes a cryptographic operation begun with begin() and invalidates operationHandle.
     *
     * This method is the last one called in an operation, so all processed data must be returned.
     *
     * Whether it completes successfully or returns an error, this method finalizes the operation
     * and therefore must invalidate the provided operation handle.  Any future use of the handle,
     * with finish(), update(), or abort(), must return ErrorCode::INVALID_OPERATION_HANDLE.
     *
     * Signing operations return the signature as the output.  Verification operations accept the
     * signature in the signature parameter, and return no output.
     *
     * == Authorization enforcement ==
     *
     * Key authorization enforcement is performed primarily in begin().  The exceptions are
     * authorization per operation keys and confirmation-required keys.
     *
     * Authorization per operation keys are the case where the key has one or more
     * Tag::USER_SECURE_IDs, and does not have a Tag::AUTH_TIMEOUT.  In this case, the key requires
     * an authorization per operation, and the finish method must receive a non-empty and valid
     * authToken.  For the auth token to be valid, all of the following has to be true:
     *
     *   o The HMAC field must validate correctly.
     *
     *   o At least one of the Tag::USER_SECURE_ID values from the key must match at least one of
     *     the secure ID values in the token.
     *
     *   o The key must have a Tag::USER_AUTH_TYPE that matches the auth type in the token.
     *
     *   o The challenge field in the auth token must contain the operationHandle
     *
     *   If any of these conditions are not met, update() must return
     *   ErrorCode::KEY_USER_NOT_AUTHENTICATED.
     *
     * The caller must provide the auth token on every call to update() and finish().
     *
     * Confirmation-required keys are keys that were generated with
     * Tag::TRUSTED_CONFIRMATION_REQUIRED.  For these keys, when doing a signing operation the
     * caller must pass a KeyParameter Tag::CONFIRMATION_TOKEN to finish().  Implementations must
     * check the confirmation token by computing the 32-byte HMAC-SHA256 over all of the
     * to-be-signed data, prefixed with the 18-byte UTF-8 encoded string "confirmation token". If
     * the computed value does not match the Tag::CONFIRMATION_TOKEN parameter, finish() must not
     * produce a signature and must return ErrorCode::NO_USER_CONFIRMATION.
     *
     * -- RSA keys --
     *
     * Some additional requirements, depending on the padding mode:
     *
     * o PaddingMode::NONE.  For unpadded signing and encryption operations, if the provided data is
     *   shorter than the key, the data must be zero-padded on the left before
     *   signing/encryption.  If the data is the same length as the key, but numerically larger,
     *   finish() must return ErrorCode::INVALID_ARGUMENT.  For verification and decryption
     *   operations, the data must be exactly as long as the key.  Otherwise, return
     *   ErrorCode::INVALID_INPUT_LENGTH.
     *
     * o PaddingMode::RSA_PSS.  For PSS-padded signature operations, the PSS salt length must match
     *   the size of the PSS digest selected.  The digest specified with Tag::DIGEST in inputParams
     *   on begin() must be used as the PSS digest algorithm, MGF1 must be used as the mask
     *   generation function and SHA1 must be used as the MGF1 digest algorithm.
     *
     * o PaddingMode::RSA_OAEP.  The digest specified with Tag::DIGEST in inputParams on begin is
     *   used as the OAEP digest algorithm, MGF1 must be used as the mask generation function and
     *   and SHA1 must be used as the MGF1 digest algorithm.
     *
     * -- ECDSA keys --
     *
     * If the data provided for unpadded signing or verification is too long, truncate it.
     *
     * -- AES keys --
     *
     * Some additional conditions, depending on block mode:
     *
     * o BlockMode::ECB or BlockMode::CBC.  If padding is PaddingMode::NONE and the data length is
     *  not a multiple of the AES block size, finish() must return
     *  ErrorCode::INVALID_INPUT_LENGTH.  If padding is PaddingMode::PKCS7, pad the data per the
     *  PKCS#7 specification, including adding an additional padding block if the data is a multiple
     *  of the block length.
     *
     * o BlockMode::GCM.  During encryption, after processing all plaintext, compute the tag
     *   (Tag::MAC_LENGTH bytes) and append it to the returned ciphertext.  During decryption,
     *   process the last Tag::MAC_LENGTH bytes as the tag.  If tag verification fails, finish()
     *   must return ErrorCode::VERIFICATION_FAILED.
     *
     * @param operationHandle The operation handle returned by begin().  This handle must be invalid
     *        when finish() returns.
     *
     * @param inParams Additional parameters for the operation.  For AEAD modes, this is used to
     *        specify Tag::ADDITIONAL_DATA, but only if no input data was provided to update().
     *
     * @param input Data to be processed, per the parameters established in the call to begin().
     *        finish() must consume all provided data or return ErrorCode::INVALID_INPUT_LENGTH.
     *
     * @param signature The signature to be verified if the purpose specified in the begin() call
     *        was KeyPurpose::VERIFY.
     *
     * @param authToken Authentication token.  Callers that provide no token must set all numeric
     *        fields to zero and the MAC must be an empty vector.
     *
     * @param verificationToken Verification token, used to prove that another IKeymasterDevice HAL
     *        has verified some parameters, and to deliver the other HAL's current timestamp, if
     *        needed.  If not provided, all fields must be initialized to zero and vectors empty.
     *
     * @return outParams Any output parameters generated by finish().
     *
     * @return output The output data, if any.
     */
    finish(OperationHandle operationHandle, vec<KeyParameter> inParams, vec<uint8_t> input,
           vec<uint8_t> signature, HardwareAuthToken authToken, VerificationToken verificationToken)
        generates (ErrorCode error, vec<KeyParameter> outParams, vec<uint8_t> output);

    /**
     * Aborts a cryptographic operation begun with begin(), freeing all internal resources and
     * invalidating operationHandle.
     *
     * @param operationHandle The operation handle returned by begin().  This handle must be
     *        invalid when abort() returns.
     *
     * @return error See the ErrorCode enum in types.hal.
     */
    abort(OperationHandle operationHandle) generates (ErrorCode error);
};