| /* |
| * 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. For thorough documentation see the implementer's reference, at |
| * https://source.android.com/security/keystore/implementer-ref.html |
| */ |
| interface IKeymasterDevice { |
| |
| /** |
| * Returns information about the underlying Keymaster hardware. |
| * |
| * @return security level of the Keymaster implementation accessed through this HAL. |
| * |
| * @return keymasterName is the name of the Keymaster implementation. |
| * |
| * @return keymasterAuthorName is the name of the author of the Keymaster implementation |
| * (organization name, not individual). |
| */ |
| getHardwareInfo() |
| generates (SecurityLevel securityLevel, string keymasterName, string keymasterAuthorName); |
| |
| /** |
| * Start the creation of an HMAC key, shared with another Keymaster implementation. Any device |
| * with a StrongBox Keymaster has two Keymaster instances, because there must be a TEE Keymaster |
| * 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 |
| * first step in the process for for agreeing on a shared key. It is called by Keystore during |
| * startup if and only if Keystore loads multiple Keymaster HALs. Keystore calls it on each of |
| * the HAL instances and collects the results in preparation for the second step. |
| */ |
| getHmacSharingParameters() generates (ErrorCode error, HmacSharingParameters params); |
| |
| /** |
| * Complete the creation of an HMAC key, shared with another Keymaster implementation. Any |
| * device with a StrongBox Keymaster has two Keymasters instances, because there must be a TEE |
| * Keymaster 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 Keystore during startup if and only if Keystore loads multiple Keymaster HALs. |
| * Keystore calls it on each of the HAL instances, and sends to it all of the |
| * HmacSharingParameters returned by all HALs. |
| * |
| * This method computes the shared 32-byte HMAC ``H'' as follows (all Keymaster 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, 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 Keymaster does not have storage |
| * available to it, but the StrongBox Keymaster does. |
| * |
| * <b>CRITICAL SECURITY REQUIREMENT</b>: All keys created by a Keymaster 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 Keymaster 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. |
| * |
| * 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 of the secure environment.. |
| * |
| * In what follows, T is the Keymaster instance without storage, S is the Keymaster 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 Keymaster instances when |
| * getHmacSharingParameters was called. |
| * |
| * @return sharingCheck A 32-byte value used to verify that all Keymaster 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. If the returned values of all Keymaster instances don't |
| * match, Keystore will assume that HMAC agreement failed. |
| */ |
| computeSharedHmac(vec<HmacSharingParameters> params) |
| generates (ErrorCode error, vec<uint8_t> sharingCheck); |
| |
| /** |
| * Verify authorizations for another Keymaster instance. |
| * |
| * On systems with both a StrongBox and a TEE Keymaster instance it is sometimes useful to ask |
| * the TEE Keymaster 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 Keymaster 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. |
| * |
| * @param authToken A HardwareAuthToken if needed to authorize key usage. |
| */ |
| 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 is guaranteed |
| * not to be the only source of entropy used, and the mixing function is required to be secure, |
| * in the sense that if the RNG is seeded (from any source) with any data the attacker cannot |
| * predict (or control), then the RNG output 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 RNG. |
| * |
| * @return error See the ErrorCode enum in types.hal. |
| */ |
| addRngEntropy(vec<uint8_t> data) generates (ErrorCode error); |
| |
| /** |
| * Generates a key, or key pair, returning a key blob and a description of the key. |
| * |
| * @param keyParams Key generation parameters are defined as Keymaster tag/value pairs, provided |
| * in params. See Tag in types.hal for the full list. |
| * |
| * @return error See the ErrorCode enum in types.hal. |
| * |
| * @return keyBlob Opaque, encrypted descriptor of the generated key. A 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 KeyCharacteristis in |
| * types.hal. |
| */ |
| generateKey(vec<KeyParameter> keyParams) |
| generates (ErrorCode error, vec<uint8_t> keyBlob, KeyCharacteristics keyCharacteristics); |
| |
| /** |
| * Imports a key, or key pair, returning a key blob and/or a description of the key. |
| * |
| * @param keyParams Key generation parameters are defined as Keymaster tag/value pairs, provided |
| * in params. See Tag for the full list. |
| * |
| * @param keyFormat The format of the key material to import. |
| * |
| * @pram keyData The key material to import, in the format specifed in keyFormat. |
| * |
| * @return error See the ErrorCode enum. |
| * |
| * @return keyBlob Opaque, encrypted descriptor of the generated key, which will generally |
| * contain a copy of the key material, wrapped in a key unavailable outside secure |
| * hardware. |
| * |
| * @return keyCharacteristics Decription of the generated key. |
| */ |
| 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. |
| * o encryptedTransportKey is a 256-bit AES key, XORed with a masking key and then encrypted |
| * in RSA-OAEP mode (SHA-256 digest, SHA-1 MGF1 digest) 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, and must be a key algorithm |
| * that supports encryption and must be at least as strong (in key size) as the key to be |
| * imported (per NIST key length recommendations: 112 bits symmetric is equivalent to |
| * 2048-bit RSA or 224-bit EC, 128 bits symmetric ~ 3072-bit RSA or 256-bit EC, etc.). |
| * |
| * @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 error See the ErrorCode enum. |
| * |
| * @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 the characteristics of the specified key, if the keyBlob is valid (implementations |
| * must fully validate the integrity of the key). |
| * |
| * @param keyBlob The opaque descriptor returned by generateKey() or importKey(); |
| * |
| * @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 error See the ErrorCode enum in types.hal. |
| * |
| * @return keyCharacteristics Decription of the generated key. See KeyCharacteristis 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. See KeyFormat in types.hal. |
| * |
| * @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 error See the ErrorCode enum in types.hal. |
| * |
| * @return keyMaterial The public key material in PKCS#8 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 certificate must contain an extension with OID 1.3.6.1.4.1.11129.2.1.17 and |
| * value defined in: |
| * |
| * https://developer.android.com/training/articles/security-key-attestation.html. |
| * |
| * @param keyToAttest The opaque descriptor returned by generateKey() or importKey(). The |
| * referenced key must be asymmetric. |
| * |
| * @param attestParams Parameters for the attestation, notably Tag::ATTESTATION_CHALLENGE. |
| * |
| * @return error See the ErrorCode enum in types.hal. |
| * |
| * @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. |
| */ |
| 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: Keymaster can be upgraded to a |
| * new version with an incompatible key blob format, or the system can be updated to invalidate |
| * the OS version and/or patch level. In either case, attempts to use an old key blob with |
| * getKeyCharacteristics(), exportKey(), attestKey() or begin() must result in Keymaster |
| * returning ErrorCode::KEY_REQUIRES_UPGRADE. The caller must use this method to upgrade the |
| * key blob. |
| * |
| * @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 error See the ErrorCode enum. |
| * |
| * @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(); |
| * |
| * @return error See the ErrorCode enum. |
| */ |
| 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. |
| * |
| * @return error See the ErrorCode enum. |
| */ |
| 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 Keymaster 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). |
| * |
| * @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. |
| * |
| * @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 error See the ErrorCode enum in types.hal. |
| * |
| * @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(). |
| * |
| * If operationHandle is invalid, update() must return ErrorCode::INVALID_OPERATION_HANDLE. |
| * |
| * update() may not consume all of the data provided in the data buffer. update() must return |
| * the amount consumed in inputConsumed. The caller may provide the unconsumed data in a |
| * subsequent call. |
| * |
| * @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 Keymaster 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 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, 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. |
| * |
| * @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 Keymaster 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 error See the ErrorCode enum in types.hal. |
| * |
| * @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); |
| }; |