Referencia de estructura keymaster2_device

Referencia de estructura keymaster2_device

#include < keymaster2.h >

Campos de información

estructura hw_device_t común
vacío * contexto
uint32_t banderas
keymaster_error_t (* configurar ) (const struct keymaster2_device *dev, const keymaster_key_param_set_t *params)
keymaster_error_t (* add_rng_entropy )(const struct keymaster2_device *dev, const uint8_t *data, size_t data_length)
keymaster_error_t (* generate_key (const struct keymaster2_device *dev, const keymaster_key_param_set_t *params, keymaster_key_blob_t *key_blob, keymaster_key_characteristics_t *características)
keymaster_error_t (* get_key_characteristics )(const struct keymaster2_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 *características)
keymaster_error_t (* import_key )(const struct keymaster2_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 *características)
keymaster_error_t (* export_key )(const struct keymaster2_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 (* attest_key (const struct keymaster2_device *dev, const keymaster_key_blob_t *key_to_attest, const keymaster_key_param_set_t *attest_params, keymaster_cert_chain_t *cert_chain)
keymaster_error_t (* Upgrade_key (const struct keymaster2_device *dev, const keymaster_key_blob_t *key_to_upgrade, const keymaster_key_param_set_t *upgrade_params, keymaster_key_blob_t *upgraded_key)
keymaster_error_t (* eliminar_clave (const estructura keymaster2_device *dev, const keymaster_key_blob_t *clave)
keymaster_error_t (* eliminar_todas_claves ) (const estructura keymaster2_device *dev)
keymaster_error_t (* comenzar ) (const struct keymaster2_device *dev, keymaster_Purpose_t propósito, 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 (* actualizar ) (const struct keymaster2_device *dev, keymaster_operative_handle_t operación_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 (* finalizar ) (const struct keymaster2_device *dev, keymaster_operative_handle_t operación_handle, const keymaster_key_param_set_t *in_params, const keymaster_blob_t *entrada, const keymaster_blob_t *firma, keymaster_key_param_set_t *out_params, keymaster_blob_t *salida)
keymaster_error_t (* abortar ) (const struct keymaster2_device *dev, keymaster_operation_handle_t operación_handle)

Descripción detallada

Definición del dispositivo Keymaster2

Definición en la línea 28 del archivo keymaster2.h .

Documentación de campo

keymaster_error_t (* abortar)(const struct keymaster2_device *dev, keymaster_operation_handle_t operación_handle)

Anula una operación criptográfica iniciada con begin() , liberando todos los recursos internos e invalidando operation_handle .

Definición en la línea 415 del archivo keymaster2.h .

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

Agrega entropía al RNG utilizado por keymaster. Se garantiza que la entropía agregada a través de este método no será la única fuente de entropía utilizada, y se requiere que la función de mezcla sea segura, en el sentido de que si el RNG se siembra (de cualquier fuente) con cualquier dato que el atacante no pueda predecir (o control), entonces la salida RNG no se puede distinguir de la aleatoria. Por tanto, si la entropía de cualquier fuente es buena, el resultado será bueno.

Parámetros
[en] desarrollador La estructura del dispositivo maestro de llaves.
[en] datos Datos aleatorios para mezclar.
[en] longitud de datos Longitud de data .

Definición en la línea 74 del archivo keymaster2.h .

keymaster_error_t (* attest_key)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key_to_attest, const keymaster_key_param_set_t *attest_params, keymaster_cert_chain_t *cert_chain)

Genera una cadena de certificados X.509 firmada que certifica la presencia de key_to_attest en keymaster (TODO(swillden): Describa el contenido del certificado con más detalle). El certificado contendrá una extensión con OID 1.3.6.1.4.1.11129.2.1.17 y el valor definido en <TODO:swillden – insert link here> que contiene la descripción de la clave.

Parámetros
[en] desarrollador La estructura del dispositivo maestro de llaves.
[en] clave_para_attestar La clave maestra de claves para la cual se generará el certificado de atestación.
[en] attest_params Parámetros que definen cómo hacer la atestación. Actualmente, el único parámetro es KM_TAG_ALGORITHM, que debe ser KM_ALGORITHM_EC o KM_ALGORITHM_RSA. Esto selecciona cuál de las claves de atestación proporcionadas se utilizará para firmar el certificado.
[afuera] cadena_certificada Una serie de certificados X.509 codificados en DER. El primero será el certificado de key_to_attest . Las entradas restantes se encadenarán hasta la raíz. La persona que llama toma posesión y debe desasignar con keymaster_free_cert_chain.

Definición en la línea 239 del archivo keymaster2.h .

keymaster_error_t (* comenzar)(const struct keymaster2_device *dev, keymaster_Purpose_t propósito, const keymaster_key_blob_t *key, const keymaster_key_param_set_t *in_params, keymaster_key_param_set_t *out_params, keymaster_operación_handle_t *operación_handle)

Comienza una operación criptográfica utilizando la clave especificada. Si todo está bien, begin() devolverá KM_ERROR_OK y creará un identificador de operación que debe pasarse a llamadas posteriores a update() , Finish() o abort() .

Es fundamental que cada llamada a comenzar() se combine con una llamada posterior a terminar() o abortar() , para permitir que la implementación del maestro de claves limpie cualquier estado de operación interna. Si no se hace esto, se puede perder espacio de estado interno u otros recursos internos y, eventualmente, puede provocar que comenzar() devuelva KM_ERROR_TOO_MANY_OPERACIONES cuando se quede sin espacio para las operaciones. Cualquier resultado que no sea KM_ERROR_OK de comenzar() , actualizar() o finalizar() aborta implícitamente la operación, en cuyo caso no es necesario llamar a abort() (y devolverá KM_ERROR_INVALID_OPERATION_HANDLE si se llama).

Parámetros
[en] desarrollador La estructura del dispositivo maestro de llaves.
[en] objetivo El propósito de la operación, uno de KM_PURPOSE_ENCRYPT, KM_PURPOSE_DECRYPT, KM_PURPOSE_SIGN o KM_PURPOSE_VERIFY. Tenga en cuenta que para los modos AEAD, el cifrado y el descifrado implican firma y verificación, respectivamente, pero deben especificarse como KM_PURPOSE_ENCRYPT y KM_PURPOSE_DECRYPT.
[en] llave La clave que se utilizará para la operación. key debe tener un propósito compatible con purpose y se deben cumplir todos sus requisitos de uso, o comenzar() devolverá un código de error apropiado.
[en] en_params Parámetros adicionales para la operación. Normalmente se utiliza para proporcionar datos de autenticación, con KM_TAG_AUTH_TOKEN. Si se proporcionaron KM_TAG_APPLICATION_ID o KM_TAG_APPLICATION_DATA durante la generación, se deben proporcionar aquí o la operación fallará con KM_ERROR_INVALID_KEY_BLOB. Para operaciones que requieren un nonce o IV, en claves que se generaron con KM_TAG_CALLER_NONCE, in_params puede contener una etiqueta KM_TAG_NONCE.
[afuera] out_params Parámetros de salida. Se utiliza para devolver datos adicionales de la inicialización de la operación, en particular para devolver el IV o nonce de operaciones que generan un IV o nonce. La persona que llama toma posesión de la matriz de parámetros de salida y debe liberarla con keymaster_free_param_set() . out_params se puede establecer en NULL si no se esperan parámetros de salida. Si out_params es NULL y se generan parámetros de salida, comenzar() devolverá KM_ERROR_OUTPUT_PARAMETER_NULL.
[afuera] mango_operación El identificador de operación recién creado que se debe pasar a update() , Finish() o abort() . Si Operation_handle es NULL, comenzar() devolverá KM_ERROR_OUTPUT_PARAMETER_NULL.

Definición en la línea 332 del archivo keymaster2.h .

estructura hw_device_t común

Métodos comunes del dispositivo keymaster. Este debe ser el primer miembro de keymaster_device ya que los usuarios de esta estructura enviarán un hw_device_t a un puntero keymaster_device en contextos donde se sabe que hw_device_t hace referencia a un keymaster_device.

Definición en la línea 35 del archivo keymaster2.h .

keymaster_error_t (* configurar)(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params)

Configura el maestro de llaves. Este método debe llamarse una vez después de abrir el dispositivo y antes de utilizarlo. Se utiliza para proporcionar KM_TAG_OS_VERSION y KM_TAG_OS_PATCHLEVEL al keymaster. Hasta que se llame a este método, todos los demás métodos devolverán KM_ERROR_KEYMASTER_NOT_CONFIGURED. Keymaster solo acepta los valores proporcionados por este método una vez por arranque. Las llamadas posteriores devolverán KM_ERROR_OK, pero no harán nada.

Si la implementación de Keymaster está en hardware seguro y la versión del sistema operativo y los valores de nivel de parche proporcionados no coinciden con los valores proporcionados al hardware seguro por el cargador de arranque (o si el cargador de arranque no proporcionó valores), entonces este método devolverá KM_ERROR_INVALID_ARGUMENT y todos otros métodos seguirán devolviendo KM_ERROR_KEYMASTER_NOT_CONFIGURED.

Definición en la línea 58 del archivo keymaster2.h .

contexto vacío*

Definición en la línea 37 del archivo keymaster2.h .

keymaster_error_t (* eliminar_todas_claves)(const estructura keymaster2_device *dev)

Elimina todas las claves del almacén de claves de hardware. Se utiliza cuando el almacén de claves se restablece por completo. Después de llamar a esta función, será imposible utilizar cualquier blob de claves generado o importado previamente para cualquier operación.

Esta función es opcional y debe establecerse en NULL si no está implementada.

Parámetros
[en] desarrollador La estructura del dispositivo maestro de llaves.

Definición en la línea 288 del archivo keymaster2.h .

keymaster_error_t (* eliminar_clave)(const struct keymaster2_device *dev, const keymaster_key_blob_t *clave)

Elimina la clave, o el par de claves, asociado al blob de claves. Después de llamar a esta función será imposible utilizar la clave para otras operaciones. Se puede aplicar a claves de raíces de confianza extranjeras (claves que no se pueden utilizar bajo la raíz de confianza actual).

Esta función es opcional y debe establecerse en NULL si no está implementada.

Parámetros
[en] desarrollador La estructura del dispositivo maestro de llaves.
[en] llave La clave a eliminar.

Definición en la línea 276 del archivo keymaster2.h .

keymaster_error_t (* export_key)(const struct keymaster2_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)

Exporta una clave pública o simétrica y devuelve una matriz de bytes en el formato especificado.

Tenga en cuenta que la exportación de claves simétricas solo se permite si la clave se creó con KM_TAG_EXPORTABLE y solo si se cumplen todos los requisitos para el uso de claves (por ejemplo, autenticación).

Parámetros
[en] desarrollador La estructura del dispositivo maestro de llaves.
[en] formato_exportación El formato que se utilizará para exportar la clave.
[en] clave_para_exportar La clave para exportar.
[en] Identificación del cliente Blob de ID de cliente, que debe coincidir con el blob proporcionado en KM_TAG_APPLICATION_ID durante la generación de claves (si corresponde).
[en] datos de aplicación Blob de datos de aplicación, que debe coincidir con el blob proporcionado en KM_TAG_APPLICATION_DATA durante la generación de claves (si corresponde).
[afuera] exportar datos El material clave exportado. La persona que llama asume la propiedad.

Definición en la línea 213 del archivo keymaster2.h .

keymaster_error_t (* terminar)(const struct keymaster2_device *dev, keymaster_operative_handle_t operación_handle, const keymaster_key_param_set_t *in_params, const keymaster_blob_t *entrada, const keymaster_blob_t *firma, keymaster_key_param_set_t *out_params, keymaster_blob_t *salida)

Finaliza una operación criptográfica iniciada con begin() e invalida operation_handle .

Parámetros
[en] desarrollador La estructura del dispositivo maestro de llaves.
[en] mango_operación El identificador de operación devuelto por begin() . Este identificador será invalidado.
[en] en_params Parámetros adicionales para la operación. Para los modos AEAD, esto se usa para especificar KM_TAG_ADDITIONAL_DATA, pero solo si no se proporcionaron datos de entrada a update() .
[en] aporte Datos a procesar, según los parámetros establecidos en la llamada a begin() . Finish() debe consumir todos los datos proporcionados o devolver KM_ERROR_INVALID_INPUT_LENGTH.
[en] firma La firma que se verificará si el propósito especificado en la llamada a comenzar() era KM_PURPOSE_VERIFY.
[afuera] producción Los datos de salida, si los hubiera. La persona que llama asume la propiedad del búfer asignado.

Si la operación que se está finalizando es una verificación de firma o un descifrado en modo AEAD y la verificación falla, finalizar() devolverá KM_ERROR_VERIFICATION_FAILED.

Definición en la línea 405 del archivo keymaster2.h .

banderas uint32_t

Consulte los indicadores definidos para keymaster0_devices::flags en keymaster_common.h . Se utiliza sólo por compatibilidad con versiones anteriores; Los dispositivos de hardware keymaster2 deben configurarlo en cero.

Definición en la línea 43 del archivo keymaster2.h .

keymaster_error_t (* generate_key)(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params, keymaster_key_blob_t *key_blob, keymaster_key_characteristics_t *características)

Genera una clave o un par de claves y devuelve un blob de claves o una descripción de la clave.

Los parámetros de generación de claves se definen como pares de etiqueta/valor keymaster, proporcionados en params . Consulte keymaster_tag_t para obtener la lista completa. Algunos valores que siempre son necesarios para la generación de claves útiles son:

  • KM_TAG_ALGORITHM;
  • KM_TAG_PURPOSE; y
  • (KM_TAG_USER_SECURE_ID y KM_TAG_USER_AUTH_TYPE) o KM_TAG_NO_AUTH_REQUIRED.

Por lo general, se debe especificar KM_TAG_AUTH_TIMEOUT a menos que KM_TAG_NO_AUTH_REQUIRED esté presente, o el usuario tendrá que autenticarse para cada uso.

Se deben especificar KM_TAG_BLOCK_MODE, KM_TAG_PADDING, KM_TAG_MAC_LENGTH y KM_TAG_DIGEST para los algoritmos que los requieran.

Es posible que no se especifiquen las siguientes etiquetas; sus valores serán proporcionados por la implementación.

  • KM_TAG_ORIGIN,
  • KM_TAG_ROLLBACK_RESISTANT,
  • KM_TAG_CREATION_DATETIME
Parámetros
[en] desarrollador La estructura del dispositivo maestro de llaves.
[en] parámetros Matriz de parámetros de generación de claves
[afuera] bloque_clave devuelve la clave generada. key_blob no debe ser NULL. La persona que llama asume la propiedad key_blob->key_material y debe liberarlo().
[afuera] características devuelve las características de la clave que se generó, si no es NULL. Si no es NULL, la persona que llama asume la propiedad y debe desasignar con keymaster_free_characteristics() . Tenga en cuenta que KM_TAG_ROOT_OF_TRUST, KM_TAG_APPLICATION_ID y KM_TAG_APPLICATION_DATA nunca se devuelven.

Definición en la línea 112 del archivo keymaster2.h .

keymaster_error_t (* get_key_characteristics)(const struct keymaster2_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 *características)

Devuelve las características de la clave especificada, o KM_ERROR_INVALID_KEY_BLOB si key_blob no es válido (las implementaciones deben validar completamente la integridad de la clave). client_id y app_data deben ser el ID y los datos proporcionados cuando se generó o importó la clave, o deben estar vacíos si KM_TAG_APPLICATION_ID y/o KM_TAG_APPLICATION_DATA no se proporcionaron durante la generación. Esos valores no están incluidos en las características devueltas. La persona que llama asume la propiedad del objeto de características asignado, que debe desasignarse con keymaster_free_characteristics() .

Tenga en cuenta que KM_TAG_APPLICATION_ID y KM_TAG_APPLICATION_DATA nunca se devuelven.

Parámetros
[en] desarrollador La estructura del dispositivo maestro de llaves.
[en] bloque_clave La clave para recuperar características.
[en] Identificación del cliente Los datos de ID del cliente, o NULL si no hay ninguno asociado.
[en] id_aplicación Los datos de la aplicación, o NULL si no hay ninguno asociado.
[afuera] características Las características clave. No debe ser nulo. La persona que llama asume la propiedad del contenido y debe cancelar la asignación con keymaster_free_characteristics() .

Definición en la línea 139 del archivo keymaster2.h .

keymaster_error_t (* import_key)(const struct keymaster2_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 *características)

Importa una clave o un par de claves y devuelve un blob de claves o una descripción de la clave.

La mayoría de los parámetros de importación clave se definen como pares de etiqueta/valor keymaster, proporcionados en "parámetros". Consulte keymaster_tag_t para obtener la lista completa. Los valores que siempre se requieren para importar claves útiles son:

  • KM_TAG_ALGORITHM;
  • KM_TAG_PURPOSE; y
  • (KM_TAG_USER_SECURE_ID y KM_TAG_USER_AUTH_TYPE) o KM_TAG_NO_AUTH_REQUIRED.

Generalmente se debe especificar KM_TAG_AUTH_TIMEOUT. Si no se especifica, el usuario deberá autenticarse para cada uso.

Las siguientes etiquetas tomarán valores predeterminados si no se especifican:

  • KM_TAG_KEY_SIZE tendrá de forma predeterminada el tamaño de la clave proporcionada.
  • KM_TAG_RSA_PUBLIC_EXPONENT utilizará de forma predeterminada el valor de la clave proporcionada (para claves RSA)

Es posible que no se especifiquen las siguientes etiquetas; sus valores serán proporcionados por la implementación.

  • KM_TAG_ORIGIN,
  • KM_TAG_ROLLBACK_RESISTANT,
  • KM_TAG_CREATION_DATETIME
Parámetros
[en] desarrollador La estructura del dispositivo maestro de llaves.
[en] parámetros Parámetros que definen la clave importada.
[en] params_count El número de entradas en params .
[en] formato_clave especifica el formato de los datos clave en key_data.
[afuera] bloque_clave Se utiliza para devolver el blob de clave opaco. Debe ser no NULL. La persona que llama asume la propiedad del key_material contenido.
[afuera] características Se utiliza para devolver las características de la clave importada. Puede ser NULL, en cuyo caso no se devolverá ninguna característica. Si no es NULL, la persona que llama asume la propiedad del contenido y debe desasignarlo con keymaster_free_characteristics() . Tenga en cuenta que KM_TAG_APPLICATION_ID y KM_TAG_APPLICATION_DATA nunca se devuelven.

Definición en la línea 186 del archivo keymaster2.h .

keymaster_error_t (* actualización)(const struct keymaster2_device *dev, keymaster_operative_handle_t operación_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)

Proporciona datos y posiblemente recibe resultados de una operación criptográfica en curso iniciada con begin() .

Si Operation_handle no es válido, update() devolverá KM_ERROR_INVALID_OPERATION_HANDLE.

Es posible que update() no consuma todos los datos proporcionados en el búfer de datos. update() devolverá la cantidad consumida en *data_consumed. La persona que llama debe proporcionar los datos no consumidos en una llamada posterior.

Parámetros
[en] desarrollador La estructura del dispositivo maestro de llaves.
[en] mango_operación El identificador de operación devuelto por begin() .
[en] en_params Parámetros adicionales para la operación. Para los modos AEAD, esto se utiliza para especificar KM_TAG_ADDITIONAL_DATA. Tenga en cuenta que se pueden proporcionar datos adicionales en varias llamadas a update() , pero solo hasta que se hayan proporcionado los datos de entrada.
[en] aporte Datos a procesar, según los parámetros establecidos en la llamada a begin() . Tenga en cuenta que update() puede consumir o no todos los datos proporcionados. Ver input_consumed .
[afuera] entrada_consumida Cantidad de datos consumidos por update() . Si esto es menor que la cantidad proporcionada, la persona que llama debe proporcionar el resto en una llamada posterior a update() .
[afuera] out_params Parámetros de salida. Se utiliza para devolver datos adicionales de la operación. La persona que llama toma posesión de la matriz de parámetros de salida y debe liberarla con keymaster_free_param_set() . out_params se puede establecer en NULL si no se esperan parámetros de salida. Si out_params es NULL y se generan parámetros de salida, comenzar() devolverá KM_ERROR_OUTPUT_PARAMETER_NULL.
[afuera] producción Los datos de salida, si los hubiera. La persona que llama asume la propiedad del búfer asignado. la salida no debe ser NULL.

Tenga en cuenta que es posible que update() no proporcione ningún resultado, en cuyo caso salida->longitud_datos será cero, y salida->datos puede ser NULL o de longitud cero (por lo que la persona que llama siempre debe liberarlo()).

Definición en la línea 376 del archivo keymaster2.h .

keymaster_error_t (* clave_actualización)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key_to_upgrade, const keymaster_key_param_set_t *upgrade_params, keymaster_key_blob_t *upgraded_key)

Actualiza una clave antigua. Las claves pueden volverse "antiguas" de dos maneras: Keymaster se puede actualizar a una nueva versión o el sistema se puede actualizar para invalidar la versión del sistema operativo y/o el nivel de parche. En cualquier caso, los intentos de utilizar una clave antigua darán como resultado que Keymaster devuelva KM_ERROR_KEY_REQUIRES_UPGRADE. Luego se debe llamar a este método para actualizar la clave.

Parámetros
[en] desarrollador La estructura del dispositivo maestro de llaves.
[en] clave_para_actualizar La clave maestra para actualizar.
[en] parámetros_actualización Parámetros necesarios para completar la actualización. En particular, se requerirán KM_TAG_APPLICATION_ID y KM_TAG_APPLICATION_DATA si se definieron para la clave.
[afuera] clave_actualizada El blob de claves actualizado.

Definición en la línea 260 del archivo keymaster2.h .


La documentación para esta estructura se generó a partir del siguiente archivo: