Referencia de la estructura keymaster2_device

Aborta una operación criptográfica iniciada con begin() , libera todos los recursos internos y invalida operation_handle .

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

Agrega entropía al RNG que usa Keymaster. Se garantiza que la entropía agregada a través de este método no sea la única fuente de entropía que se usa, y la función de combinación debe ser segura, en el sentido de que, si se inicializa el generador de números aleatorios (desde cualquier fuente) con datos que el atacante no puede predecir (o controlar), el resultado del generador de números aleatorios no se puede distinguir de un valor aleatorio. Por lo tanto, si la entropía de cualquier fuente es buena, el resultado será bueno.

Parámetros

[in]	dev	La estructura del dispositivo de Keymaster
[in]	datos	Datos aleatorios que se mezclarán.
[in]	data_length	Longitud de data .

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

Genera una cadena de certificados X.509 firmada que certifica la presencia de key_to_attest en Keymaster (TODO(swillden): Describe el contenido del certificado con más detalle). El certificado contendrá una extensión con el 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

[in]	dev	La estructura del dispositivo de Keymaster
[in]	key_to_attest	La clave de Keymaster para la que se generará el certificado de certificación.
[in]	attest_params	Son parámetros que definen cómo se realiza la certificación. Actualmente, el único parámetro es KM_TAG_ALGORITHM, que debe ser KM_ALGORITHM_EC o KM_ALGORITHM_RSA. De esta forma, se selecciona cuál de las claves de certificación aprovisionadas se usará para firmar el certificado.
[out]	cert_chain	Es un array de certificados X.509 codificados en DER. El primero será el certificado para key_to_attest . Las entradas restantes se vincularán a la raíz. El llamador se convierte en el propietario y debe anular la asignación con keymaster_free_cert_chain.

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

Inicia una operación criptográfica con la clave especificada. Si todo está bien, begin() mostrará KM_ERROR_OK y creará un identificador de operación que se debe pasar a las llamadas posteriores a update() , finish() o abort() .

Es fundamental que cada llamada a begin() esté vinculada a una llamada posterior a finish() o abort() para permitir que la implementación de Keymaster borre cualquier estado de operación interna. Si no lo haces, es posible que se filtre el espacio de estado interno o algún otro recurso interno, y, con el tiempo, es posible que begin() muestre KM_ERROR_TOO_MANY_OPERATIONS cuando se quede sin espacio para las operaciones. Cualquier resultado que no sea KM_ERROR_OK de begin() , update() o finish() aborta implícitamente la operación, en cuyo caso no es necesario llamar a abort() (y se mostrará KM_ERROR_INVALID_OPERATION_HANDLE si se llama).

Parámetros

[in]	dev	La estructura del dispositivo de Keymaster
[in]	propósito	El propósito de la operación, uno de KM_PURPOSE_ENCRYPT, KM_PURPOSE_DECRYPT, KM_PURPOSE_SIGN o KM_PURPOSE_VERIFY. Ten en cuenta que, para los modos AEAD, la encriptación y la desencriptación implican la firma y la verificación, respectivamente, pero deben especificarse como KM_PURPOSE_ENCRYPT y KM_PURPOSE_DECRYPT.
[in]	key	Es la clave que se usará para la operación. key debe tener un propósito compatible con purpose y se deben satisfacer todos sus requisitos de uso, o bien begin() mostrará un código de error adecuado.
[in]	in_params	Parámetros adicionales para la operación. Por lo general, se usa 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. En el caso de las operaciones que requieren un nonce o IV, en las claves que se generaron con KM_TAG_CALLER_NONCE, in_params puede contener una etiqueta KM_TAG_NONCE.
[out]	out_params	Parámetros de salida Se usa para mostrar datos adicionales de la inicialización de la operación, en particular, para mostrar el IV o el nonce de las operaciones que generan un IV o un nonce. El llamador se convierte en el propietario del array de parámetros de salida y debe liberarlo 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, begin() mostrará KM_ERROR_OUTPUT_PARAMETER_NULL.
[out]	operation_handle	Es el identificador de operación recién creado que se debe pasar a update() , finish() o abort() . Si operation_handle es nulo, begin() mostrará KM_ERROR_OUTPUT_PARAMETER_NULL.

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

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

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

Configura Keymaster. Se debe llamar a este método una vez después de que se abre el dispositivo y antes de que se use. Se usa para proporcionar KM_TAG_OS_VERSION y KM_TAG_OS_PATCHLEVEL a Keymaster. Hasta que se llame a este método, todos los demás mostrarán KM_ERROR_KEYMASTER_NOT_CONFIGURED. Keymaster solo acepta los valores proporcionados por este método una vez por inicio. Las llamadas posteriores mostrarán KM_ERROR_OK, pero no harán nada.

Si la implementación de Keymaster está en hardware seguro y los valores de nivel de parche y versión del SO proporcionados no coinciden con los valores que el bootloader proporcionó al hardware seguro (o si el bootloader no proporcionó valores), este método mostrará KM_ERROR_INVALID_ARGUMENT y todos los demás métodos seguirán mostrando KM_ERROR_KEYMASTER_NOT_CONFIGURED.

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

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

Borra todas las claves del almacén de claves de hardware. Se usa cuando se restablece por completo el almacén de claves. Después de llamar a esta función, será imposible usar los blobs de claves generados o importados anteriormente para ninguna operación.

Esta función es opcional y debe establecerse en NULL si no se implementa.

Parámetros

[in]

dev

La estructura del dispositivo de Keymaster

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

Borra la clave o el par de claves asociado con el BLOB de claves. Después de llamar a esta función, será imposible usar la clave para ninguna otra operación. Se puede aplicar a claves de raíces de confianza externas (claves que no se pueden usar en la raíz de confianza actual).

Esta función es opcional y debe establecerse en NULL si no se implementa.

Parámetros

[in]	dev	La estructura del dispositivo de Keymaster
[in]	key	La clave que se borrará.

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

Exporta una clave pública o simétrica y muestra un array de bytes en el formato especificado.

Ten 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 (p.ej., la autenticación).

Parámetros

[in]	dev	La estructura del dispositivo de Keymaster
[in]	export_format	Es el formato que se usará para exportar la clave.
[in]	key_to_export	La clave que se exportará.
[in]	client_id	Es el BLOB del ID de cliente, que debe coincidir con el BLOB proporcionado en KM_TAG_APPLICATION_ID durante la generación de claves (si corresponde).
[in]	app_data	Blob de datos de la aplicación, que debe coincidir con el blob proporcionado en KM_TAG_APPLICATION_DATA durante la generación de claves (si corresponde)
[out]	export_data	El material de clave exportado El llamador asume la propiedad.

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

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

Parámetros

[in]	dev	La estructura del dispositivo de Keymaster
[in]	operation_handle	El identificador de operación que muestra begin() Este identificador dejará de ser válido.
[in]	in_params	Parámetros adicionales para la operación. En el caso de los modos AEAD, se usa para especificar KM_TAG_ADDITIONAL_DATA, pero solo si no se proporcionaron datos de entrada a update() .
[in]	input	Datos que se procesarán según los parámetros establecidos en la llamada a begin() . finish() debe consumir todos los datos proporcionados o mostrar KM_ERROR_INVALID_INPUT_LENGTH.
[in]	firma	Es la firma que se verificará si el propósito especificado en la llamada a begin() era KM_PURPOSE_VERIFY.
[out]	output	Los datos de salida, si corresponde El llamador asume la propiedad del búfer asignado.

Si la operación que se está finalizando es una verificación de firma o una desencriptación en modo AEAD, y la verificación falla, finish() mostrará KM_ERROR_VERIFICATION_FAILED.

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

Consulta las marcas definidas para keymaster0_devices::flags en keymaster_common.h . Se usa solo para la retrocompatibilidad. Los dispositivos de hardware de keymaster2 deben establecerlo en cero.

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

Genera una clave o un par de claves, y muestra un BLOB de clave o una descripción de la clave.

Los parámetros de generación de claves se definen como pares de etiquetas o valores de Keymaster, que se proporcionan en params . Consulta keymaster_tag_t para obtener la lista completa. Estos son algunos valores que siempre se requieren para generar claves útiles:

• KM_TAG_ALGORITHM;
• KM_TAG_PURPOSE;
• (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 esté presente KM_TAG_NO_AUTH_REQUIRED, o el usuario tendrá que autenticarse cada vez que lo use.

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; la implementación proporcionará sus valores.

• KM_TAG_ORIGIN,
• KM_TAG_ROLLBACK_RESISTANT,
• KM_TAG_CREATION_DATETIME

Parámetros

[in]	dev	La estructura del dispositivo de Keymaster
[in]	params	Array of key generation param
[out]	key_blob	muestra la clave generada. key_blob no debe ser NULL. El llamador asume la propiedad de key_blob->key_material y debe liberarlo.
[out]	características	Muestra las características de la clave que se generó, si no es NULO. Si no es NULL, el llamador asume la propiedad y debe reasignar con keymaster_free_characteristics() . Ten en cuenta que nunca se devuelven KM_TAG_ROOT_OF_TRUST, KM_TAG_APPLICATION_ID ni KM_TAG_APPLICATION_DATA.

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

Devuelve las características de la clave especificada o KM_ERROR_INVALID_KEY_BLOB si el key_blob no es válido (las implementaciones deben validar por completo 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 bien deben estar vacíos si no se proporcionaron KM_TAG_APPLICATION_ID o KM_TAG_APPLICATION_DATA durante la generación. Esos valores no se incluyen en las características que se muestran. El llamador asume la propiedad del objeto de características asignado, que se debe desasignar con keymaster_free_characteristics() .

Ten en cuenta que nunca se devuelven KM_TAG_APPLICATION_ID ni KM_TAG_APPLICATION_DATA.

Parámetros

[in]	dev	La estructura del dispositivo de Keymaster
[in]	key_blob	Es la clave de la que se recuperan las características.
[in]	client_id	Los datos del ID de cliente o NULL si no hay ninguno asociado.
[in]	app_id	Los datos de la app o NULL si no hay ninguno asociado.
[out]	características	Las características clave. No debe ser NULL. El llamador asume la propiedad del contenido y debe liberar la asignación con keymaster_free_characteristics() .

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

Importa una clave o un par de claves y muestra un BLOB de clave o una descripción de la clave.

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

• KM_TAG_ALGORITHM;
• KM_TAG_PURPOSE;
• (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. Si no se especifica, el usuario deberá autenticarse cada vez que lo use.

Las siguientes etiquetas tendrá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 usará de forma predeterminada el valor de la clave proporcionada (para claves RSA).

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

• KM_TAG_ORIGIN,
• KM_TAG_ROLLBACK_RESISTANT,
• KM_TAG_CREATION_DATETIME

Parámetros

[in]	dev	La estructura del dispositivo de Keymaster
[in]	params	Son los parámetros que definen la clave importada.
[in]	params_count	Es la cantidad de entradas en params .
[in]	key_format	Especifica el formato de los datos de clave en key_data.
[out]	key_blob	Se usa para mostrar el blob de clave opaco. No debe ser nulo. El llamador asume la propiedad del key_material contenido.
[out]	características	Se usa para mostrar las características de la clave importada. Puede ser NULL, en cuyo caso no se mostrarán características. Si no es nulo, el llamador asume la propiedad del contenido y debe reasignarlo con keymaster_free_characteristics() . Ten en cuenta que nunca se devuelven KM_TAG_APPLICATION_ID ni KM_TAG_APPLICATION_DATA.

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

Proporciona datos a una operación criptográfica en curso que se inició con begin() y, posiblemente, recibe resultados de ella.

Si operation_handle no es válido, update() mostrará KM_ERROR_INVALID_OPERATION_HANDLE.

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

Parámetros

[in]	dev	La estructura del dispositivo de Keymaster
[in]	operation_handle	El identificador de operación que muestra begin()
[in]	in_params	Parámetros adicionales para la operación. En el caso de los modos AEAD, se usa para especificar KM_TAG_ADDITIONAL_DATA. Ten en cuenta que se pueden proporcionar datos adicionales en varias llamadas a update() , pero solo hasta que se proporcionen los datos de entrada.
[in]	input	Datos que se procesarán según los parámetros establecidos en la llamada a begin() . Ten en cuenta que update() puede consumir todos los datos proporcionados o no. Consulta input_consumed .
[out]	input_consumed	Es la cantidad de datos que consumió update() . Si es inferior al importe proporcionado, el llamador debe proporcionar el resto en una llamada posterior a update() .
[out]	out_params	Parámetros de salida Se usa para mostrar datos adicionales de la operación. El llamador se apropia del array de parámetros de salida y debe liberarlo 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, begin() mostrará KM_ERROR_OUTPUT_PARAMETER_NULL.
[out]	output	Los datos de salida, si corresponde El llamador asume la propiedad del búfer asignado. El resultado no debe ser NULL.

Ten en cuenta que update() puede no proporcionar ningún resultado, en cuyo caso output->data_length será cero, y output->data puede ser NULL o tener una longitud de cero (por lo que el llamador siempre debe liberarlo).

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

Actualiza una clave antigua. Las claves pueden volverse "viejas" de dos maneras: Keymaster se puede actualizar a una versión nueva, o bien se puede actualizar el sistema para invalidar la versión del SO o el nivel de parche. En cualquier caso, los intentos de usar una clave antigua provocarán que Keymaster devuelva KM_ERROR_KEY_REQUIRES_UPGRADE. Luego, se debe llamar a este método para actualizar la clave.

Parámetros

[in]	dev	La estructura del dispositivo de Keymaster
[in]	key_to_upgrade	La clave de Keymaster que se actualizará.
[in]	upgrade_params	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.
[out]	upgraded_key	El BLOB de clave actualizado

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