Esta página proporciona detalles para ayudar a los implementadores de Keymaster HAL. Cubre cada etiqueta en HAL, en qué versión de Keymaster está disponible esa etiqueta y si la etiqueta es repetible. Excepto lo que se indica en las descripciones de las etiquetas, todas las etiquetas siguientes se utilizan durante la generación de claves para especificar las características clave.
Para Keymaster 4, las etiquetas se definen en platform/hardware/interfaces/keymaster/ keymaster-version /types.hal , como 3.0/types.hal para Keymaster 3 y 4.0/types.hal para Keymaster 4. Para Keymaster 2 y versiones anteriores, Las etiquetas se definen en platform/hardware/libhardware/include/hardware/keymaster_defs.h .
Para conocer las funciones, consulte la página Funciones del Keymaster .
Etiqueta::ACTIVE_DATETIME
Versión : 1, 2, 3, 4
¿ Repetible ? No
Especifica la fecha y hora en que la clave se activa. Antes de este momento, cualquier intento de utilizar la clave falla con ErrorCode::KEY_NOT_YET_VALID .
El valor es un entero de 64 bits que representa milisegundos desde el 1 de enero de 1970.
Etiqueta::ALGORITMO
Versión : 1, 2, 3, 4
¿ Repetible ? No
Especifica el algoritmo criptográfico con el que se utiliza la clave.
Los valores posibles se definen mediante la siguiente enumeración:
Keymaster 3
enum class Algorithm : uint32_t {
RSA = 1,
EC = 3,
AES = 32,
HMAC = 128,
};
Keymaster 2 y anteriores
typedef enum {
KM_ALGORITHM_RSA = 1,
KM_ALGORITHM_EC = 3,
KM_ALGORITHM_AES = 32,
KM_ALGORITHM_HMAC = 128,
} keymaster_algorithm_t;
Etiqueta::TODAS_APLICACIONES
Versión : 1, 2, 3, 4
¿ Repetible ? No
Reservado para uso futuro.
Etiqueta::ALLOW_WHILE_ON_BODY
Versión : 2, 3, 4
¿ Repetible ? No
Esta etiqueta solo se aplica a dispositivos Android Wear con sensores corporales. En este punto, no se espera que ningún TEE pueda proporcionar acceso seguro a un sensor corporal, o que los sensores corporales sean muy seguros, por lo que se espera que sea una característica puramente impuesta por software.
Etiqueta::TODOS_USUARIOS
Versión : 3, 4
¿ Repetible ? No
Reservado para uso futuro.
Etiqueta::APLICACIÓN_DATOS
Versión : 1, 2, 3, 4
¿ Repetible ? No
Cuando se proporciona para generateKey o importKey , esta etiqueta especifica los datos necesarios durante todos los usos de la clave. En particular, las llamadas a exportKey y getKeyCharacteristics deben proporcionar el mismo valor al parámetro clientId , y las llamadas a comenzar deben proporcionar esta etiqueta y los mismos datos asociados como parte del conjunto inParams . Si no se proporcionan los datos correctos, la función devuelve ErrorCode::INVALID_KEY_BLOB .
El contenido de esta etiqueta está vinculado criptográficamente a la clave, lo que significa que no debe ser posible para un adversario que tiene acceso a todos los secretos del mundo seguro pero no tiene acceso al contenido de la etiqueta descifrar la clave sin fuerza bruta sobre la etiqueta. contenido, que las aplicaciones pueden evitar especificando contenido de entropía suficientemente alta.
El valor es un blob, una matriz de bytes de longitud arbitraria.
Etiqueta::APLICACIÓN_ID
Versión : 1, 2, 3, 4
¿ Repetible ? No
Cuando se proporciona para generateKey o importKey , esta etiqueta especifica los datos necesarios durante todos los usos de la clave. En particular, las llamadas a exportKey y getKeyCharacteristics deben proporcionar el mismo valor en el parámetro clientId , y las llamadas a comenzar deben proporcionar esta etiqueta y los mismos datos asociados como parte del conjunto inParams . Si no se proporcionan los datos correctos, la función devuelve ErrorCode::INVALID_KEY_BLOB .
El contenido de esta etiqueta está vinculado criptográficamente a la clave, lo que significa que un adversario que puede acceder a todos los secretos del mundo seguro (pero no tiene acceso al contenido de la etiqueta) no puede descifrar la clave (sin fuerza bruta al contenido de la etiqueta). ).
El valor es un blob, una matriz de bytes de longitud arbitraria.
Etiqueta::ASOCIADOS_DATOS
Versión : 1, 2, 3, 4
¿ Repetible ? No
Proporciona "datos asociados" para el cifrado o descifrado AES-GCM. Esta etiqueta se proporciona para actualizar y especifica datos que no están cifrados/descifrados, pero que se utilizan para calcular la etiqueta GCM.
El valor es un blob, una matriz de bytes de longitud arbitraria.
Etiqueta::ATTESTATION_APPLICATION_ID
Versión : 3, 4
¿ Repetible ? No
Se utiliza para identificar el conjunto de posibles solicitudes de las cuales se ha iniciado una atestación de clave.
El valor es un blob, una matriz de bytes de longitud arbitraria.
Etiqueta::ATTESTATION_CHALLENGE
Versión : 3, 4
¿ Repetible ? No
Se utiliza para proporcionar impugnación en la certificación.
El valor es un blob, una matriz de bytes de longitud arbitraria.
Etiqueta::ATTESTATION_ID_BRAND
Versión : 3, 4
¿ Repetible ? No
Proporciona el nombre de la marca del dispositivo, según lo devuelto por Build.BRAND en Android. Este campo se configura solo cuando se solicita la certificación de los identificadores del dispositivo.
Si el dispositivo no admite la certificación de ID (o se llamó anteriormente destroyAttestationIds() y el dispositivo ya no puede certificar sus ID), cualquier solicitud de certificación de clave que incluya esta etiqueta falla con ErrorCode::CANNOT_ATTEST_IDS .
El valor es un blob, una matriz de bytes de longitud arbitraria.
Etiqueta::ATTESTATION_ID_DEVICE
Versión : 3, 4
¿ Repetible ? No
Proporciona el nombre del dispositivo, tal como lo devuelve Build.DEVICE en Android. Este campo se configura solo cuando se solicita la certificación de los identificadores del dispositivo.
Si el dispositivo no admite la certificación de ID (o se llamó anteriormente destroyAttestationIds() y el dispositivo ya no puede certificar sus ID), cualquier solicitud de certificación de clave que incluya esta etiqueta falla con ErrorCode::CANNOT_ATTEST_IDS .
El valor es un blob, una matriz de bytes de longitud arbitraria.
Etiqueta::ATTESTATION_ID_IMEI
Versión : 3, 4
¿ Repetible ? Sí
Proporciona los IMEI de todas las radios del dispositivo. Este campo se configura solo cuando se solicita la certificación de los identificadores del dispositivo.
Si el dispositivo no admite la certificación de ID (o se llamó anteriormente destroyAttestationIds() y el dispositivo ya no puede certificar sus ID), cualquier solicitud de certificación de clave que incluya esta etiqueta falla con ErrorCode::CANNOT_ATTEST_IDS .
El valor es un blob, una matriz de bytes de longitud arbitraria.
Etiqueta::ATTESTATION_ID_MANUFACTURER
Versión : 3, 4
¿ Repetible ? No
Proporciona el nombre del fabricante del dispositivo, según lo devuelto por Build.MANUFACTURER en Android. Este campo se configura solo cuando se solicita la certificación de los identificadores del dispositivo.
Si el dispositivo no admite la certificación de ID (o se llamó anteriormente destroyAttestationIds() y el dispositivo ya no puede certificar sus ID), cualquier solicitud de certificación de clave que incluya esta etiqueta falla con ErrorCode::CANNOT_ATTEST_IDS .
El valor es un blob, una matriz de bytes de longitud arbitraria.
Etiqueta::ATTESTATION_ID_MEID
Versión : 3, 4
¿ Repetible ? Sí
Proporciona los MEID para todas las radios del dispositivo. Este campo solo se configurará cuando se solicite la certificación de los identificadores del dispositivo.
Si el dispositivo no admite la certificación de ID (o se llamó anteriormente destroyAttestationIds() y el dispositivo ya no puede certificar sus ID), cualquier solicitud de certificación de clave que incluya esta etiqueta falla con ErrorCode::CANNOT_ATTEST_IDS .
El valor es un blob, una matriz de bytes de longitud arbitraria.
Etiqueta::ATTESTATION_ID_MODEL
Versión : 3, 4
¿ Repetible ? No
Proporciona el nombre del modelo del dispositivo, según lo devuelto por Build.MODEL en Android. Este campo se configura solo cuando se solicita la certificación de los identificadores del dispositivo.
Si el dispositivo no admite la certificación de ID (o se llamó anteriormente destroyAttestationIds() y el dispositivo ya no puede certificar sus ID), cualquier solicitud de certificación de clave que incluya esta etiqueta falla con ErrorCode::CANNOT_ATTEST_IDS .
El valor es un blob, una matriz de bytes de longitud arbitraria.
Etiqueta::ATTESTATION_ID_PRODUCT
Versión : 3, 4
¿ Repetible ? No
Proporciona el nombre del producto del dispositivo, tal como lo devuelve Build.PRODUCT en Android. Este campo se configura solo cuando se solicita la certificación de los identificadores del dispositivo.
Si el dispositivo no admite la certificación de ID (o se llamó anteriormente destroyAttestationIds() y el dispositivo ya no puede certificar sus ID), cualquier solicitud de certificación de clave que incluya esta etiqueta falla con ErrorCode::CANNOT_ATTEST_IDS .
El valor es un blob, una matriz de bytes de longitud arbitraria.
Etiqueta::ATTESTATION_ID_SERIAL
Versión : 3, 4
¿ Repetible ? No
Proporciona el número de serie del dispositivo. Este campo se configura solo cuando se solicita la certificación de los identificadores del dispositivo.
Si el dispositivo no admite la certificación de ID (o se llamó anteriormente destroyAttestationIds() y el dispositivo ya no puede certificar sus ID), cualquier solicitud de certificación de clave que incluya esta etiqueta falla con ErrorCode::CANNOT_ATTEST_IDS .
El valor es un blob, una matriz de bytes de longitud arbitraria.
Etiqueta::AUTH_TIMEOUT
Versión : 1, 2, 3, 4
¿ Repetible ? No
Especifica el tiempo en segundos durante el cual se autoriza el uso de la clave, después de la autenticación. Si Tag::USER_SECURE_ID está presente y esta etiqueta no, entonces la clave necesita autenticación para cada uso (consulte inicio para obtener detalles del flujo de autenticación por operación).
El valor es un entero de 32 bits que especifica el tiempo en segundos después de una autenticación exitosa del usuario especificado por Tag::USER_SECURE_ID con el método de autenticación especificado por Tag::USER_AUTH_TYPE en el que se puede usar la clave.
Etiqueta::AUTH_TOKEN
Versión : 1, 2, 3, 4
¿ Repetible ? No
Proporciona un token de autenticación para comenzar , actualizar o finalizar , para demostrar la autenticación del usuario para una operación clave que lo requiere (la clave tiene Tag::USER_SECURE_ID ).
El valor es un blob que contiene una estructura hw_auth_token_t .
Etiqueta::BLOB_USAGE_REQUIREMENTS
Versión : 1, 2, 3, 4
¿ Repetible ? No
Especifica las condiciones ambientales del sistema necesarias para que se utilice la clave generada.
Los valores posibles se definen mediante la siguiente enumeración:
Keymaster 3
enum class KeyBlobUsageRequirements : uint32_t {
STANDALONE = 0,
REQUIRES_FILE_SYSTEM = 1,
};
Keymaster 2 y anteriores
typedef enum {
KM_BLOB_STANDALONE = 0,
KM_BLOB_REQUIRES_FILE_SYSTEM = 1,
} keymaster_key_blob_usage_requirements_t;
Esta etiqueta se puede especificar durante la generación de claves para exigir que la clave se pueda utilizar en la condición especificada. Debe devolverse con las características clave de generateKey y getKeyCharacteristics . Si el autor de la llamada especifica Tag::BLOB_USAGE_REQUIREMENTS con el valor KeyBlobUsageRequirements::STANDALONE el trustlet devuelve un blob de claves que se puede usar sin compatibilidad con el sistema de archivos. Esto es fundamental para dispositivos con discos cifrados, donde el sistema de archivos puede no estar disponible hasta que se utilice una clave Keymaster para descifrar el disco.
Etiqueta::BLOCK_MODE
Versión : 1, 2, 3, 4
¿ Repetible ? Sí
Especifica los modos de cifrado de bloque con los que se puede utilizar la clave. Esta etiqueta sólo es relevante para las claves AES.
Los valores posibles se definen mediante la siguiente enumeración:
Keymaster 3
enum class BlockMode : uint32_t {
ECB = 1,
CBC = 2,
CTR = 3,
GCM = 32,
};
Keymaster 2 y anteriores
typedef enum {
KM_MODE_ECB = 1,
KM_MODE_CBC = 2,
KM_MODE_CTR = 3,
KM_MODE_GCM = 32,
} keymaster_block_mode_t;
Esta etiqueta es repetible y, para las operaciones de clave AES, especifique un modo en el argumento additionalParams de comenzar . Si el modo especificado no está en los modos asociados con la clave, la operación falla con ErrorCode::INCOMPATIBLE_BLOCK_MODE .
Etiqueta::BOOT_PATCHLEVEL
Versión : 4
Tag::BOOT_PATCHLEVEL especifica el nivel de parche de seguridad de la imagen de arranque (kernel) con el que se puede utilizar la clave. Esta etiqueta nunca se envía al TA maestro de llaves, pero el TA la agrega a la lista de autorización impuesta por hardware. Cualquier intento de utilizar una clave con un valor Tag::BOOT_PATCHLEVEL diferente del nivel de parche del sistema actualmente en ejecución hace que begin() , getKeyCharacteristics() o exportKey() devuelvan ErrorCode::KEY_REQUIRES_UPGRADE . Consulte upgradeKey() para obtener más detalles.
El valor de la etiqueta es un número entero con el formato AAAAMMDD, donde AAAA es el año de cuatro dígitos de la última actualización, MM es el mes de dos dígitos y DD es el día de dos dígitos de la última actualización. Por ejemplo, para una clave generada en un dispositivo Android actualizado por última vez el 5 de junio de 2018, el valor sería 20180605. Si no se conoce el día, se puede sustituir por 00.
Durante cada arranque, el gestor de arranque debe proporcionar el nivel de parche de la imagen de arranque al entorno seguro (el mecanismo está definido por la implementación).
Debe aplicarse mediante hardware.
Etiqueta::BOOTLOADER_ONLY
Versión : 1, 2, 3, 4
¿ Repetible ? No
Especifica que solo el gestor de arranque puede usar la clave.
Esta etiqueta es booleana, por lo que los valores posibles son verdadero (si la etiqueta está presente) y falso (si la etiqueta no está presente).
Cualquier intento de utilizar una clave con Tag::BOOTLOADER_ONLY desde el sistema Android falla con ErrorCode::INVALID_KEY_BLOB .
Etiqueta::CALLER_NONCE
Versión : 1, 2, 3, 4
¿ Repetible ? No
Especifica que la persona que llama puede proporcionar un nonce para operaciones que no lo requieren.
Esta etiqueta es booleana, por lo que los valores posibles son verdadero (si la etiqueta está presente) y falso (si la etiqueta no está presente).
Esta etiqueta se usa solo para claves AES y solo es relevante para los modos de bloque CBC, CTR y GCM. Si la etiqueta no está presente, las implementaciones deben rechazar cualquier operación que proporcione Tag::NONCE para comenzar con ErrorCode::CALLER_NONCE_PROHIBITED .
Etiqueta::CREATION_DATETIME
Versión : 1, 2, 3, 4
¿ Repetible ? No
Especifica la fecha y hora en que se creó la clave, en milisegundos desde el 1 de enero de 1970. Esta etiqueta es opcional y sólo informativa.
Etiqueta::DIGESTO
Versión : 1, 2, 3, 4
¿ Repetible ? Sí
Especifica los algoritmos de resumen que se pueden utilizar con la clave para realizar operaciones de firma y verificación. Esta etiqueta es relevante para las claves RSA, ECDSA y HMAC.
Los valores posibles se definen mediante la siguiente enumeración:
Keymaster 3
enum class Digest : uint32_t {
NONE = 0,
MD5 = 1,
SHA1 = 2,
SHA_2_224 = 3,
SHA_2_256 = 4,
SHA_2_384 = 5,
SHA_2_512 = 6,
};
Keymaster 2 y anteriores
typedef enum {
KM_DIGEST_NONE = 0,
KM_DIGEST_MD5 = 1,
KM_DIGEST_SHA1 = 2,
KM_DIGEST_SHA_2_224 = 3,
KM_DIGEST_SHA_2_256 = 4,
KM_DIGEST_SHA_2_384 = 5,
KM_DIGEST_SHA_2_512 = 6,
}
keymaster_digest_t;
Esta etiqueta es repetible. Para operaciones de firma y verificación, especifique un resumen en el argumento additionalParams de comenzar . Si el resumen especificado no está en los resúmenes asociados con la clave, la operación falla con ErrorCode::INCOMPATIBLE_DIGEST .
Etiqueta::EC_CURVE
Versión : 2, 3, 4
¿ Repetible ? No
En Keymaster 1, la curva utilizada para las claves EC se adivinó a partir del tamaño de clave especificado. Para mejorar la flexibilidad en el futuro, Keymaster 2 introdujo una forma explícita de especificar curvas. Las solicitudes de generación de claves EC pueden tener Tag::EC_CURVE , Tag::KEY_SIZE o ambos.
Los valores posibles se definen mediante la siguiente enumeración:
Keymaster 3
enum class EcCurve : uint32_t {
P_224 = 0,
P_256 = 1,
P_384 = 2,
P_521 = 3,
};
Keymaster 2 y anteriores
enum class EcCurve : uint32_t {
P_224 = 0,
P_256 = 1,
P_384 = 2,
P_521 = 3,
};
Si una solicitud de generación solo contiene Tag::KEY_SIZE , recurra a la lógica Keymaster 1 y elija la curva NIST adecuada.
Si la solicitud solo contiene Tag::EC_CURVE , utilice la curva especificada. Para Keymaster 3 y posteriores, las curvas se definen en EcCurve . Para Keymaster 2 y versiones anteriores, las curvas se definen en keymaster_ec_curve_t .
Si la solicitud contiene ambos, use la curva especificada por Tag::EC_CURVE y valide que el tamaño de clave especificado sea apropiado para esa curva. De lo contrario, devuelva ErrorCode::INVALID_ARGUMENT .
Etiqueta::INCLUDE_UNIQUE_ID
Versión : 2, 3, 4
¿ Repetible ? No
Esta etiqueta se especifica durante la generación de claves para indicar que un certificado de atestación para la clave generada debe contener una identificación única del dispositivo con alcance de aplicación y tiempo limitado, como se especifica en Tag::UNIQUE_ID .
Esta etiqueta es booleana, por lo que los valores posibles son verdadero (si la etiqueta está presente) y falso (si la etiqueta no está presente).
Etiqueta::KEY_SIZE
Versión : 1, 2, 3, 4
¿ Repetible ? No
Especifica el tamaño, en bits, de la clave, midiendo de la forma normal para el algoritmo de la clave. Por ejemplo, para claves RSA, Tag::KEY_SIZE especifica el tamaño del módulo público. Para claves AES, especifica la longitud del material de la clave secreta.
Etiqueta::MAC_LENGTH
Versión : 1, 2, 3, 4
¿ Repetible ? No
Proporciona la longitud solicitada de una etiqueta de autenticación MAC o GCM, en bits.
El valor es la longitud MAC en bits. Es un múltiplo de 8 y al menos tan grande como el valor de Tag::MIN_MAC_LENGTH asociado con la clave.
Etiqueta::MAX_USES_PER_BOOT
Versión : 1, 2, 3, 4
¿ Repetible ? No
Especifica la cantidad máxima de veces que se puede usar una clave entre reinicios del sistema. Este es otro mecanismo para limitar el uso de claves.
El valor es un entero de 32 bits que representa los usos por arranque.
Cuando se utiliza una clave con esta etiqueta en una operación, se debe incrementar un contador asociado a la clave durante la llamada de inicio . Después de que el contador de claves haya excedido este valor, todos los intentos posteriores de usar la clave fallarán con ErrorCode::MAX_OPS_EXCEEDED , hasta que se reinicie el dispositivo. Esto implica que un trustlet mantiene una tabla de contadores de uso para las claves con esta etiqueta. Debido a que la memoria de Keymaster suele ser limitada, esta tabla puede tener un tamaño máximo fijo y Keymaster puede fallar en operaciones que intentan usar claves con esta etiqueta cuando la tabla está llena. La mesa debe contener al menos 16 llaves. Si una operación falla porque la tabla está llena, Keymaster devuelve ErrorCode::TOO_MANY_OPERATIONS .
Etiqueta::MIN_MAC_LENGTH
Versión : 1, 2, 3, 4
¿ Repetible ? No
Esta etiqueta especifica la longitud mínima de MAC que se puede solicitar o verificar con esta clave para claves HMAC y claves AES que admiten el modo GCM.
Este valor es la longitud mínima de MAC, en bits. Es un múltiplo de 8. Para claves HMAC, el valor es al menos 64. Para claves GCM, el valor es al menos 96 y no más de 128.
Etiqueta::MIN_SECONDS_BETWEEN_OPS
Versión : 1, 2, 3, 4
¿ Repetible ? No
Especifica la cantidad mínima de tiempo que transcurre entre operaciones permitidas utilizando una clave. Esto se puede utilizar para limitar el uso de claves en contextos donde el uso ilimitado puede permitir ataques de fuerza bruta.
El valor es un entero de 32 bits que representa segundos entre operaciones permitidas.
Cuando se utiliza una clave con esta etiqueta en una operación, inicia un temporizador durante la finalización o cancelación de la llamada. Cualquier llamada para comenzar que se reciba antes de que el temporizador indique que ha transcurrido el intervalo especificado por Tag::MIN_SECONDS_BETWEEN_OPS falla con ErrorCode::KEY_RATE_LIMIT_EXCEEDED . Esto implica que un trustlet mantiene una tabla de contadores de uso para las claves con esta etiqueta. Debido a que la memoria de Keymaster suele ser limitada, esta tabla puede tener un tamaño máximo fijo y Keymaster puede fallar en operaciones que intentan usar claves con esta etiqueta cuando la tabla está llena. La tabla debe acomodar al menos 32 claves en uso y reutilizar agresivamente las ranuras de la tabla cuando expiren los intervalos de uso mínimo de las claves. Si una operación falla porque la tabla está llena, Keymaster devuelve ErrorCode::TOO_MANY_OPERATIONS .
Etiqueta::NO_AUTH_REQUIRED
Versión : 1, 2, 3, 4
¿ Repetible ? No
Especifica que no se requiere autenticación para utilizar esta clave. Esta etiqueta es mutuamente excluyente con Tag::USER_SECURE_ID .
Esta etiqueta es booleana, por lo que los valores posibles son verdadero (si la etiqueta está presente) y falso (si la etiqueta no está presente).
Etiqueta::NUNCA
Versión : 1, 2, 3, 4
¿ Repetible ? No
Proporciona o devuelve un nonce o vector de inicialización (IV) para el cifrado o descifrado AES GCM, CBC o CTR. Esta etiqueta se proporciona para comenzar durante las operaciones de cifrado y descifrado. Solo se proporciona para comenzar si la clave tiene Tag::CALLER_NONCE . Si no se proporciona, Keymaster generará aleatoriamente un nonce o IV apropiado y lo devolverá desde el principio.
El valor es un blob, una matriz de bytes de longitud arbitraria. Las longitudes permitidas dependen del modo: los nonces GCM tienen una longitud de 12 bytes; Los CBC y CTR IV tienen una longitud de 16 bytes.
Etiqueta::ORIGEN
Versión : 1, 2, 3, 4
¿ Repetible ? No
Especifica dónde se creó la clave, si se conoce. Esta etiqueta no se puede especificar durante la generación o importación de claves y el trustlet debe agregarla a las características clave.
Maestro de llaves 3 Los valores posibles se definen en android::hardware::keymaster::v3_0::KeyOrigin :
enum class KeyOrigin : uint32_t {
GENERATED = 0,
DERIVED = 1,
IMPORTED = 2,
UNKNOWN = 3,
};
Keymaster 2 y anteriores Los valores posibles están definidos en keymaster_origin_t :
typedef enum {
KM_ORIGIN_GENERATED = 0,
KM_ORIGIN_IMPORTED = 2,
KM_ORIGIN_UNKNOWN = 3,
} keymaster_key_origin_t
El significado completo del valor depende no solo del valor sino de si se encuentra en la lista de características impuestas por hardware o por software.
GENERATED indica que Keymaster generó la clave. Si está en la lista de hardware exigido, la clave se generó en un hardware seguro y está vinculada permanentemente al hardware. Si está en la lista impuesta por software, la clave se generó en SoftKeymaster y no está vinculada al hardware.
DERIVED indica que la clave se derivó dentro de Keymaster. Probablemente exista fuera del dispositivo.
IMPORTED indica que la clave se generó fuera de Keymaster y se importó a Keymaster. Si está en la lista de hardware obligatorio, está permanentemente vinculado al hardware, aunque pueden existir copias fuera del hardware seguro. Si está en la lista de aplicaciones de software, la clave se importó a SoftKeymaster y no está vinculada al hardware.
UNKNOWN sólo debería aparecer en la lista impuesta por hardware. Indica que la clave está vinculada al hardware, pero no se sabe si la clave se generó originalmente en hardware seguro o se importó. Esto solo ocurre cuando se utiliza hardware keymaster0 para emular los servicios keymaster1.
Etiqueta::ORIGINATION_EXPIRE_DATETIME
Versión : 1, 2, 3, 4
¿ Repetible ? No
Especifica la fecha y hora en que caduca la clave para fines de firma y cifrado. Después de este tiempo, cualquier intento de utilizar una clave con KeyPurpose::SIGN o KeyPurpose::ENCRYPT proporcionada para comenzar falla con ErrorCode::KEY_EXPIRED .
El valor es un entero de 64 bits que representa milisegundos desde el 1 de enero de 1970.
Etiqueta::OS_PATCHLEVEL
Versión : 2, 3, 4
¿ Repetible ? No
Esta etiqueta nunca se envía al TA maestro de llaves, pero el TA la agrega a la lista de autorización impuesta por hardware.
El valor de la etiqueta es un número entero con el formato AAAAMM, donde AAAA es el año de cuatro dígitos de la última actualización y MM es el mes de dos dígitos de la última actualización. Por ejemplo, para una clave generada en un dispositivo Android actualizado por última vez en diciembre de 2015, el valor sería 201512.
Las claves que tienen un nivel de parche diferente al nivel de parche actual no se pueden utilizar. Un intento de utilizar dicha clave hace que comenzar , getKeyCharacteristics o exportKey devuelvan ErrorCode::KEY_REQUIRES_UPGRADE . Consulte Enlace de versión para obtener más detalles.
Etiqueta::OS_VERSION
Versión : 2, 3, 4
¿ Repetible ? No
Esta etiqueta nunca se envía al TA maestro de llaves, pero el TA la agrega a la lista de autorización impuesta por hardware.
El valor de la etiqueta es un número entero con el formato MMmmss, donde MM es el número de versión principal, mm es el número de versión menor y ss es el número de versión secundaria. Por ejemplo, para una clave generada en la versión 4.0.3 de Android, el valor sería 040003.
Etiqueta::RELLENO
Versión : 1, 2, 3, 4
¿ Repetible ? Sí
Especifica los modos de relleno que se pueden utilizar con la clave. Esta etiqueta es relevante para las claves RSA y AES.
Los valores posibles se definen mediante la siguiente enumeración:
Keymaster 3
enum class PaddingMode : uint32_t {
NONE = 1,
RSA_OAEP = 2,
RSA_PSS = 3,
RSA_PKCS1_1_5_ENCRYPT = 4,
RSA_PKCS1_1_5_SIGN = 5,
PKCS7 = 64,
};
Keymaster 2 y anteriores
typedef enum {
KM_PAD_NONE = 1,
KM_PAD_RSA_OAEP = 2,
KM_PAD_RSA_PSS = 3,
KM_PAD_RSA_PKCS1_1_5_ENCRYPT = 4,
KM_PAD_RSA_PKCS1_1_5_SIGN = 5,
KM_PAD_PKCS7 = 64,
} keymaster_padding_t;
PaddingMode::RSA_OAEP y PaddingMode::RSA_PKCS1_1_5_ENCRYPT se usan solo para claves de cifrado/descifrado RSA y especifican el relleno OAEP RSA PKCS#1v2 y el relleno aleatorio RSA PKCS#1 v1.5, respectivamente. PaddingMode::RSA_PSS y PaddingMode::RSA_PKCS1_1_5_SIGN se usan solo para claves de firma/verificación RSA y especifican el relleno PSS RSA PKCS#1v2 y el relleno determinista RSA PKCS#1 v1.5, respectivamente.
PaddingMode::NONE se puede utilizar con claves RSA o AES. Para las claves AES, si PaddingMode::NONE se usa con el modo de bloque ECB o CBC y los datos que se van a cifrar o descifrar no son un múltiplo del tamaño del bloque AES en longitud, la llamada para finalizar falla con ErrorCode::INVALID_INPUT_LENGTH .
PaddingMode::PKCS7 solo se puede usar con claves AES y solo con los modos ECB y CBC.
Esta etiqueta es repetible. Se debe especificar un modo de relleno en la llamada para comenzar . Si el modo especificado no está autorizado para la clave, la operación falla con ErrorCode::INCOMPATIBLE_BLOCK_MODE .
Etiqueta::PROPÓSITO
Versión : 1, 2, 3, 4
¿ Repetible ? Sí
Especifica el conjunto de propósitos para los cuales se puede utilizar la clave.
Los valores posibles se definen mediante la siguiente enumeración:
Keymaster 3
enum class KeyPurpose : uint32_t {
ENCRYPT = 0,
DECRYPT = 1,
SIGN = 2,
VERIFY = 3,
DERIVE_KEY = 4, // since 3.0
WRAP_KEY = 5, // since 3.0
};
Keymaster 2 y anteriores
typedef enum {
KM_PURPOSE_ENCRYPT = 0,
KM_PURPOSE_DECRYPT = 1,
KM_PURPOSE_SIGN = 2,
KM_PURPOSE_VERIFY = 3,
} keymaster_purpose_t;
Esta etiqueta es repetible; Las claves se pueden generar con múltiples valores, aunque una operación tiene un solo propósito. Cuando se llama a la función de inicio para iniciar una operación, se especifica el propósito de la operación. Si la clave no autoriza el propósito especificado para la operación, la operación falla con ErrorCode::INCOMPATIBLE_PURPOSE .
Etiqueta::RESET_SINCE_ID_ROTATION
Versión : 3, 4
¿ Repetible ? No
Especifica si el dispositivo se ha restablecido a los valores de fábrica desde la última rotación de ID única. Se utiliza para la certificación de claves.
Esta etiqueta es booleana, por lo que los valores posibles son verdadero (si la etiqueta está presente) y falso (si la etiqueta no está presente).
Etiqueta::ROLLBACK_RESISTANT
Versión : 1, 2, 3, 4
¿ Repetible ? No
Indica que la clave es resistente a la reversión, lo que significa que cuando se elimina mediante deleteKey o deleteAllKeys , se garantiza que la clave se eliminará permanentemente y será inutilizable. Es posible que las claves sin esta etiqueta se eliminen y luego se restauren desde la copia de seguridad.
Esta etiqueta es booleana, por lo que los valores posibles son verdadero (si la etiqueta está presente) y falso (si la etiqueta no está presente).
Etiqueta::ROOT_OF_TRUST
Versión : 1, 2, 3, 4
¿ Repetible ? No
Especifica la raíz de confianza , la clave utilizada por el inicio verificado para validar el sistema operativo iniciado (si corresponde). Esta etiqueta nunca se proporciona ni se devuelve a Keymaster en las características clave.
Etiqueta::RSA_PUBLIC_EXPONENT
Versión : 1, 2, 3, 4
¿ Repetible ? No
Especifica el valor del exponente público para un par de claves RSA. Esta etiqueta es relevante solo para las claves RSA y necesaria para todas las claves RSA.
El valor es un entero sin signo de 64 bits que satisface los requisitos de un exponente público RSA. Este valor tiene que ser un número primo. Los Trustlets admiten el valor 2^16+1 y pueden admitir otros valores razonables, en particular el valor 3. Si no se especifica ningún exponente o si el exponente especificado no es compatible, la generación de claves falla con ErrorCode::INVALID_ARGUMENT .
Etiqueta::UNIQUE_ID
Versión : 3, 4
¿ Repetible ? No
Se utiliza para proporcionar una identificación única en la certificación.
El valor es un blob, una matriz de bytes de longitud arbitraria.
Etiqueta::USAGE_EXPIRE_DATETIME
Versión : 1, 2, 3, 4
¿ Repetible ? No
Especifica la fecha y hora en que caduca la clave para fines de verificación y descifrado. Después de este tiempo, cualquier intento de utilizar una clave con KeyPurpose::VERIFY o KeyPurpose::DECRYPT proporcionada para comenzar falla con ErrorCode::KEY_EXPIRED .
El valor es un entero de 64 bits que representa milisegundos desde el 1 de enero de 1970.
Etiqueta::USER_AUTH_TYPE
Versión : 1, 2, 3, 4
¿ Repetible ? No
Especifica los tipos de autenticadores de usuario que se pueden utilizar para autorizar esta clave. Cuando se solicita a Keymaster que realice una operación con una clave con esta etiqueta, recibe un token de autenticación y el campo authenticator_type del token debe coincidir con el valor de la etiqueta. Por ejemplo, (ntoh(token.authenticator_type) & auth_type_tag_value) != 0 , donde ntoh es una función que convierte enteros ordenados por la red en enteros ordenados por el host y auth_type_tag_value es el valor de esta etiqueta.
El valor es una máscara de bits entera de 32 bits de valores de la enumeración:
Keymaster 3
enum class HardwareAuthenticatorType : uint32_t {
NONE = 0u, // 0
PASSWORD = 1 << 0,
FINGERPRINT = 1 << 1,
ANY = UINT32_MAX,
};
Keymaster 2 y anteriores
typedef enum {
HW_AUTH_NONE = 0,
HW_AUTH_PASSWORD = 1 << 0,
HW_AUTH_FINGERPRINT = 1 << 1,
// Additional entries should be powers of 2.
HW_AUTH_ANY = UINT32_MAX,
} hw_authenticator_type_t;
Etiqueta::USER_SECURE_ID
Versión : 1, 2, 3, 4
¿ Repetible ? No
Especifica que una clave solo se puede utilizar bajo un estado de autenticación de usuario seguro particular. Esta etiqueta es mutuamente excluyente con Tag::NO_AUTH_REQUIRED .
El valor es un entero de 64 bits que especifica el valor del estado de la política de autenticación que debe estar presente en un token de autenticación (proporcionado para comenzar con Tag::AUTH_TOKEN ) para autorizar el uso de la clave. Cualquier llamada para comenzar con una clave con esta etiqueta que no proporciona un token de autenticación o que proporciona un token de autenticación sin un valor de estado de política coincidente falla.
Esta etiqueta es repetible. Si alguno de los valores proporcionados coincide con algún valor de estado de política en el token de autenticación, se autoriza el uso de la clave. De lo contrario, la operación falla con ErrorCode::KEY_USER_NOT_AUTHENTICATED .
Etiqueta::VENDOR_PATCHLEVEL
Versión : 4
Esta etiqueta especifica el nivel de parche de seguridad de la imagen del proveedor con el que se puede utilizar la clave. Esta etiqueta nunca se envía al TA maestro de llaves, pero el TA la agrega a la lista de autorización impuesta por hardware. Cualquier intento de utilizar una clave con un valor Tag::VENDOR_PATCHLEVEL diferente del nivel de parche del sistema actualmente en ejecución debe provocar que begin() , getKeyCharacteristics() o exportKey() devuelvan ErrorCode::KEY_REQUIRES_UPGRADE . Consulte upgradeKey() para obtener más detalles.
El valor de la etiqueta es un número entero con el formato AAAAMMDD, donde AAAA es el año de cuatro dígitos de la última actualización, MM es el mes de dos dígitos y DD es el día de dos dígitos de la última actualización. Por ejemplo, para una clave generada en un dispositivo Android actualizado por última vez el 5 de junio de 2018, el valor sería 20180605.
El HAL IKeymasterDevice debe leer el nivel de parche del proveedor actual de la propiedad del sistema ro.vendor.build.security_patch y entregarlo al entorno seguro cuando el HAL se carga por primera vez (el mecanismo está definido por la implementación). El entorno seguro no debe aceptar otro nivel de parche hasta después del siguiente inicio.
Debe aplicarse mediante hardware.