Etiquetas de autorización de Keymaster

Esta página proporciona detalles para ayudar a los implementadores de Keymaster HAL. Cubre cada etiqueta en la HAL, en qué versión Keymaster está disponible esa etiqueta y si la etiqueta es repetible. Salvo que se indique lo contrario en las descripciones de las etiquetas, todas las etiquetas siguientes se utilizan durante la generación de claves para especificar 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 de Keymaster .

Etiqueta::ACTIVE_DATETIME

Versión : 1, 2, 3, 4

repetible ? No

Especifica la fecha y la hora en que la clave se activa. Antes de este momento, cualquier intento de usar 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:

enum class Algorithm : uint32_t {
    RSA = 1,
    EC = 3,
    AES = 32,
    HMAC = 128,
};

typedef enum {
    KM_ALGORITHM_RSA = 1,
    KM_ALGORITHM_EC = 3,
    KM_ALGORITHM_AES = 32,
    KM_ALGORITHM_HMAC = 128,
} keymaster_algorithm_t;

Etiqueta::TODAS LAS APLICACIONES

Versión : 1, 2, 3, 4

repetible ? No

Reservado para utilización futura.

Etiqueta::ALLOW_WHILE_ON_BODY

Versión : 2, 3, 4

repetible ? No

Esta etiqueta solo se aplica a los 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 esta sea una característica puramente aplicada por software.

Etiqueta::TODOS LOS USUARIOS

Versión : 3, 4

repetible ? No

Reservado para utilización futura.

Etiqueta::APLICACIÓN_DATOS

Versión : 1, 2, 3, 4

repetible ? No

Cuando se proporciona a generateKey o importKey , esta etiqueta especifica los datos que son 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 begin 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 que un adversario que tenga acceso a todos los secretos del mundo seguro, pero que no tenga acceso al contenido de la etiqueta, descifre la clave sin fuerza bruta en la etiqueta. contenido, que las aplicaciones pueden evitar especificando un contenido de entropía lo suficientemente alto.

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 a generateKey o importKey , esta etiqueta especifica los datos que son 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 begin 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 que no tiene acceso al contenido de la etiqueta, no puede descifrar la clave (sin aplicar fuerza bruta al contenido de la etiqueta). ).

El valor es un blob, una matriz de bytes de longitud arbitraria.

Etiqueta::DATOS_ASOCIADOS

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 ni 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 aplicaciones de las que 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 un desafío en la atestació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, tal como lo devuelve Build.BRAND en Android. Este campo se establece solo cuando se solicita la certificación de los identificadores del dispositivo.

Si el dispositivo no admite la atestación de ID (o se llamó previamente a destroyAttestationIds() y el dispositivo ya no puede atestar sus ID), cualquier solicitud de atestació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 del dispositivo, tal como lo devuelve Build.DEVICE en Android. Este campo se establece solo cuando se solicita la certificación de los identificadores del dispositivo.

Si el dispositivo no admite la atestación de ID (o se llamó previamente a destroyAttestationIds() y el dispositivo ya no puede atestar sus ID), cualquier solicitud de atestació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 establece solo cuando se solicita la certificación de los identificadores del dispositivo.

Si el dispositivo no admite la atestación de ID (o se llamó previamente a destroyAttestationIds() y el dispositivo ya no puede atestar sus ID), cualquier solicitud de atestació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, tal como lo devuelve Build.MANUFACTURER en Android. Este campo se establece solo cuando se solicita la certificación de los identificadores del dispositivo.

Si el dispositivo no admite la atestación de ID (o se llamó previamente a destroyAttestationIds() y el dispositivo ya no puede atestar sus ID), cualquier solicitud de atestació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 establecerá cuando se solicite la atestación de los identificadores del dispositivo.

Si el dispositivo no admite la atestación de ID (o se llamó previamente a destroyAttestationIds() y el dispositivo ya no puede atestar sus ID), cualquier solicitud de atestació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, tal como lo devuelve Build.MODEL en Android. Este campo se establece solo cuando se solicita la certificación de los identificadores del dispositivo.

Si el dispositivo no admite la atestación de ID (o se llamó previamente a destroyAttestationIds() y el dispositivo ya no puede atestar sus ID), cualquier solicitud de atestació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 establece solo cuando se solicita la certificación de los identificadores del dispositivo.

Si el dispositivo no admite la atestación de ID (o se llamó previamente a destroyAttestationIds() y el dispositivo ya no puede atestar sus ID), cualquier solicitud de atestació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 establece solo cuando se solicita la certificación de los identificadores del dispositivo.

Si el dispositivo no admite la atestación de ID (o se llamó previamente a destroyAttestationIds() y el dispositivo ya no puede atestar sus ID), cualquier solicitud de atestació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 (vea el comienzo 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 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 probar la autenticación del usuario para una operación clave que lo requiera (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 de entorno del sistema necesarias para que se utilice la clave generada.

Los valores posibles se definen mediante la siguiente enumeración:

enum class KeyBlobUsageRequirements : uint32_t {
    STANDALONE = 0,
    REQUIRES_FILE_SYSTEM = 1,
};

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 la persona que llama 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 los dispositivos con discos cifrados, donde el sistema de archivos puede no estar disponible hasta que se use una clave Keymaster para descifrar el disco.

Etiqueta::BLOCK_MODE

Versión : 1, 2, 3, 4

repetible ? Sí

Especifica los modos de cifrado de bloques con los que se puede usar la clave. Esta etiqueta solo es relevante para las claves AES.

Los valores posibles se definen mediante la siguiente enumeración:

enum class BlockMode : uint32_t {
    ECB = 1,
    CBC = 2,
    CTR = 3,
    GCM = 32,
};

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 tecla AES, especifique un modo en el argumento additionalParams de begin . 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 usar la clave. Esta etiqueta nunca se envía al maestro de claves TA, pero el TA la agrega a la lista de autorización aplicada por hardware. Cualquier intento de usar 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 . Ver upgradeKey() para más detalles.

El valor de la etiqueta es un número entero de la forma 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 que se actualizó 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 cargador 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 ser forzado por hardware.

Etiqueta::BOOTLOADER_ONLY

Versión : 1, 2, 3, 4

repetible ? No

Especifica que solo el cargador de arranque puede usar la clave.

Esta etiqueta es booleana, por lo que los valores posibles son verdaderos (si la etiqueta está presente) y falsos (si la etiqueta no está presente).

Cualquier intento de usar una clave con Tag::BOOTLOADER_ONLY del 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 verdaderos (si la etiqueta está presente) y falsos (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 la hora en que se creó la clave, en milisegundos desde el 1 de enero de 1970. Esta etiqueta es opcional y solo informativa.

Etiqueta::DIGESTO

Versión : 1, 2, 3, 4

repetible ? Sí

Especifica los algoritmos de resumen que se pueden usar 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:

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,
};

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 las operaciones de firma y verificación, especifique un resumen en el argumento additionalParams de begin . 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:

enum class EcCurve : uint32_t {
    P_224 = 0,
    P_256 = 1,
    P_384 = 2,
    P_521 = 3,
};

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 , use la curva especificada. Para Keymaster 3 y versiones 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. Si no, devuelve 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 ID única de dispositivo limitada en el tiempo y en el ámbito de la aplicación, como se especifica en Tag::UNIQUE_ID .

Esta etiqueta es booleana, por lo que los valores posibles son verdaderos (si la etiqueta está presente) y falsos (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 habitual para el algoritmo de la clave. Por ejemplo, para claves RSA, Tag::KEY_SIZE especifica el tamaño del módulo público. Para las 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 el número máximo 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 número entero de 32 bits que representa los usos por arranque.

Cuando se utiliza una tecla con esta etiqueta en una operación, se debe incrementar un contador asociado a la tecla durante la llamada de inicio . Una vez que el contador de claves ha excedido este valor, todos los intentos posteriores de usar la clave fallan con ErrorCode::MAX_OPS_EXCEEDED , hasta que se reinicia el dispositivo. Esto implica que un trustlet mantiene una tabla de contadores de uso para claves con esta etiqueta. Debido a que la memoria de Keymaster a menudo es limitada, esta tabla puede tener un tamaño máximo fijo y Keymaster puede fallar en las operaciones que intentan usar claves con esta etiqueta cuando la tabla está llena. La mesa debe acomodar 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 las operaciones permitidas usando una clave. Esto se puede usar para limitar la tasa de 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 tecla con esta etiqueta en una operación, se inicia un temporizador durante la finalización o cancelación de la llamada. Cualquier llamada para comenzar que se recibe 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 claves con esta etiqueta. Debido a que la memoria de Keymaster a menudo es limitada, esta tabla puede tener un tamaño máximo fijo y Keymaster puede fallar en las operaciones que intentan usar claves con esta etiqueta cuando la tabla está llena. La mesa debe acomodar al menos 32 claves en uso y reutilizar agresivamente los espacios de la mesa cuando expiren los intervalos de uso mínimo de clave. 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 usar esta clave. Esta etiqueta es mutuamente excluyente con Tag::USER_SECURE_ID .

Esta etiqueta es booleana, por lo que los valores posibles son verdaderos (si la etiqueta está presente) y falsos (si la etiqueta no está presente).

Etiqueta::NONCE

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. Es posible que esta etiqueta no se especifique durante la generación o importación de claves, y el trustlet debe agregarla a las características clave.

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,
};

Los valores posibles se definen 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 también de si se encuentra en la lista de características aplicadas por hardware o por software.

GENERATED indica que Keymaster generó la clave. Si está en la lista forzada por hardware, la clave se generó en un hardware seguro y está vinculada permanentemente al hardware. Si está en la lista de software forzado, la clave se generó en SoftKeymaster y no está vinculada al hardware.

DERIVED indica que la clave se derivó dentro de Keymaster. Es probable que exista fuera del dispositivo.

IMPORTED indica que la clave se generó fuera de Keymaster y se importó a Keymaster. Si está en la lista forzada por hardware, está vinculado permanentemente al hardware, aunque pueden existir copias fuera del hardware seguro. Si está en la lista de cumplimiento de software, la clave se importó a SoftKeymaster y no está vinculada al hardware.

UNKNOWN solo debe aparecer en la lista de dispositivos forzados por hardware. Indica que la clave está vinculada al hardware, pero no se sabe si la clave se generó originalmente en un hardware seguro o si se importó. Esto solo ocurre cuando el hardware keymaster0 se utiliza para emular los servicios keymaster1.

Etiqueta::ORIGINATION_EXPIRE_DATETIME

Versión : 1, 2, 3, 4

repetible ? No

Especifica la fecha y la hora en que caduca la clave para fines de firma y cifrado. Después de este tiempo, cualquier intento de usar 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 maestro de claves TA, pero el TA la agrega a la lista de autorización aplicada por hardware.

El valor de la etiqueta es un número entero de la forma 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 usar. Un intento de usar una clave de este tipo hace que begin , getKeyCharacteristics o exportKey devuelvan ErrorCode::KEY_REQUIRES_UPGRADE . Consulte Vinculación de versiones para obtener más detalles.

Etiqueta::OS_VERSION

Versión : 2, 3, 4

repetible ? No

Esta etiqueta nunca se envía al maestro de claves TA, pero el TA la agrega a la lista de autorización aplicada por hardware.

El valor de la etiqueta es un número entero de la forma MMmmss, donde MM es el número de versión principal, mm es el número de versión secundaria y ss es el número de versión secundaria. Por ejemplo, para una clave generada en la versión de Android 4.0.3, el valor sería 040003.

Etiqueta::RELLENO

Versión : 1, 2, 3, 4

repetible ? Sí

Especifica los modos de relleno que se pueden usar con la clave. Esta etiqueta es relevante para las claves RSA y AES.

Los valores posibles se definen mediante la siguiente enumeración:

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,
};

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 RSA PKCS#1v2 OAEP y el relleno aleatorio RSA PKCS#1 v1.5, respectivamente. PaddingMode::RSA_PSS y PaddingMode::RSA_PKCS1_1_5_SIGN se usan solo para las claves de firma/verificación de RSA y especifican el relleno RSA PKCS#1v2 PSS y el relleno determinista RSA PKCS#1 v1.5, respectivamente.

PaddingMode::NONE se puede usar 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 tienen una longitud múltiplo del tamaño del bloque AES, 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 fines para los que se puede utilizar la clave.

Los valores posibles se definen mediante la siguiente enumeración:

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
};

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 el propósito especificado para la operación no está autorizado por la clave, la operación falla con ErrorCode::INCOMPATIBLE_PURPOSE .

Etiqueta::RESET_SINCE_ID_ROTATION

Versión : 3, 4

repetible ? No

Especifica si el dispositivo se restableció de fábrica desde la última rotación de ID única. Se utiliza para la atestación de clave.

Esta etiqueta es booleana, por lo que los valores posibles son verdaderos (si la etiqueta está presente) y falsos (si la etiqueta no está presente).

Etiqueta::ROLLBACK_RESISTENTE

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á de forma permanente y quedará 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 verdaderos (si la etiqueta está presente) y falsos (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 desde 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 solo es relevante para las claves RSA y es necesaria para todas las claves RSA.

El valor es un entero sin signo de 64 bits que cumple 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 atestación.

El valor es un blob, una matriz de bytes de longitud arbitraria.

Etiqueta::USO_EXPIRE_DATETIME

Versión : 1, 2, 3, 4

repetible ? No

Especifica la fecha y la hora en que caduca la clave con fines de verificación y descifrado. Después de este tiempo, cualquier intento de usar 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 usar 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 red en enteros ordenados por host y auth_type_tag_value es el valor de esta etiqueta.

El valor es una máscara de bits de entero de 32 bits de valores de la enumeración:

enum class HardwareAuthenticatorType : uint32_t {
    NONE = 0u, // 0
    PASSWORD = 1 << 0,
    FINGERPRINT = 1 << 1,
    ANY = UINT32_MAX,
};

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 usar en un estado de autenticación de usuario seguro en 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 (que comienza con Tag::AUTH_TOKEN ) para autorizar el uso de la clave. Cualquier llamada para comenzar con una clave con esta etiqueta que no proporcione un token de autenticación, o proporcione 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 cualquier valor de estado de política en el token de autenticación, la clave está autorizada para su uso. 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 usar la clave. Esta etiqueta nunca se envía al maestro de claves TA, pero el TA la agrega a la lista de autorización aplicada por hardware. Cualquier intento de usar una clave con un valor Tag::VENDOR_PATCHLEVEL diferente del nivel de parche del sistema que se está ejecutando actualmente debe hacer que begin() , getKeyCharacteristics() o exportKey() devuelvan ErrorCode::KEY_REQUIRES_UPGRADE . Ver upgradeKey() para más detalles.

El valor de la etiqueta es un número entero de la forma 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.

La HAL de 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 la 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 arranque.

Debe ser forzado por hardware.