Funciones de Keymaster

En esta página, se proporcionan detalles para ayudar a los implementadores de Keymaster Capas de abstracción de hardware (HAL) Abarca cada función del y en qué versión de Keymaster está disponible esa función, y describe la implementación predeterminada. Para las etiquetas, consulta la Etiquetas de keymaster.

Lineamientos generales para la implementación

Los siguientes lineamientos se aplican a todas las funciones de la API.

Parámetros de puntero de entrada

Versión: 1, 2

Los parámetros del puntero de entrada que no se utilizan para una llamada determinada se pueden NULL El llamador no está obligado a proporcionar marcadores de posición. Por ejemplo, es posible que algunos tipos y modos de clave no usen ningún valor del inParams para begin, de modo que el llamador pueda Establece inParams en NULL o proporciona un parámetro vacío. automático. Los emisores también pueden proporcionar parámetros sin usar, y los métodos de Keymaster deben no generes errores.

Si un parámetro de entrada obligatorio es NULL, se deben mostrar los métodos de Keymaster. ErrorCode::UNEXPECTED_NULL_POINTER

A partir de Keymaster 3, no hay parámetros de puntero. Todos los parámetros se pasan mediante valores o referencias de constante.

Parámetros del puntero de salida

Versión: 1, 2

Similar a los parámetros del puntero de entrada, parámetros del puntero de salida sin usar puede ser NULL. Si un método necesita devolver datos en una salida si el parámetro es NULL, debería mostrar ErrorCode::OUTPUT_PARAMETER_NULL

A partir de Keymaster 3, no hay parámetros de puntero. Todos los parámetros se pasan mediante valores o referencias de constante.

Uso inadecuado de la API

Versión: 1, 2, 3

Hay muchas maneras en que los emisores pueden hacer solicitudes que no tienen sentido o son tontos, pero técnicamente no incorrectos. Las implementaciones de Keymaster no son para fallar en tales casos o emitir un diagnóstico. El uso de claves demasiado pequeñas, la especificación de parámetros de entrada irrelevantes, la reutilización de IVs o nonces la generación de claves sin fines (por lo tanto, inútiles) y similares no deberían y se diagnostican a través de implementaciones. Omisión de los parámetros obligatorios, especificación de parámetros obligatorios no válidos y se deben diagnosticar errores similares.

Las apps, el framework y el almacén de claves de Android son responsables de asegurarte de que las llamadas a los módulos de Keymaster sean sensatas y útiles.

Funciones

getHardwareFeatures

Versión: 3

El nuevo método getHardwareFeatures expone a los clientes algunas de las del hardware seguro subyacente. El método no recibe argumentos y devuelve cuatro valores, todos booleanos:

• isSecure es true si las claves se almacenan en hardware seguro (TEE, etc.) y nunca lo abandonen.
• supportsEllipticCurve es true si la es compatible con la criptografía de curva elíptica con las curvas NIST (P-224, P-256, P-384 y P-521).
• El estado de supportsSymmetricCryptography es true si el hardware admite criptografía simétrica, incluidos AES y HMAC.
• supportsAttestation es true si la el hardware admite la generación de certificados de atestación de claves públicas de Keymaster, firmado con una clave insertada en un entorno seguro.

Los únicos códigos de error que puede mostrar este método son ErrorCode:OK. ErrorCode::KEYMASTER_NOT_CONFIGURED o uno de los códigos de error que indica una falla en la comunicación con el hardware seguro.

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

Configurar

Versión: 2

Esta función se introdujo en Keymaster 2 y dejó de estar disponible en Keymaster 3, ya que esta información está disponible en los archivos de propiedades del sistema, y la leen esos archivos durante el inicio.

Configura el keymaster. Se llama a este método una vez 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 maestro de claves. Hasta que se llame a este método, todos los demás métodos devuelven KM_ERROR_KEYMASTER_NOT_CONFIGURED Los valores que proporciona este de Keymaster una vez por inicio. Posterior las llamadas muestran KM_ERROR_OK, pero no hacen nada.

Si la implementación de Keymaster se encuentra en hardware seguro, y la versión del SO y los valores de nivel de parche proporcionados no coinciden con los valores proporcionados hardware por el bootloader (o si el bootloader no proporcionó valores), este método muestra KM_ERROR_INVALID_ARGUMENT y todas las demás siguen mostrando KM_ERROR_KEYMASTER_NOT_CONFIGURED.

keymaster_error_t (*configure)(const struct keymaster2_device* dev,
                               const keymaster_key_param_set_t* params);

Entropía de redireccionamiento

Versión: 1, 2, 3

Esta función se introdujo en Keymaster 1 como add_rng_entropy y lo cambió en Keymaster 3.

Agrega la entropía proporcionada por el llamador al grupo que usa la implementación de Keymaster 1. para generar números aleatorios, claves, IVs, etcétera.

Las implementaciones de Keymaster deben combinar de forma segura los recursos entropía del grupo, que también debe contener entropía generada internamente a partir de un generador de números aleatorios de hardware. La combinación debe controlarse para que un atacante que tenga el control total de los bits proporcionados por addRngEntropy o los generados bits, pero no ambos, no tiene una ventaja insignificante en la predicción de bits, generados a partir del grupo de entropía.

Implementaciones de Keymaster que intentan estimar la entropía en su supondrán que los datos proporcionados por addRngEntropy no contiene entropía. Las implementaciones de Keymaster pueden mostrar ErrorCode::INVALID_INPUT_LENGTH si se le dieron más de 2 KiB de datos en una sola llamada.

generar clave

Versión: 1, 2, 3

Esta función se introdujo en Keymaster 1 como generate_key y lo cambió en Keymaster 3.

Genera una clave criptográfica nueva, especificando las autorizaciones asociadas. que están vinculados permanentemente a la clave. Las implementaciones de Keymaster hacen que sea es imposible usar una clave de ninguna forma que no coincida con las autorizaciones especificadas en el momento de la generación. Con respecto a las autorizaciones a las que hardware no puede exigir el cumplimiento, la obligación del hardware seguro se limita lo que garantiza que las autorizaciones inaplicables asociadas con la clave modificarse, de manera que cada llamada a getKeyCharacteristics devuelve el valor original. Además, las características devueltas por generateKey asigna las autorizaciones correctamente entre las listas aplicadas por hardware y por software. Consulta getKeyCharacteristics para obtener más detalles.

Los parámetros proporcionados a generateKey dependen del tipo de clave que se está generando. Esta sección resume las etiquetas necesarias y opcionales para cada tipo de clave. Tag::ALGORITHM siempre es necesario para especificar el tipo.

Claves RSA

Los siguientes parámetros son necesarios para generar una clave RSA.

• Etiqueta::KEY_SIZE especifica el tamaño del módulo público en bits. Si se omite, el método muestra ErrorCode::UNSUPPORTED_KEY_SIZE. Los valores admitidos son 1024, 2048, 3072 y 4096. Valores recomendados son todos los tamaños de clave que son múltiplos de 8.
• Tag::RSA_PUBLIC_EXPONENT especifica el valor del exponente público RSA. Si se omite, el método muestra ErrorCode::INVALID_ARGUMENT. Los valores admitidos son 3 y 65,537. Los valores recomendados son los siguientes: todos los valores primos hasta 2^64.

Los siguientes parámetros no son necesarios para generar una clave RSA, pero crear una clave RSA sin ellos produce una clave que no se puede usar. Sin embargo, el La función generateKey no muestra un error si estos parámetros se omiten.

• Tag::PURPOSE especifica los fines permitidos. Todos los propósitos deben ser compatibles con las claves RSA, en cualquier combinación.
• Tag::DIGEST especifica de resumen que se pueden usar con la clave nueva. Implementaciones que no admiten todos los algoritmos de resumen deben aceptar la generación de claves las solicitudes que incluyen resúmenes no admitidos. Los resúmenes no admitidos deben ser colocado en la sección "Aplicación de reglas de firewall" en las características clave que se devuelven. Esto se debe a que la clave se puede usar con esos otros resúmenes, que se llevan a cabo en el software. Luego, se llama al hardware para que realice la operación con Digest::NONE.
• Tag::PADDING especifica la modos de relleno que se pueden usar con la clave nueva. Implementaciones que no admiten todos los algoritmos de resumen deben colocar PaddingMode::RSA_PSS y PaddingMode::RSA_OAEP in la lista de características clave aplicada por software si alguna no compatible se especifican los algoritmos de resumen.

Claves de ECDSA

Solo se estableció Tag::KEY_SIZE necesarias para generar una clave ECDSA. Se usa para seleccionar el grupo de conversiones avanzadas. Los valores admitidos son 224, 256, 384 y 521, que indican la Curvas p-224, p-256, p-384 y p521 del NIST, respectivamente.

Tag::DIGEST también es necesaria para una clave ECDSA útil, pero no es necesaria para generarla.

Claves AES

Solo Tag::KEY_SIZE se necesita para generar una clave AES. Si se omite, el método devuelve ErrorCode::UNSUPPORTED_KEY_SIZE Valores admitidos: 128 y 256, con compatibilidad opcional para claves AES de 192 bits.

Los siguientes parámetros son particularmente relevantes para las claves AES, pero no necesario para generar uno:

• Tag::BLOCK_MODE especifica los modos de bloque con los que se puede usar la clave nueva.
• Tag::PADDING especifica los modos de padding que se podrían ejecutar que se usan. Esto solo es relevante para los modos ECB y CBC.

Si se especifica el modo de bloque de GCM, debes proporcionar el Tag::MIN_MAC_LENGTH. Si se omite, el método muestra ErrorCode::MISSING_MIN_MAC_LENGTH. El valor de la etiqueta es un múltiplo de 8 y entre 96 y 128.

Claves HMAC

Los siguientes parámetros son obligatorios para la generación de claves HMAC:

• Etiqueta::KEY_SIZE especifica el tamaño de la clave en bits. Valores inferiores a 64 ni valores que no sean múltiplos de 8. Todo se admiten múltiplos de 8, de 64 a 512. Los valores más altos pueden no es compatible.
• Etiqueta::MIN_MAC_LENGTH especifica la longitud mínima de Son las MAC que se pueden generar o verificar con esta clave. El valor es un múltiplo de 8 y al menos 64.
• Tag::DIGEST especifica el algoritmo de resumen de la clave. Exactamente se especifica un resumen; de lo contrario, se muestra ErrorCode::UNSUPPORTED_DIGEST Si el resumen no es compatible por el Trustlet, devolverá ErrorCode::UNSUPPORTED_DIGEST

Características clave

Si el argumento features no es NULL, generateKey muestra las características de la clave generada recientemente divididas listas aplicadas por hardware y por software. Consulta getKeyCharacteristics para una descripción de qué características figuran en cada lista. Los atributos que se muestran incluir todos los parámetros especificados para la generación de claves, excepto Tag::APPLICATION_ID y Tag::APPLICATION_DATA. Si estas etiquetas se incluyeron en los parámetros clave, se quitarán de los atributos devueltos, de modo que no sea posible encontrar sus valores examinando el BLOB de clave que se muestra. Sin embargo, están vinculados a nivel criptográfico. al BLOB de claves, de modo que, si no se proporcionan los valores correctos cuando la clave se si se usan, el uso falla. De forma similar, Tag::ROOT_OF_TRUST es vinculado criptográficamente a la clave, pero puede que no se especifique durante la creación o importación de claves, y nunca se muestra.

Además de las etiquetas proporcionadas, el Trustlet también agrega Tag::ORIGIN. con el valor KeyOrigin::GENERATED, y si la clave es resistente a las reversiones,

Resistencia a la reversión

La resistencia a la reversión significa que, una vez que la clave se borra con deleteKey o deleteAllKeys, se garantiza con hardware seguro que no se puedan volver a usar. Por lo general, se implementan sin resistencia a la reversión mostrará el material de clave generado o importado al llamador como un BLOB de claves, un formulario encriptado y autenticado. Cuando el almacén de claves borra el BLOB de claves, la clave se ha desaparecido, pero un atacante que ha logrado recuperar el material de claves y, tal vez, puedas restablecerla en el dispositivo.

Una clave es resistente a las reversiones si el hardware seguro garantiza que las claves no se pueden restablecer. Generalmente, esto se logra almacenando claves metadatos en una ubicación de confianza que no puede ser manipulada por un atacante. Activada dispositivos móviles, el mecanismo utilizado para esto suele ser la repetición de la memoria protegida. Bloques (RPMB) Debido a que la cantidad de claves que se pueden crear es esencial no delimitado y es posible que se limite el almacenamiento de confianza que se usa para la resistencia a la reversión en tamaño, este método debe tener éxito incluso si la resistencia a la reversión no se puede proporcionar para la clave nueva. En ese caso, Tag::ROLLBACK_RESISTANT no deben agregarse a las características clave.

getKeyCharacteristics

Versión: 1, 2, 3

Esta función se introdujo en Keymaster 1 como Se cambió el nombre de get_key_characteristics en Keymaster 3.

Muestra parámetros y autorizaciones asociados con la clave proporcionada. divididas en dos conjuntos: aplicada por hardware y aplicada por software. La descripción se aplica de la misma forma a las listas de características clave que muestran importKey y generateKey.

Si se proporcionó Tag::APPLICATION_ID durante la generación de la clave o importar, se proporciona el mismo valor este método en el argumento clientId. De lo contrario, el muestra ErrorCode::INVALID_KEY_BLOB. De forma similar, si se proporcionó Tag::APPLICATION_DATA durante la generación o importar, se proporciona el mismo valor este método en el argumento appData.

Las características mostradas por este método describen completamente el tipo y el uso de la clave especificada.

La regla general para decidir si una etiqueta determinada pertenece al aplicada por hardware o por software es que si el significado de la etiqueta cuenta con la garantía de que el hardware seguro se aplica de manera forzosa. De lo contrario, de que se aplique el software. A continuación, se muestra una lista de etiquetas específicas cuya asignación correcta pueden ser poco claros:

• Tag::ALGORITHM, Etiqueta::KEY_SIZE, y Tag::RSA_PUBLIC_EXPONENT son propiedades intrínsecas de la clave. Para cualquier clave protegida por hardware, estas etiquetas estarán en la lista de aplicaciones aplicadas por hardware.
• Valores Tag::DIGEST que son compatibles con el hardware seguro se colocan hardware compatible. Los resúmenes no compatibles se incluyen en la lista que admite software.
• Valores Tag::PADDING suelen incluirse en la lista de dispositivos compatibles con hardware, a menos que haya posibilidad de que el software deba ejecutar un modo de relleno específico. En ese caso, se incluyen en la lista de aplicaciones aplicadas por software. Esa posibilidad se produce para las claves RSA que permiten rellenar OAEP o PSS con algoritmos de resumen que no son compatibles con el hardware seguro.
• Etiqueta::USER_SECURE_ID y Tag::USER_AUTH_TYPE se aplican por hardware solo si la autenticación de usuario es el hardware establecido. Para para lograrlo, el Trustlet de Keymaster y el certificado de autenticación relevante Estos deben ser seguros y compartir una clave HMAC secreta que se usa para firmar y y validar tokens de autenticación. Consulta la página Autenticación para obtener más detalles.
• Tag::ACTIVE_DATETIME, Tag::ORIGINATION_EXPIRE_DATETIME, y etiquetas Tag::USAGE_EXPIRE_DATETIME que requieran acceso a un reloj de pared que se pueda verificar correctamente. Hardware más seguro solo tiene acceso a la información de hora proporcionada por el SO no seguro, que significa que las etiquetas se implementan mediante software.
• Tag::ORIGIN es siempre está en la lista de hardware para claves vinculadas a hardware. Su presencia en ese es la forma en que las capas superiores determinan que una clave tiene copia de seguridad en hardware.

importarClave

Versión: 1, 2, 3

Esta función se introdujo en Keymaster 1 como import_key y lo cambió en Keymaster 3.

Importa material de claves al hardware de Keymaster. Los parámetros de definición clave y las características de salida se manejan de la misma manera que para generateKey. con las siguientes excepciones:

• Tag::KEY_SIZE y Etiqueta::RSA_PUBLIC_EXPONENT (solo para claves RSA) no son necesarias en los parámetros de entrada. Si no se proporciona, el Trustlet deduce los valores del material de clave proporcionado y suma con las etiquetas y los valores adecuados para las características clave. Si los parámetros son proporciona, el Trustlet los valida en función del material de clave. En la de una discrepancia, el método muestra ErrorCode::IMPORT_PARAMETER_MISMATCH.
• La Tag::ORIGIN que se muestra tiene la mismo valor que KeyOrigin::IMPORTED.

clave de exportación

Versión: 1, 2, 3

Esta función se introdujo en Keymaster 1 como export_key y lo cambió en Keymaster 3.

Exporta una clave pública desde un par de claves EC o RSA de Keymaster.

Si se proporcionó Tag::APPLICATION_ID durante la generación de la clave o de importación, se proporciona el mismo valor a este método en clientId. De lo contrario, el método devuelve ErrorCode::INVALID_KEY_BLOB Del mismo modo, si Tag::APPLICATION_DATA se proporciona durante la generación o la importación, se proporciona el mismo valor a este método en el argumento appData.

borrar clave

Versión: 1, 2, 3

Esta función se introdujo en Keymaster 1 como delete_key y lo cambió en Keymaster 3.

Borra la clave proporcionada. Este método es opcional y solo que implementan los módulos de Keymaster, que brindan resistencia a la reversión.

deleteAllKeys

Versión: 1, 2, 3

Esta función se introdujo en Keymaster 1 como delete_all_keys y lo cambió en Keymaster 3.

Borra todas las claves. Este método es opcional y solo se implementa por los módulos de Keymaster que brindan resistencia a la reversión.

destroyAttestationIds

Versión: 3

Se usa el método destroyAttestationIds() para inhabilitar la nueva (opcional, pero altamente recomendada) Certificación de ID . Si el TEE no tiene forma de garantizar que la certificación de la ID sea permanente inhabilitado después de llamar a este método, entonces no se debe implementar en absoluto, en cuyo caso este método no hace nada y muestra ErrorCode::UNIMPLEMENTED. Si la certificación de ID es compatible, este método debe implementarse y debe inhabilitarse de forma permanente todos los intentos futuros de certificación de ID. El método se puede llamar a cualquier cantidad de veces. Si la certificación de ID ya está inhabilitada de forma permanente, el método No hay nada y muestra ErrorCode::OK.

Los únicos códigos de error que puede mostrar este método son ErrorCode::UNIMPLEMENTED (si no se admite la certificación de ID) ErrorCode:OK, ErrorCode::KEYMASTER_NOT_CONFIGURED o uno de los códigos de error que indica un error al comunicarse con el hardware.

begin

Versión: 1, 2, 3

Inicia una operación criptográfica, con la clave especificada, para el valor especificado propósito, con los parámetros especificados (según corresponda) y devuelve un controlador de operación que se usa con update y finish para completarla. El controlador de operación es también se utiliza como el "desafío" token en operaciones autenticadas y para tales operaciones se incluyen en el campo challenge de la token de autenticación.

Una implementación de Keymaster admite al menos 16 apps las operaciones. El almacén de claves usa hasta 15 caracteres, lo que deja uno para que vold lo use como contraseña. encriptación. Cuando el almacén de claves tiene 15 operaciones en curso (begin tiene se llamó, pero finish o abort todavía no se han recibe una solicitud para comenzar un día 16, llama abort en la operación menos utilizada para reducir la cantidad de operaciones activas a 14 antes de llamar a begin para iniciar operación solicitada recientemente.

Si Tag::APPLICATION_ID o Tag::APPLICATION_DATA durante la generación o importación de la clave, las llamadas a begin incluyen aquellas etiquetas con los valores especificados originalmente en el argumento inParams a este método.

Aplicación de la autorización

Durante este método, las siguientes autorizaciones de clave se aplican. la confianza si la implementación los colocó en el dominio y si la operación no es de clave pública. Clave pública operaciones, lo que significa KeyPurpose::ENCRYPT y KeyPurpose::VERIFY, con claves RSA o EC, pueden tener éxito incluso si la que los requisitos no se cumplan.

• Tag::PURPOSE: El propósito especificados en la llamada begin() debe coincidir con uno de los propósitos en las autorizaciones de clave, a menos que la operación solicitada sea de clave pública una sola operación. Si el propósito especificado no coincide y la operación no una operación de clave pública, begin mostrará ErrorCode::UNSUPPORTED_PURPOSE Las operaciones de clave pública se la criptografía asimétrica o las operaciones de verificación.
• Etiqueta: ACTIVE_DATETIME solo se pueden aplicar de manera forzosa si hay disponible una fuente de hora UTC confiable. Si el botón la fecha y hora actuales es anterior al valor de la etiqueta, el método devuelve ErrorCode::KEY_NOT_YET_VALID
• Etiqueta::ORIGINATION_EXPIRE_DATETIME solo se pueden aplicar de manera forzosa si hay disponible una fuente de hora UTC confiable. Si el botón la fecha y hora actuales es posterior al valor de la etiqueta, y el propósito es KeyPurpose::ENCRYPT o KeyPurpose::SIGN, el método muestra ErrorCode::KEY_EXPIRED.
• Etiqueta: USAGE_EXPIRE_DATETIME solo se pueden aplicar de manera forzosa si hay disponible una fuente de hora UTC confiable. Si el botón la fecha y hora actuales es posterior al valor de la etiqueta, y el propósito es KeyPurpose::DECRYPT o KeyPurpose::VERIFY, el método muestra ErrorCode::KEY_EXPIRED.
• Etiqueta::MIN_SECONDS_BETWEEN_OPS se compara con un temporizador relativo de confianza que indica el último uso de la clave. Si la hora del último uso más el valor de la etiqueta es menor que la hora actual, el método muestra ErrorCode::KEY_RATE_LIMIT_EXCEEDED. Consulta la descripción de la etiqueta para conocer detalles importantes sobre la implementación.
• Etiqueta::MAX_USES_PER_BOOT se compara con un contador seguro que rastrea los usos de la clave desde el inicio. Si el recuento de usos anteriores supera el valor de la etiqueta, el muestra ErrorCode::KEY_MAX_OPS_EXCEEDED.
• Etiqueta::USER_SECURE_ID se aplica mediante este método solo si la clave también tiene Tag::AUTH_TIMEOUT. Si la clave tiene ambos, este método debe recibir un Tag::AUTH_TOKEN en inParams Para que el token de autenticación sea válido, se deben cumplir todas las siguientes condiciones: tiene que ser cierto:
  • El campo HMAC se valida correctamente.
  • Al menos uno de los Etiqueta::USER_SECURE_ID de la clave coincida con al menos uno de los valores de ID seguro en la token.
  • La clave tiene un Etiqueta::USER_AUTH_TYPE que coincida con el tipo de autenticación del token.

  Si no se cumple alguna de estas condiciones, el método devuelve ErrorCode::KEY_USER_NOT_AUTHENTICATED

• Tag::CALLER_NONCE permite que el emisor especifique un nonce o un vector de inicialización (IV). Si la clave no tiene esta etiqueta, pero el emisor proporcionó Tag::NONCE a este método, Se devuelve ErrorCode::CALLER_NONCE_PROHIBITED.
• Tag::BOOTLOADER_ONLY especifica que solo el bootloader puede usar la clave. Si este método es se llama con una clave exclusiva de bootloader una vez que termina de ejecutarse se muestra ErrorCode::INVALID_KEY_BLOB.

Claves RSA

Todas las operaciones de clave RSA especifican exactamente un modo de relleno en inParams. Si no se especifica o se especifica más de una vez, el método muestra ErrorCode::UNSUPPORTED_PADDING_MODE

Las operaciones de firma y verificación RSA necesitan un resumen, al igual que la encriptación RSA. de encriptación y desencriptación con el modo de relleno OAEP. En esos casos, el llamador especifica exactamente un resumen en inParams. Si no se especifica o se especifica más de una vez, el método muestra ErrorCode::UNSUPPORTED_DIGEST.

Operaciones de clave privada (KeyPurpose::DECYPT y KeyPurpose::SIGN) necesitan autorización de resumen y relleno, lo que significa que las autorizaciones de deben contener los valores especificados. De lo contrario, el método devuelve ErrorCode::INCOMPATIBLE_DIGEST o ErrorCode::INCOMPATIBLE_PADDING, según corresponda. Operaciones de clave pública (KeyPurpose::ENCRYPT y KeyPurpose::VERIFY) se permiten con resumen o relleno no autorizados.

A excepción de PaddingMode::NONE, se admiten todos los modos de padding de RSA. aplicables solo a ciertos fines. Específicamente: PaddingMode::RSA_PKCS1_1_5_SIGN y PaddingMode::RSA_PSS solo admiten firmas y verificación, mientras que PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT y PaddingMode::RSA_OAEP solo admiten encriptación y desencriptación. El método muestra ErrorCode::UNSUPPORTED_PADDING_MODE si el valor el modo especificado no admite el propósito especificado.

Existen algunas interacciones importantes entre los modos de relleno y los resúmenes:

• PaddingMode::NONE indica que un elemento "sin procesar" La operación de RSA es una tarea. Si se firma o se verifica, Digest::NONE es especificadas para el resumen. No es necesario un resumen para la encriptación sin padding o desencriptación.
• El padding de PaddingMode::RSA_PKCS1_1_5_SIGN requiere un resumen. El El resumen puede ser Digest::NONE, en cuyo caso el Keymaster no puede crear una estructura de firma PKCS#1 v1.5 adecuada porque no puede agregar la estructura DigestInfo. En cambio, la implementación construye 0x00 || 0x01 || PS || 0x00 || M, donde M es la y PS es la cadena de relleno. El tamaño de la clave RSA debe debe ser al menos 11 bytes más grande que el mensaje; de lo contrario, el método mostrará ErrorCode::INVALID_INPUT_LENGTH
• El padding de PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT no requiere un resumen.
• El padding de PaddingMode::RSA_PSS requiere un resumen, que puede Digest::NONE Si se especifica Digest::NONE, El método muestra ErrorCode::INCOMPATIBLE_DIGEST. Además, el el tamaño de la clave RSA debe ser al menos 2 + D bytes más grande que la salida el tamaño del resumen, en el que D es el tamaño del resumen, en bytes. En caso contrario el método muestra ErrorCode::INCOMPATIBLE_DIGEST. El tamaño de la sal es la D.
• El padding de PaddingMode::RSA_OAEP requiere un resumen, que puede Digest::NONE Si se especifica Digest::NONE, El método muestra ErrorCode::INCOMPATIBLE_DIGEST.

Claves de EC

Las operaciones de clave EC especifican exactamente un modo de relleno en inParams. Si no se especifica o se especifica más de una vez, el método muestra ErrorCode::UNSUPPORTED_PADDING_MODE.

Las operaciones de clave privada (KeyPurpose::SIGN) necesitan autorización de resumen y relleno, lo que significa que las autorizaciones de claves deben contener los valores especificados. De lo contrario, devuelve ErrorCode::INCOMPATIBLE_DIGEST Operaciones de clave pública (KeyPurpose::VERIFY) se permiten con resumen o relleno no autorizados.

Claves AES

Las operaciones de clave AES especifican exactamente un modo de bloque y un modo de relleno en inParams. Si alguno de los valores no se especifica o si se especifica más de una vez, muestra ErrorCode::UNSUPPORTED_BLOCK_MODE o ErrorCode::UNSUPPORTED_PADDING_MODE Los modos especificados deben ser autorizado por la clave; de lo contrario, el método devuelve ErrorCode::INCOMPATIBLE_BLOCK_MODE o ErrorCode::INCOMPATIBLE_PADDING_MODE

Si el modo de bloqueo es BlockMode::GCM, inParams. especifica Tag::MAC_LENGTH, y el el valor especificado es un múltiplo de 8 que no sea mayor que 128 o menos que el valor de Tag::MIN_MAC_LENGTH en el autorizaciones clave. Para longitudes de MAC mayores a 128 o no múltiplos de 8, muestra ErrorCode::UNSUPPORTED_MAC_LENGTH. Para valores inferiores que la longitud mínima de la clave, muestra ErrorCode::INVALID_MAC_LENGTH.

Si el modo de bloqueo es BlockMode::GCM o BlockMode::CTR, el modo de padding especificado debe ser PaddingMode::NONE. Para BlockMode::ECB o BlockMode::CBC, el modo puede ser PaddingMode::NONE o PaddingMode::PKCS7. Si el modo de relleno no cumple con estas condiciones, muestra ErrorCode::INCOMPATIBLE_PADDING_MODE.

Si el modo de bloqueo es BlockMode::CBC, BlockMode::CTR, o BlockMode::GCM, se necesita un vector de inicialización o un nonce. En la mayoría de los casos, los emisores no deben proporcionar un IV o un nonce. En ese caso, el La implementación de Keymaster genera un IV o un nonce aleatorio y lo muestra mediante Tag::NONCE en outParams. Los valores de CBC y CTR IV son de 16 bytes. Los nonces de GCM son de 12 bytes. Si la clave las autorizaciones contienen Tag::CALLER_NONCE, el emisor puede proporcionar un IV/nonce con Etiqueta::NOCE en inParams. Si se proporciona un nonce cuando Tag::CALLER_NONCE no está autorizado, devuelve ErrorCode::CALLER_NONCE_PROHIBITED. Si no se proporciona un nonce cuando Tag::CALLER_NONCE genera un IV/nonce aleatorio.

Claves HMAC

Las operaciones de clave HMAC especifican Tag::MAC_LENGTH en inParams. El valor especificado debe ser un múltiplo de 8 que no sea mayor que el longitud del resumen o menor que el valor de Tag::MIN_MAC_LENGTH en las autorizaciones de clave. Para longitudes de MAC mayores que la longitud del resumen o no múltiplos de 8, muestra ErrorCode::UNSUPPORTED_MAC_LENGTH. Para valores inferiores a la longitud mínima de la clave, muestra ErrorCode::INVALID_MAC_LENGTH

update

Versión: 1, 2, 3

Proporciona datos para procesar en una operación en curso que comienza con begin. La operación se especifica mediante el parámetro operationHandle.

Para proporcionar más flexibilidad en el manejo del búfer, las implementaciones de este método tienen la opción de consumir menos datos de los proporcionados. La persona que llama es Es responsable de repetir indefinidamente el resto de los datos en las llamadas posteriores. El La cantidad de entrada consumida se muestra en el parámetro inputConsumed. Las implementaciones siempre consumen al menos un byte, a menos que el operación ya no puede aceptar más; si se proporcionan más de cero bytes y cero bytes individuales, los llamadores lo consideran un error y anulan la operación.

Las implementaciones también pueden elegir cuántos datos mostrar como resultado del actualización. Esto solo es relevante para las operaciones de encriptación y desencriptación, la firma y la verificación no devuelven datos hasta que completen. Muestra los datos lo antes posible, en lugar de almacenarlos en búfer.

Manejo de errores

Si este método devuelve un código de error distinto de ErrorCode::OK, se anula la operación y se invalida el controlador de la operación. Cualquiera el uso futuro del controlador, con este método, Finish o abort muestra ErrorCode::INVALID_OPERATION_HANDLE.

Aplicación de la autorización

La aplicación forzosa de la autorización de claves se realiza principalmente en begin. La única excepción se da cuando la clave tiene lo siguiente:

• Uno o más Tag::USER_SECURE_IDs y
• No tiene una Tag::AUTH_TIMEOUT.

En este caso, la clave requiere una autorización por operación, y la actualización método recibe una Tag::AUTH_TOKEN en el argumento inParams. HMAC verifica que el token sea válido y contenga un ID de usuario seguro coincidente, que coincida con el Tag::USER_AUTH_TYPE, y contiene el controlador de operación de la operación actual en la de desafío. Si no se cumplen estas condiciones, devuelve ErrorCode::KEY_USER_NOT_AUTHENTICATED

El llamador proporciona el token de autenticación a cada llamada para update y terminar. La implementación solo necesita validar el token una vez, si así lo prefiere.

Claves RSA

Para las operaciones de firma y verificación con Digest::NONE, haz lo siguiente: este método acepta que todo el bloque se firme o verifique en una sola actualización. Es posible que no consuma solo una parte del bloque. Sin embargo, si el llamador si elige proporcionar los datos en varias actualizaciones, este método los acepta. Si el emisor proporciona más datos para firmar de los que puede usar (longitud de si los datos superan el tamaño de la clave RSA), muestra ErrorCode::INVALID_INPUT_LENGTH.

Claves de ECDSA

Para las operaciones de firma y verificación con Digest::NONE, haz lo siguiente: este método acepta que todo el bloque se firme o verifique en una sola actualización. Es posible que este método no consuma solo una parte del bloque.

Sin embargo, si el emisor elige proporcionar los datos en varias actualizaciones este método los acepta. Si el emisor proporciona más datos para firmar de lo que se puede usar, los datos se truncan en silencio. (Difiere del y el manejo del exceso de datos que se proporcionan en operaciones RSA similares. El motivo es la compatibilidad con clientes heredados).

Claves AES

El modo AES GCM admite "datos de autenticación asociados", proporcionadas mediante la Tag::ASSOCIATED_DATA etiqueta en el argumento inParams. Los datos asociados se pueden proporcionar en llamadas repetidas (importante si los datos son demasiado grandes para enviarlos en un solo bloque), pero siempre preceden a los datos. que se encripten o desencripten. Una llamada de actualización puede recibir datos asociados y datos para encriptar y desencriptar, pero es posible que las actualizaciones posteriores no incluyan de datos no estructurados. Si el emisor proporciona datos asociados a una llamada de actualización después de una llamada que incluya datos para encriptar y desencriptar, muestra ErrorCode::INVALID_TAG.

Para la encriptación de GCM, la etiqueta se agrega al texto cifrado fin. Durante la desencriptación, el último Tag::MAC_LENGTH bytes de los datos proporcionados al último de actualización es la etiqueta. Ya que una invocación dada de update no puede saber si es la última invocación, Procesa todo excepto la longitud de la etiqueta y almacena en búfer los datos posibles de la etiqueta. durante finish.

finalizar

Versión: 1, 2, 3

Finaliza una operación en curso que comienza con begin. procesar todos los datos aún sin procesar proporcionados por actualizaciones.

Este método es el último al que se llama en una operación, así que se devuelven los datos procesados.

Si se completa correctamente o devuelve un error, este método finaliza y, por lo tanto, invalida el controlador de operación proporcionado. Cualquiera el uso futuro del controlador con este método o update o abort, muestra ErrorCode::INVALID_OPERATION_HANDLE.

Las operaciones de firma muestran la firma como resultado. Operaciones de verificación Acepta la firma en el parámetro signature y no muestra resultados.

Aplicación de la autorización

La aplicación forzosa de la autorización de claves se lleva a cabo principalmente en begin La única excepción se da cuando la clave tiene lo siguiente:

• Uno o más Tag::USER_SECURE_IDs y
• No contiene un Tag::AUTH_TIMEOUT

En este caso, la clave requiere una autorización por operación, y la actualización método recibe una Tag::AUTH_TOKEN en el argumento inParams. HMAC verifica que el token es válido y contiene un ID de usuario seguro que coincide, coincide con el de la clave Tag::USER_AUTH_TYPE y contiene el controlador de operación de la operación actual en la de desafío. Si no se cumplen estas condiciones, devuelve ErrorCode::KEY_USER_NOT_AUTHENTICATED

El llamador proporciona el token de autenticación a cada llamada a update y finish. La implementación solo necesita validar el token una vez, si así lo prefiere.

Claves RSA

Estos son algunos requisitos adicionales, según el modo de padding:

• PaddingMode::NONE Para las operaciones de encriptación y firma sin rellenar, si los datos proporcionados son más cortos que la clave, los datos no tendrán relleno la izquierda antes de la firma o encriptación. Si los datos tienen la misma longitud que la clave, pero numéricamente más grande, muestra ErrorCode::INVALID_ARGUMENT. Para de verificación y desencriptación, los datos deben tener la misma longitud como la clave. De lo contrario, muestra ErrorCode::INVALID_INPUT_LENGTH..
• PaddingMode::RSA_PSS Para operaciones de firmas con relleno de PSS, la sal del PSS es el tamaño del resumen del mensaje y se genera de forma aleatoria. El resumen especificado con Tag::DIGEST en inputParams del begin se usa como resumen del PSS. y como el algoritmo de resumen de MGF1.
• PaddingMode::RSA_OAEP El resumen especificado con Tag::DIGEST en inputParams en begin se usa como OAEP. de resumen y SHA1 se usa como el algoritmo de resumen de MGF1.

Claves de ECDSA

Si los datos proporcionados para la verificación o la firma sin rellenar son demasiado largos, truncar que la modifica.

Claves AES

Estas son algunas condiciones adicionales, según el modo de bloqueo:

• BlockMode::ECB o BlockMode::CBC. Si el padding es PaddingMode::NONE y el la longitud de los datos no es múltiplo del tamaño del bloque AES, devolver ErrorCode::INVALID_INPUT_LENGTH Si el padding es PaddingMode::PKCS7, rellena los datos según la especificación PKCS#7. Ten en cuenta que PKCS#7 recomienda agregar un bloque de padding adicional. si los datos son múltiplos de la longitud del bloque.
• BlockMode::GCM Durante la encriptación, después del procesamiento como texto simple, calcula la etiqueta (Tag::MAC_LENGTH bytes) y adjúntalo al texto cifrado devuelto. Durante la desencriptación, procesar la última Tag::MAC_LENGTH bytes como la etiqueta. Si falla la verificación de la etiqueta, devuelve ErrorCode::VERIFICATION_FAILED

anular

Versión: 1, 2, 3

Anula la operación en curso. Después de la llamada para anular, regresar ErrorCode::INVALID_OPERATION_HANDLE para cualquier uso posterior del controlador de operación proporcionado con update terminar o abortar.

get_supported_algorithms

Versión: 1

Devuelve la lista de algoritmos admitidos por el hardware de Keymaster. para implementarlos. Una implementación de software muestra una lista vacía. un modelo híbrido una implementación muestra una lista que contiene solo los algoritmos son compatibles con el hardware.

Las implementaciones de Keymaster 1 admiten RSA, EC, AES y HMAC.

get_supported_block_modes

Versión: 1

Devuelve la lista de modos de bloqueo de AES admitidos por el hardware de Keymaster. implementación para un algoritmo y un propósito especificados.

Para RSA, EC y HMAC, que no son algoritmos de cifrado por bloques, el método devuelve un lista vacía para todos los fines válidos. Los fines no válidos deberían hacer que el método Se muestra ErrorCode::INVALID_PURPOSE.

Las implementaciones de Keymaster 1 admiten ECB, CBC, CTR y GCM para AES. encriptación y desencriptación.

get_supported_padding_modes

Versión: 1

Devuelve la lista de modos de relleno que admite el hardware de Keymaster implementación para un algoritmo y un propósito especificados.

HMAC y EC no tienen noción de relleno, por lo que el método devuelve una lista vacía. para todos los fines válidos. Los propósitos no válidos deberían hacer que el método devuelva ErrorCode::INVALID_PURPOSE

Para RSA, las implementaciones de Keymaster 1 admiten lo siguiente:

• Encriptación, desencriptación, firma y verificación sin rellenar. Sin relleno encriptación y firma, si el mensaje es más corto que el módulo público, implementaciones deben escribir en el borde izquierdo con ceros. Para la desencriptación sin rellenar verificación, la longitud de entrada debe coincidir con el tamaño del módulo público.
• Modos de relleno de encriptación y firma PKCS#1 v1.5
• PSS con una longitud mínima de sal de 20
• OAEP

Para AES en modos ECB y CBC, las implementaciones de Keymaster 1 no admiten y PKCS#7-padding. Los modos CTR y GCM solo admiten no relleno.

get_supported_digests

Versión: 1

Devuelve la lista de modos de resumen compatibles con el hardware de Keymaster. implementación para un algoritmo y un propósito especificados.

Ningún modo AES admite ni requiere resumen, por lo que el método muestra un valor vacío. lista con fines válidos.

Las implementaciones de Keymaster 1 pueden implementar un subconjunto de las opciones resúmenes. Las implementaciones proporcionan SHA-256 y pueden proporcionar MD5, SHA1, SHA-224, SHA-256, SHA384 y SHA512 (el conjunto completo de resúmenes definidos).

get_supported_import_formats

Versión: 1

Devuelve la lista de formatos de importación que admite el hardware de Keymaster. implementación de un algoritmo específico.

Las implementaciones de Keymaster 1 admiten el formato PKCS#8 (sin contraseña). protección) para importar pares de claves RSA y EC, y admitir la importación RAW de Material de claves AES y HMAC

get_supported_export_formats

Versión: 1

Devuelve la lista de formatos de exportación que admite el hardware de Keymaster. implementación de un algoritmo específico.

Las implementaciones de Keymaster1 admiten el formato X.509 para exportar RSA y claves públicas de EC. No se admite la exportación de claves privadas ni claves asimétricas.

Funciones históricas

Keymaster 0

Las siguientes funciones pertenecen a la definición original de Keymaster 0. Ellas estaban presentes en el struct keymaster1_device_t de Keymaster 1. Sin embargo, en Keymaster 1.0 no se implementaron y los punteros de función se configuraron con el valor NULL.

• generate_keypair
• import_keypair
• get_keypair_public
• delete_keypair
• delete_all
• sign_data
• Verify_data

Keymaster 1

Las siguientes funciones pertenecen a la definición de Keymaster 1, pero se en Keymaster 2, junto con las funciones de Keymaster 0 mencionadas anteriormente.

• get_supported_algorithms
• get_supported_block_modes
• get_supported_padding_modes
• get_supported_digests
• get_supported_import_formats
• get_supported_export_formats

Keymaster 2

Las siguientes funciones pertenecen a la definición de Keymaster 2, pero se en Keymaster 3, junto con las funciones de Keymaster 1 mencionadas anteriormente.

• configure