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
estrue
si las claves se almacenan en hardware seguro (TEE, etc.) y nunca lo abandonen.supportsEllipticCurve
estrue
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
estrue
si el hardware admite criptografía simétrica, incluidos AES y HMAC. supportsAttestation
estrue
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
yPaddingMode::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
oKeyPurpose::SIGN
, el método muestraErrorCode::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
oKeyPurpose::VERIFY
, el método muestraErrorCode::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 serDigest::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 construye0x00 || 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 puedeDigest::NONE
Si se especificaDigest::NONE
, El método muestraErrorCode::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 muestraErrorCode::INCOMPATIBLE_DIGEST
. El tamaño de la sal es la D. - El padding de
PaddingMode::RSA_OAEP
requiere un resumen, que puedeDigest::NONE
Si se especificaDigest::NONE
, El método muestraErrorCode::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, muestraErrorCode::INVALID_ARGUMENT
. Para de verificación y desencriptación, los datos deben tener la misma longitud como la clave. De lo contrario, muestraErrorCode::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 eninputParams
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 eninputParams
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
oBlockMode::CBC
. Si el padding esPaddingMode::NONE
y el la longitud de los datos no es múltiplo del tamaño del bloque AES, devolverErrorCode::INVALID_INPUT_LENGTH
Si el padding esPaddingMode::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, devuelveErrorCode::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