keymaster1_device Struct Reference

Data Fields
keymaster1_device Struct Reference

#include < keymaster1.h >

Data Fields

struct hw_device_t   common
 
uint32_t  client_version
 
uint32_t  flags
 
void *  context
 
int(*  generate_keypair )(const struct keymaster1_device *dev, const keymaster_keypair_t key_type, const void *key_params, uint8_t **key_blob, size_t *key_blob_length)
 
int(*  import_keypair )(const struct keymaster1_device *dev, const uint8_t *key, const size_t key_length, uint8_t **key_blob, size_t *key_blob_length)
 
int(*  get_keypair_public )(const struct keymaster1_device *dev, const uint8_t *key_blob, const size_t key_blob_length, uint8_t **x509_data, size_t *x509_data_length)
 
int(*  delete_keypair )(const struct keymaster1_device *dev, const uint8_t *key_blob, const size_t key_blob_length)
 
int(*  delete_all )(const struct keymaster1_device *dev)
 
int(*  sign_data )(const struct keymaster1_device *dev, const void *signing_params, const uint8_t *key_blob, const size_t key_blob_length, const uint8_t *data, const size_t data_length, uint8_t **signed_data, size_t *signed_data_length)
 
int(*  verify_data )(const struct keymaster1_device *dev, const void *signing_params, const uint8_t *key_blob, const size_t key_blob_length, const uint8_t *signed_data, const size_t signed_data_length, const uint8_t *signature, const size_t signature_length)
 
keymaster_error_t (*  get_supported_algorithms )(const struct keymaster1_device *dev, keymaster_algorithm_t **algorithms, size_t *algorithms_length)
 
keymaster_error_t (*  get_supported_block_modes )(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_purpose_t purpose, keymaster_block_mode_t **modes, size_t *modes_length)
 
keymaster_error_t (*  get_supported_padding_modes )(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_purpose_t purpose, keymaster_padding_t **modes, size_t *modes_length)
 
keymaster_error_t (*  get_supported_digests )(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_purpose_t purpose, keymaster_digest_t **digests, size_t *digests_length)
 
keymaster_error_t (*  get_supported_import_formats )(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_key_format_t **formats, size_t *formats_length)
 
keymaster_error_t (*  get_supported_export_formats )(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_key_format_t **formats, size_t *formats_length)
 
keymaster_error_t (*  add_rng_entropy )(const struct keymaster1_device *dev, const uint8_t *data, size_t data_length)
 
keymaster_error_t (*  generate_key )(const struct keymaster1_device *dev, const keymaster_key_param_set_t *params, keymaster_key_blob_t *key_blob, keymaster_key_characteristics_t **characteristics)
 
keymaster_error_t (*  get_key_characteristics )(const struct keymaster1_device *dev, const keymaster_key_blob_t *key_blob, const keymaster_blob_t *client_id, const keymaster_blob_t *app_data, keymaster_key_characteristics_t **characteristics)
 
keymaster_error_t (*  import_key )(const struct keymaster1_device *dev, const keymaster_key_param_set_t *params, keymaster_key_format_t key_format, const keymaster_blob_t *key_data, keymaster_key_blob_t *key_blob, keymaster_key_characteristics_t **characteristics)
 
keymaster_error_t (*  export_key )(const struct keymaster1_device *dev, keymaster_key_format_t export_format, const keymaster_key_blob_t *key_to_export, const keymaster_blob_t *client_id, const keymaster_blob_t *app_data, keymaster_blob_t *export_data)
 
keymaster_error_t (*  delete_key )(const struct keymaster1_device *dev, const keymaster_key_blob_t *key)
 
keymaster_error_t (*  delete_all_keys )(const struct keymaster1_device *dev)
 
keymaster_error_t (*  begin )(const struct keymaster1_device *dev, keymaster_purpose_t purpose, const keymaster_key_blob_t *key, const keymaster_key_param_set_t *in_params, keymaster_key_param_set_t *out_params, keymaster_operation_handle_t *operation_handle)
 
keymaster_error_t (*  update )(const struct keymaster1_device *dev, keymaster_operation_handle_t operation_handle, const keymaster_key_param_set_t *in_params, const keymaster_blob_t *input, size_t *input_consumed, keymaster_key_param_set_t *out_params, keymaster_blob_t *output)
 
keymaster_error_t (*  finish )(const struct keymaster1_device *dev, keymaster_operation_handle_t operation_handle, const keymaster_key_param_set_t *in_params, const keymaster_blob_t *signature, keymaster_key_param_set_t *out_params, keymaster_blob_t *output)
 
keymaster_error_t (*  abort )(const struct keymaster1_device *dev, keymaster_operation_handle_t operation_handle)
 

Detailed Description

Keymaster1 device definition

Definition at line 28 of file keymaster1.h .

Field Documentation

keymaster_error_t (* abort)(const struct keymaster1_device *dev, keymaster_operation_handle_t operation_handle)

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

Definition at line 531 of file keymaster1.h .

keymaster_error_t (* add_rng_entropy)(const struct keymaster1_device *dev, const uint8_t *data, size_t data_length)

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 will be good.

Parameters
[in] dev The keymaster device structure.
[in] data Random data to be mixed in.
[in] data_length Length of data .

Definition at line 242 of file keymaster1.h .

keymaster_error_t (* begin)(const struct keymaster1_device *dev, keymaster_purpose_t purpose, const keymaster_key_blob_t *key, const keymaster_key_param_set_t *in_params, keymaster_key_param_set_t *out_params, keymaster_operation_handle_t *operation_handle)

Begins a cryptographic operation using the specified key. If all is well, begin() will return KM_ERROR_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 KM_ERROR_TOO_MANY_OPERATIONS when it runs out of space for operations. Any result other than KM_ERROR_OK from begin() , update() or finish() implicitly aborts the operation, in which case abort() need not be called (and will return KM_ERROR_INVALID_OPERATION_HANDLE if called).

Parameters
[in] dev The keymaster device structure.
[in] purpose The purpose of the operation, one of KM_PURPOSE_ENCRYPT, KM_PURPOSE_DECRYPT, KM_PURPOSE_SIGN or KM_PURPOSE_VERIFY. Note that for AEAD modes, encryption and decryption imply signing and verification, respectively, but should be specified as KM_PURPOSE_ENCRYPT and KM_PURPOSE_DECRYPT.
[in] key The key to be used for the operation. key must have a purpose compatible with purpose and all of its usage requirements must be satisfied, or begin() will return an appropriate error code.
[in] in_params Additional parameters for the operation. This is typically used to provide authentication data, with KM_TAG_AUTH_TOKEN. If KM_TAG_APPLICATION_ID or KM_TAG_APPLICATION_DATA were provided during generation, they must be provided here, or the operation will fail with KM_ERROR_INVALID_KEY_BLOB. For operations that require a nonce or IV, on keys that were generated with KM_TAG_CALLER_NONCE, in_params may contain a tag KM_TAG_NONCE. For AEAD operations KM_TAG_CHUNK_SIZE is specified here.
[out] out_params 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. The caller takes ownership of the output parameters array and must free it with keymaster_free_param_set() . out_params may be set to NULL if no output parameters are expected. If out_params is NULL, and output paramaters are generated, begin() will return KM_ERROR_OUTPUT_PARAMETER_NULL.
[out] operation_handle The newly-created operation handle which must be passed to update() , finish() or abort() . If operation_handle is NULL, begin() will return KM_ERROR_OUTPUT_PARAMETER_NULL.

Definition at line 451 of file keymaster1.h .

uint32_t client_version

THIS IS DEPRECATED. Use the new "module_api_version" and "hal_api_version" fields in the keymaster_module initialization instead.

Definition at line 41 of file keymaster1.h .

struct hw_device_t common

Common methods of the keymaster device. This must be the first member of keymaster_device as users of this structure will cast a hw_device_t to keymaster_device pointer in contexts where it's known the hw_device_t references a keymaster_device.

Definition at line 35 of file keymaster1.h .

void* context

Definition at line 48 of file keymaster1.h .

int(* delete_all)(const struct keymaster1_device *dev)
Deprecated:
Deletes all keys in the hardware keystore. Used when keystore is reset completely.

This function is optional and should be set to NULL if it is not implemented.

Returns 0 on success or an error code less than 0.

Definition at line 100 of file keymaster1.h .

keymaster_error_t (* delete_all_keys)(const struct keymaster1_device *dev)

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 function is optional and should be set to NULL if it is not implemented.

Parameters
[in] dev The keymaster device structure.

Definition at line 407 of file keymaster1.h .

keymaster_error_t (* delete_key)(const struct keymaster1_device *dev, const keymaster_key_blob_t *key)

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 function is optional and should be set to NULL if it is not implemented.

Parameters
[in] dev The keymaster device structure.
[in] key The key to be deleted.

Definition at line 395 of file keymaster1.h .

int(* delete_keypair)(const struct keymaster1_device *dev, const uint8_t *key_blob, const size_t key_blob_length)
Deprecated:
Deletes the key pair associated with the key blob.

This function is optional and should be set to NULL if it is not implemented.

Returns 0 on success or an error code less than 0.

Definition at line 88 of file keymaster1.h .

keymaster_error_t (* export_key)(const struct keymaster1_device *dev, keymaster_key_format_t export_format, const keymaster_key_blob_t *key_to_export, const keymaster_blob_t *client_id, const keymaster_blob_t *app_data, keymaster_blob_t *export_data)

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

Parameters
[in] dev The keymaster device structure.
[in] export_format The format to be used for exporting the key.
[in] key_to_export The key to export.
[out] export_data The exported key material. The caller assumes ownership.
[out] export_data_length The length of export_data .

Definition at line 377 of file keymaster1.h .

keymaster_error_t (* finish)(const struct keymaster1_device *dev, keymaster_operation_handle_t operation_handle, const keymaster_key_param_set_t *in_params, const keymaster_blob_t *signature, keymaster_key_param_set_t *out_params, keymaster_blob_t *output)

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

Parameters
[in] dev The keymaster device structure.
[in] operation_handle The operation handle returned by begin() . This handle will be invalidated.
[in] params Additional parameters for the operation. For AEAD modes, this is used to specify KM_TAG_ADDITIONAL_DATA, but only if no input data was provided to update() .
[in] signature The signature to be verified if the purpose specified in the begin() call was KM_PURPOSE_VERIFY.
[out] output The output data, if any. The caller assumes ownership of the allocated buffer.

If the operation being finished is a signature verification or an AEAD-mode decryption and verification fails then finish() will return KM_ERROR_VERIFICATION_FAILED.

Definition at line 521 of file keymaster1.h .

uint32_t flags

See flags defined for keymaster0_devices::flags in keymaster_common.h

Definition at line 46 of file keymaster1.h .

keymaster_error_t (* generate_key)(const struct keymaster1_device *dev, const keymaster_key_param_set_t *params, keymaster_key_blob_t *key_blob, keymaster_key_characteristics_t **characteristics)

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

Key generation parameters are defined as keymaster tag/value pairs, provided in params . See keymaster_tag_t for the full list. Some values that are always required for generation of useful keys are:

  • KM_TAG_ALGORITHM;
  • KM_TAG_PURPOSE; and
  • (KM_TAG_USER_SECURE_ID and KM_TAG_USER_AUTH_TYPE) or KM_TAG_NO_AUTH_REQUIRED.

KM_TAG_AUTH_TIMEOUT should generally be specified unless KM_TAG_NO_AUTH_REQUIRED is present, or the user will have to authenticate for every use.

KM_TAG_BLOCK_MODE, KM_TAG_PADDING, KM_TAG_MAC_LENGTH and KM_TAG_DIGEST must be specified for algorithms that require them.

The following tags may not be specified; their values will be provided by the implementation.

  • KM_TAG_ORIGIN,
  • KM_TAG_ROLLBACK_RESISTANT,
  • KM_TAG_CREATION_DATETIME
Parameters
[in] dev The keymaster device structure.
[in] params Array of key generation parameters.
[in] params_count Length of params .
[out] key_blob returns the generated key. key_blob must not be NULL. The caller assumes ownership key_blob->key_material and must free() it.
[out] characteristics returns the characteristics of the key that was, generated, if non-NULL. If non-NULL, the caller assumes ownership and must deallocate with keymaster_free_characteristics() . Note that KM_TAG_ROOT_OF_TRUST, KM_TAG_APPLICATION_ID and KM_TAG_APPLICATION_DATA are never returned.

Definition at line 282 of file keymaster1.h .

int(* generate_keypair)(const struct keymaster1_device *dev, const keymaster_keypair_t key_type, const void *key_params, uint8_t **key_blob, size_t *key_blob_length)
Deprecated:
Generates a public and private key. The key-blob returned is opaque and must subsequently provided for signing and verification.

Returns: 0 on success or an error code less than 0.

Definition at line 56 of file keymaster1.h .

keymaster_error_t (* get_key_characteristics)(const struct keymaster1_device *dev, const keymaster_key_blob_t *key_blob, const keymaster_blob_t *client_id, const keymaster_blob_t *app_data, keymaster_key_characteristics_t **characteristics)

Returns the characteristics of the specified key, or KM_ERROR_INVALID_KEY_BLOB if the key_blob is invalid (implementations must fully validate the integrity of the key). client_id and app_data must be the ID and data provided when the key was generated or imported, or empty if KM_TAG_APPLICATION_ID and/or KM_TAG_APPLICATION_DATA were not provided during generation. Those values are not included in the returned characteristics. The caller assumes ownership of the allocated characteristics object, which must be deallocated with keymaster_free_characteristics() .

Note that KM_TAG_ROOT_OF_TRUST, KM_TAG_APPLICATION_ID and KM_TAG_APPLICATION_DATA are never returned.

Parameters
[in] dev The keymaster device structure.
[in] key_blob The key to retreive characteristics from.
[in] client_id The client ID data, or NULL if none associated.
[in] app_id The app data, or NULL if none associated.
[out] characteristics The key characteristics.

Definition at line 309 of file keymaster1.h .

int(* get_keypair_public)(const struct keymaster1_device *dev, const uint8_t *key_blob, const size_t key_blob_length, uint8_t **x509_data, size_t *x509_data_length)
Deprecated:
Gets the public key part of a key pair. The public key must be in X.509 format (Java standard) encoded byte array.

Returns: 0 on success or an error code less than 0. On error, x509_data should not be allocated.

Definition at line 76 of file keymaster1.h .

keymaster_error_t (* get_supported_algorithms)(const struct keymaster1_device *dev, keymaster_algorithm_t **algorithms, size_t *algorithms_length)

Gets algorithms supported.

Parameters
[in] dev The keymaster device structure.
[out] algorithms Array of algorithms supported. The caller takes ownership of the array and must free() it.
[out] algorithms_length Length of algorithms .

Definition at line 133 of file keymaster1.h .

keymaster_error_t (* get_supported_block_modes)(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_purpose_t purpose, keymaster_block_mode_t **modes, size_t *modes_length)

Gets the block modes supported for the specified algorithm.

Parameters
[in] dev The keymaster device structure.
[in] algorithm The algorithm for which supported modes will be returned.
[out] modes Array of modes supported. The caller takes ownership of the array and must free() it.
[out] modes_length Length of modes .

Definition at line 149 of file keymaster1.h .

keymaster_error_t (* get_supported_digests)(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_purpose_t purpose, keymaster_digest_t **digests, size_t *digests_length)

Gets the digests supported for the specified algorithm. Caller assumes ownership of the allocated array.

Parameters
[in] dev The keymaster device structure.
[in] algorithm The algorithm for which supported digests will be returned.
[out] digests Array of digests supported. The caller takes ownership of the array and must free() it.
[out] digests_length Length of digests .

Definition at line 187 of file keymaster1.h .

keymaster_error_t (* get_supported_export_formats)(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_key_format_t **formats, size_t *formats_length)

Gets the key export formats supported for keys of the specified algorithm. Caller assumes ownership of the allocated array.

Parameters
[in] dev The keymaster device structure.
[in] algorithm The algorithm for which supported formats will be returned.
[out] formats Array of formats supported. The caller takes ownership of the array and must free() it.
[out] formats_length Length of formats .

Definition at line 224 of file keymaster1.h .

keymaster_error_t (* get_supported_import_formats)(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_key_format_t **formats, size_t *formats_length)

Gets the key import formats supported for keys of the specified algorithm. Caller assumes ownership of the allocated array.

Parameters
[in] dev The keymaster device structure.
[in] algorithm The algorithm for which supported formats will be returned.
[out] formats Array of formats supported. The caller takes ownership of the array and must free() it.
[out] formats_length Length of formats .

Definition at line 206 of file keymaster1.h .

keymaster_error_t (* get_supported_padding_modes)(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_purpose_t purpose, keymaster_padding_t **modes, size_t *modes_length)

Gets the padding modes supported for the specified algorithm. Caller assumes ownership of the allocated array.

Parameters
[in] dev The keymaster device structure.
[in] algorithm The algorithm for which supported padding modes will be returned.
[out] modes Array of padding modes supported. The caller takes ownership of the array and must free() it.
[out] modes_length Length of modes .

Definition at line 168 of file keymaster1.h .

keymaster_error_t (* import_key)(const struct keymaster1_device *dev, const keymaster_key_param_set_t *params, keymaster_key_format_t key_format, const keymaster_blob_t *key_data, keymaster_key_blob_t *key_blob, keymaster_key_characteristics_t **characteristics)

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

Most key import parameters are defined as keymaster tag/value pairs, provided in "params". See keymaster_tag_t for the full list. Values that are always required for import of useful keys are:

  • KM_TAG_ALGORITHM;
  • KM_TAG_PURPOSE; and
  • (KM_TAG_USER_SECURE_ID and KM_TAG_USER_AUTH_TYPE) or KM_TAG_NO_AUTH_REQUIRED.

KM_TAG_AUTH_TIMEOUT should generally be specified. If unspecified, the user will have to authenticate for every use.

The following tags will take default values if unspecified:

  • KM_TAG_KEY_SIZE will default to the size of the key provided.
  • KM_TAG_RSA_PUBLIC_EXPONENT will default to the value in the key provided (for RSA keys)

The following tags may not be specified; their values will be provided by the implementation.

  • KM_TAG_ORIGIN,
  • KM_TAG_ROLLBACK_RESISTANT,
  • KM_TAG_CREATION_DATETIME
Parameters
[in] dev The keymaster device structure.
[in] params Parameters defining the imported key.
[in] params_count The number of entries in params .
[in] key_format specifies the format of the key data in key_data.
[out] key_blob Used to return the opaque key blob. Must be non-NULL. The caller assumes ownership of the contained key_material.
[out] characteristics Used to return the characteristics of the imported key. May be NULL, in which case no characteristics will be returned. If non-NULL, the caller assumes ownership and must deallocate with keymaster_free_characteristics() . Note that KM_TAG_ROOT_OF_TRUST, KM_TAG_APPLICATION_ID and KM_TAG_APPLICATION_DATA are never returned.

Definition at line 357 of file keymaster1.h .

int(* import_keypair)(const struct keymaster1_device *dev, const uint8_t *key, const size_t key_length, uint8_t **key_blob, size_t *key_blob_length)
Deprecated:
Imports a public and private key pair. The imported keys will be in PKCS#8 format with DER encoding (Java standard). The key-blob returned is opaque and will be subsequently provided for signing and verification.

Returns: 0 on success or an error code less than 0.

Definition at line 66 of file keymaster1.h .

int(* sign_data)(const struct keymaster1_device *dev, const void *signing_params, const uint8_t *key_blob, const size_t key_blob_length, const uint8_t *data, const size_t data_length, uint8_t **signed_data, size_t *signed_data_length)
Deprecated:
Signs data using a key-blob generated before. This can use either an asymmetric key or a secret key.

Returns: 0 on success or an error code less than 0.

Definition at line 108 of file keymaster1.h .

keymaster_error_t (* update)(const struct keymaster1_device *dev, keymaster_operation_handle_t operation_handle, const keymaster_key_param_set_t *in_params, const keymaster_blob_t *input, size_t *input_consumed, keymaster_key_param_set_t *out_params, keymaster_blob_t *output)

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

If operation_handle is invalid, update() will return KM_ERROR_INVALID_OPERATION_HANDLE.

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

Parameters
[in] dev The keymaster device structure.
[in] operation_handle The operation handle returned by begin() .
[in] in_params Additional parameters for the operation. For AEAD modes, this is used to specify KM_TAG_ADDITIONAL_DATA. Note that additional data may be provided in multiple calls to update() , but only until input data has been provided.
[in] 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 input_consumed .
[out] input_consumed Amount of data that was consumed by update() . If this is less than the amount provided, the caller should provide the remainder in a subsequent call to update() .
[out] out_params 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() . out_params may be set to NULL if no output parameters are expected. If out_params is NULL, and output paramaters are generated, begin() will return KM_ERROR_OUTPUT_PARAMETER_NULL.
[out] output The output data, if any. The caller assumes ownership of the allocated buffer. output must not be NULL.

Note that update() may not provide any output, in which case output->data_length will be zero, and output->data may be either NULL or zero-length (so the caller should always free() it).

Definition at line 495 of file keymaster1.h .

int(* verify_data)(const struct keymaster1_device *dev, const void *signing_params, const uint8_t *key_blob, const size_t key_blob_length, const uint8_t *signed_data, const size_t signed_data_length, const uint8_t *signature, const size_t signature_length)
Deprecated:
Verifies data signed with a key-blob. This can use either an asymmetric key or a secret key.

Returns: 0 on successful verification or an error code less than 0.

Definition at line 118 of file keymaster1.h .

The documentation for this struct was generated from the following file: