Package: android.hardware.keymaster@3.0

IKeymasterDevice

interface IKeymasterDevice

Keymaster device definition.For thorough documentation see the implementer's reference, at https ://source.android.com/security/keystore/implementer-ref.html

Methods

getHardwareFeatures

getHardwareFeatures ()
generates (bool isSecure, bool supportsEllipticCurve, bool supportsSymmetricCryptography, bool supportsAttestation, bool supportsAllDigests, string keymasterName, string keymasterAuthorName)

Returns information about the underlying keymaster hardware.

Details
Generates
isSecure
is true if keys are stored and never leave secure hardware(Trusted Execution Environment or similar). CDD requires that all devices initially launched with Marshmallow or later must have secure hardware.
supportsEllipticCurve
is true if the hardware supports Elliptic Curve cryptography with the NIST curves(P-224, P-256, P-384, and P-521). CDD requires that all devices initially launched with Nougat or later must support Elliptic Curve cryptography.
supportsSymmetricCryptography
is true if the hardware supports symmetric cryptography, including AES and HMAC.CDD requires that all devices initially launched with Nougat or later must support hardware enforcement of Keymaster authorizations.
supportsAttestation
is true if the hardware supports generation of Keymaster public key attestation certificates, signed with a key injected in a secure environment.CDD requires that all devices initially launched with Android O or later must support hardware attestation.
supportsAllDigests
is true if the hardware supports all keymaster digest functions, namely ND-5, SHA-1, SHA-224, SHA-256, SHA-384 and SHA-512.CDD requires that all devices launched initially with Android O or later must support all digests.
keymasterName
is the name of the keymaster implementation.
keymasterAuthorName
is the name of the author of the keymaster implementation(generally this should be the name of an organization, not an individual.)

addRngEntropy

addRngEntropy (vec<uint8_t> data)
generates (ErrorCode error)

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.

Details
Parameters
data
Bytes to be mixed into the RNG.
Generates
error
See the ErrorCode enum in types.hal.

generateKey

generateKey (vec<KeyParameter> keyParams)
generates (ErrorCode error, vec<uint8_t> keyBlob, KeyCharacteristics keyCharacteristics)

Generates a key, or key pair, returning a key blob and/or a description of the key.

Details
Parameters
keyParams
Key generation parameters are defined as keymaster tag/value pairs, provided in params.See Tag in types.hal for the full list.
Generates
error
See the ErrorCode enum in types.hal.
keyBlob
Opaque, encrypted descriptor of the generated key, which generally contains a copy of the key material, wrapped in a key unavailable outside secure hardware.
keyCharacteristics
Description of the generated key.See KeyCharacteristis in types.hal.

importKey

importKey (vec<KeyParameter> params, KeyFormat keyFormat, vec<uint8_t> keyData)
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.

@pram keyData The key material to import, in the format specifed in keyFormat.

Details
Parameters
params
keyFormat
The format of the key material to import.See KeyFormat in types.hal.
keyData
Generates
error
See the ErrorCode enum.
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.
keyCharacteristics
Decription of the generated key.See KeyCharacteristis.

getKeyCharacteristics

getKeyCharacteristics (vec<uint8_t> keyBlob, vec<uint8_t> clientId, vec<uint8_t> appData)
generates (ErrorCode error, KeyCharacteristics keyCharacteristics)

Returns the characteristics of the specified key, if the keyBlob is valid(implementations must fully validate the integrity of the key).

Details
Parameters
keyBlob
The opaque descriptor returned by generateKey() or importKey() ;
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 cryptographically impossible for the secure hardware to obtain the key material.
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 cryptographically impossible for the secure hardware to obtain the key material.
Generates
error
See the ErrorCode enum in types.hal.
keyCharacteristics
Decription of the generated key.See KeyCharacteristis in types.hal.

exportKey

exportKey (KeyFormat keyFormat, vec<uint8_t> keyBlob, vec<uint8_t> clientId, vec<uint8_t> appData)
generates (ErrorCode error, vec<uint8_t> keyMaterial)

Exports a public key, returning the key in the specified format.

@parm keyFormat The format used for export.See KeyFormat in types.hal.

Details
Parameters
keyFormat
keyBlob
The opaque descriptor returned by generateKey() or importKey().The referenced key must be asymmetric.
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 cryptographically impossible for the secure hardware to obtain the key material.
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 cryptographically impossible for the secure hardware to obtain the key material.
Generates
error
See the ErrorCode enum in types.hal.
keyMaterial
The public key material in PKCS#8 format.

attestKey

attestKey (vec<uint8_t> keyToAttest, vec<KeyParameter> attestParams)
generates (ErrorCode error, vec<vec<uint8_t>> certChain)

Generates a signed X.509 certificate chain attesting to the presence of keyToAttest in keymaster.The certificate will 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.

Details
Parameters
keyToAttest
The opaque descriptor returned by generateKey() or importKey().The referenced key must be asymmetric.
attestParams
Parameters for the attestation, notably Tag::ATTESTATION_CHALLENGE.
Generates
error
See the ErrorCode enum in types.hal.
certChain

upgradeKey

upgradeKey (vec<uint8_t> keyBlobToUpgrade, vec<KeyParameter> upgradeParams)
generates (ErrorCode error, vec<uint8_t> upgradedKeyBlob)

Upgrades an old key.Keys can become "old" in two ways:Keymaster can be upgraded to a new version, or the system can be updated to invalidate the OS version and/or patch level.In either case, attempts to use an old key with getKeyCharacteristics(), exportKey(), attestKey() or begin() will result in keymaster returning ErrorCode::KEY_REQUIRES_UPGRADE.This method must then be called to upgrade the key.

Details
Parameters
keyBlobToUpgrade
The opaque descriptor returned by generateKey() or importKey() ;
upgradeParams
A parameter list containing any parameters needed to complete the upgrade, including Tag::APPLICATION_ID and Tag::APPLICATION_DATA.
Generates
error
See the ErrorCode enum.
upgradedKeyBlob

deleteKey

deleteKey (vec<uint8_t> keyBlob)
generates (ErrorCode error)

Deletes the key, or key pair, associated with the key blob.After calling this function it will be impossible to use the key for any other operations.May be applied to keys from foreign roots of trust(keys not usable under the current root of trust).

This is a NOP for keys that don't have rollback protection.

Details
Parameters
keyBlob
Generates
error
See the ErrorCode enum.

deleteAllKeys

deleteAllKeys ()
generates (ErrorCode error)

Deletes all keys in the hardware keystore.Used when keystore is reset completely.After calling this function it will be impossible to use any previously generated or imported key blobs for any operations.

This is a NOP if keys don't have rollback protection.

Details
Generates
error
See the ErrorCode enum.

destroyAttestationIds

destroyAttestationIds ()
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.

Details
Generates
error
See the ErrorCode enum.

begin

begin (KeyPurpose purpose, vec<uint8_t> key, vec<KeyParameter> inParams)
generates (ErrorCode error, vec<KeyParameter> outParams, OperationHandle operationHandle)

Begins a cryptographic operation using the specified key.If all is well, begin() will 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.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 will return ErrorCode::INVALID_OPERATION_HANDLE if called).

Details
Parameters
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.
key
inParams
Additional parameters for the operation.This is typically used to provide authentication data, with Tag::AUTH_TOKEN.If Tag::APPLICATION_ID or Tag::APPLICATION_DATA were provided during generation, they must be provided here, or the operation will 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.
Generates
error
See the ErrorCode enum in types.hal.
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.
operationHandle
The newly-created operation handle which must be passed to update(), finish() or abort().

update

update (OperationHandle operationHandle, vec<KeyParameter> inParams, vec<uint8_t> input)
generates (ErrorCode error, uint32_t inputConsumed, vec<KeyParameter> outParams, vec<uint8_t> output)

Provides data to, and possibly receives output from, an ongoing cryptographic operation begun with begin().

If operationHandle is invalid, update() will return ErrorCode::INVALID_OPERATION_HANDLE.

update() may not consume all of the data provided in the data buffer.update() will return the amount consumed in inputConsumed.The caller may provide the unconsumed data in a subsequent call.

Details
Parameters
operationHandle
The operation handle returned by begin().
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.
input
Data to be processed, per the parameters established in the call to begin().Note that update() may or may not consume all of the data provided.See inputConsumed.
Generates
error
See the ErrorCode enum in types.hal.
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().
outParams
Output parameters, used to return additional data from the operation The caller takes ownership of the output parameters array and must free it with keymaster_free_param_set().
output
The output data, if any.

finish

finish (OperationHandle operationHandle, vec<KeyParameter> inParams, vec<uint8_t> input, vec<uint8_t> signature)
generates (ErrorCode error, vec<KeyParameter> outParams, vec<uint8_t> output)

Finalizes a cryptographic operation begun with begin() and invalidates operationHandle.

Details
Parameters
operationHandle
The operation handle returned by begin().This handle will be invalid when finish() returns.
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().
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.
signature
The signature to be verified if the purpose specified in the begin() call was KeyPurpose::VERIFY.
Generates
error
See the ErrorCode enum in types.hal.
outParams
Any output parameters generated by finish().
output
The output data, if any.

abort

abort (OperationHandle operationHandle)
generates (ErrorCode error)

Aborts a cryptographic operation begun with begin(), freeing all internal resources and invalidating operationHandle.

Details
Parameters
operationHandle
The operation handle returned by begin().This handle will be invalid when abort() returns.
Generates
error
See the ErrorCode enum in types.hal.