Esta página fornece detalhes para auxiliar os implementadores de HALs Keymaster. Ele cobre cada tag no HAL, em qual versão do Keymaster essa tag está disponível e se a tag é repetível. Exceto conforme indicado nas descrições das tags, todas as tags abaixo são usadas durante a geração de chaves para especificar características principais.
Para Keymaster 4, as tags são definidas em platform/hardware/interfaces/keymaster/ keymaster-version /types.hal , como 3.0/types.hal para Keymaster 3 e 4.0/types.hal para Keymaster 4. Para Keymaster 2 e anteriores, tags são definidas em platform/hardware/libhardware/include/hardware/keymaster_defs.h .
Para funções, consulte a página Funções do Keymaster .
Etiqueta::ACTIVE_DATETIME
Versão : 1, 2, 3, 4
Repetivel ? Não
Especifica a data e a hora em que a chave se torna ativa. Antes desse período, qualquer tentativa de usar a chave falhará com ErrorCode::KEY_NOT_YET_VALID .
O valor é um número inteiro de 64 bits que representa milissegundos desde 1º de janeiro de 1970.
Tag::ALGORITMO
Versão : 1, 2, 3, 4
Repetivel ? Não
Especifica o algoritmo criptográfico com o qual a chave é usada.
Os valores possíveis são definidos pela seguinte enumeração:
Keymaster 3
enum class Algorithm : uint32_t {
RSA = 1,
EC = 3,
AES = 32,
HMAC = 128,
};
Keymaster 2 e anteriores
typedef enum {
KM_ALGORITHM_RSA = 1,
KM_ALGORITHM_EC = 3,
KM_ALGORITHM_AES = 32,
KM_ALGORITHM_HMAC = 128,
} keymaster_algorithm_t;
Tag::TODOS_APLICATIVOS
Versão : 1, 2, 3, 4
Repetivel ? Não
Reservado para uso futuro.
Tag::ALLOW_WHILE_ON_BODY
Versão : 2, 3, 4
Repetivel ? Não
Esta tag é aplicável somente a dispositivos Android Wear com sensores no corpo. Neste ponto, não se espera que qualquer TEE seja capaz de fornecer acesso seguro a um sensor corporal, ou que os sensores corporais sejam muito seguros, portanto, espera-se que este seja um recurso puramente imposto por software.
Etiqueta::ALL_USERS
Versão : 3, 4
Repetivel ? Não
Reservado para uso futuro.
Etiqueta::APPLICATION_DATA
Versão : 1, 2, 3, 4
Repetivel ? Não
Quando fornecida para generateKey ou importKey , esta tag especifica os dados necessários durante todos os usos da chave. Em particular, as chamadas para exportKey e getKeyCharacteristics precisam fornecer o mesmo valor para o parâmetro clientId , e as chamadas para começar precisam fornecer essa tag e os mesmos dados associados como parte do conjunto inParams . Se os dados corretos não forem fornecidos, a função retornará ErrorCode::INVALID_KEY_BLOB .
O conteúdo desta tag está vinculado à chave criptograficamente , o que significa que não deve ser possível para um adversário que tenha acesso a todos os segredos do mundo seguro, mas não tenha acesso ao conteúdo da tag, descriptografar a chave sem forçar a tag. conteúdo, que os aplicativos podem evitar especificando conteúdo com entropia suficientemente alta.
O valor é um blob, uma matriz de bytes de comprimento arbitrário.
Etiqueta::APPLICATION_ID
Versão : 1, 2, 3, 4
Repetivel ? Não
Quando fornecida para generateKey ou importKey , esta tag especifica os dados necessários durante todos os usos da chave. Em particular, as chamadas para exportKey e getKeyCharacteristics precisam fornecer o mesmo valor no parâmetro clientId , e as chamadas para começar precisam fornecer essa tag e os mesmos dados associados como parte do conjunto inParams . Se os dados corretos não forem fornecidos, a função retornará ErrorCode::INVALID_KEY_BLOB .
O conteúdo desta tag está vinculado à chave criptograficamente , o que significa que um adversário que pode acessar todos os segredos do mundo seguro - mas não tem acesso ao conteúdo da tag - não pode descriptografar a chave (sem forçar brutalmente o conteúdo da tag ).
O valor é um blob, uma matriz de bytes de comprimento arbitrário.
Etiqueta::ASSOCIATED_DATA
Versão : 1, 2, 3, 4
Repetivel ? Não
Fornece "dados associados" para criptografia ou descriptografia AES-GCM. Esta tag é fornecida para atualizar e especifica dados que não são criptografados/descriptografados, mas são usados no cálculo da tag GCM.
O valor é um blob, uma matriz de bytes de comprimento arbitrário.
Etiqueta::ATTESTATION_APPLICATION_ID
Versão : 3, 4
Repetivel ? Não
Usado para identificar o conjunto de possíveis aplicações das quais se iniciou um atestado de chave.
O valor é um blob, uma matriz de bytes de comprimento arbitrário.
Tag::ATTESTATION_CHALLENGE
Versão : 3, 4
Repetivel ? Não
Usado para fornecer desafio no atestado.
O valor é um blob, uma matriz de bytes de comprimento arbitrário.
Etiqueta::ATTESTATION_ID_BRAND
Versão : 3, 4
Repetivel ? Não
Fornece o nome da marca do dispositivo, conforme retornado por Build.BRAND no Android. Este campo é definido somente ao solicitar atestado dos identificadores do dispositivo.
Se o dispositivo não suportar atestado de ID (ou destroyAttestationIds() foi chamado anteriormente e o dispositivo não puder mais atestar seus IDs), qualquer solicitação de atestado de chave que inclua essa tag falhará com ErrorCode::CANNOT_ATTEST_IDS .
O valor é um blob, uma matriz de bytes de comprimento arbitrário.
Tag::ATTESTATION_ID_DEVICE
Versão : 3, 4
Repetivel ? Não
Fornece o nome do dispositivo, conforme retornado por Build.DEVICE no Android. Este campo é definido somente ao solicitar atestado dos identificadores do dispositivo.
Se o dispositivo não suportar atestado de ID (ou destroyAttestationIds() foi chamado anteriormente e o dispositivo não puder mais atestar seus IDs), qualquer solicitação de atestado de chave que inclua essa tag falhará com ErrorCode::CANNOT_ATTEST_IDS .
O valor é um blob, uma matriz de bytes de comprimento arbitrário.
Etiqueta::ATTESTATION_ID_IMEI
Versão : 3, 4
Repetivel ? Sim
Fornece os IMEIs de todos os rádios do dispositivo. Este campo é definido somente ao solicitar atestado dos identificadores do dispositivo.
Se o dispositivo não suportar atestado de ID (ou destroyAttestationIds() foi chamado anteriormente e o dispositivo não puder mais atestar seus IDs), qualquer solicitação de atestado de chave que inclua essa tag falhará com ErrorCode::CANNOT_ATTEST_IDS .
O valor é um blob, uma matriz de bytes de comprimento arbitrário.
Etiqueta::ATTESTATION_ID_MANUFACTURER
Versão : 3, 4
Repetivel ? Não
Fornece o nome do fabricante do dispositivo, conforme retornado por Build.MANUFACTURER no Android. Este campo é definido somente ao solicitar atestado dos identificadores do dispositivo.
Se o dispositivo não suportar atestado de ID (ou destroyAttestationIds() foi chamado anteriormente e o dispositivo não puder mais atestar seus IDs), qualquer solicitação de atestado de chave que inclua essa tag falhará com ErrorCode::CANNOT_ATTEST_IDS .
O valor é um blob, uma matriz de bytes de comprimento arbitrário.
Etiqueta::ATTESTATION_ID_MEID
Versão : 3, 4
Repetivel ? Sim
Fornece os MEIDs para todos os rádios do dispositivo. Este campo só será definido quando for solicitado o atestado dos identificadores do dispositivo.
Se o dispositivo não suportar atestado de ID (ou destroyAttestationIds() foi chamado anteriormente e o dispositivo não puder mais atestar seus IDs), qualquer solicitação de atestado de chave que inclua essa tag falhará com ErrorCode::CANNOT_ATTEST_IDS .
O valor é um blob, uma matriz de bytes de comprimento arbitrário.
Etiqueta::ATTESTATION_ID_MODEL
Versão : 3, 4
Repetivel ? Não
Fornece o nome do modelo do dispositivo, conforme retornado por Build.MODEL no Android. Este campo é definido somente ao solicitar atestado dos identificadores do dispositivo.
Se o dispositivo não suportar atestado de ID (ou destroyAttestationIds() foi chamado anteriormente e o dispositivo não puder mais atestar seus IDs), qualquer solicitação de atestado de chave que inclua essa tag falhará com ErrorCode::CANNOT_ATTEST_IDS .
O valor é um blob, uma matriz de bytes de comprimento arbitrário.
Etiqueta::ATTESTATION_ID_PRODUCT
Versão : 3, 4
Repetivel ? Não
Fornece o nome do produto do dispositivo, conforme retornado por Build.PRODUCT no Android. Este campo é definido somente ao solicitar atestado dos identificadores do dispositivo.
Se o dispositivo não suportar atestado de ID (ou destroyAttestationIds() foi chamado anteriormente e o dispositivo não puder mais atestar seus IDs), qualquer solicitação de atestado de chave que inclua essa tag falhará com ErrorCode::CANNOT_ATTEST_IDS .
O valor é um blob, uma matriz de bytes de comprimento arbitrário.
Etiqueta::ATTESTATION_ID_SERIAL
Versão : 3, 4
Repetivel ? Não
Fornece o número de série do dispositivo. Este campo é definido somente ao solicitar atestado dos identificadores do dispositivo.
Se o dispositivo não suportar atestado de ID (ou destroyAttestationIds() foi chamado anteriormente e o dispositivo não puder mais atestar seus IDs), qualquer solicitação de atestado de chave que inclua essa tag falhará com ErrorCode::CANNOT_ATTEST_IDS .
O valor é um blob, uma matriz de bytes de comprimento arbitrário.
Etiqueta::AUTH_TIMEOUT
Versão : 1, 2, 3, 4
Repetivel ? Não
Especifica o tempo em segundos durante o qual a chave é autorizada para uso, após a autenticação. Se Tag::USER_SECURE_ID estiver presente e esta tag não estiver, então a chave precisará de autenticação para cada uso (consulte o início para obter detalhes do fluxo de autenticação por operação).
O valor é um número inteiro de 32 bits que especifica o tempo em segundos após uma autenticação bem-sucedida do usuário especificado por Tag::USER_SECURE_ID com o método de autenticação especificado por Tag::USER_AUTH_TYPE que a chave pode ser usada.
Etiqueta::AUTH_TOKEN
Versão : 1, 2, 3, 4
Repetivel ? Não
Fornece um token de autenticação para start , update ou finish , para provar a autenticação do usuário para uma operação de chave que a requer (a chave possui Tag::USER_SECURE_ID ).
O valor é um blob que contém uma estrutura hw_auth_token_t .
Etiqueta::BLOB_USAGE_REQUIREMENTS
Versão : 1, 2, 3, 4
Repetivel ? Não
Especifica as condições de ambiente do sistema necessárias para que a chave gerada seja usada.
Os valores possíveis são definidos pela seguinte enumeração:
Keymaster 3
enum class KeyBlobUsageRequirements : uint32_t {
STANDALONE = 0,
REQUIRES_FILE_SYSTEM = 1,
};
Keymaster 2 e anteriores
typedef enum {
KM_BLOB_STANDALONE = 0,
KM_BLOB_REQUIRES_FILE_SYSTEM = 1,
} keymaster_key_blob_usage_requirements_t;
Essa tag pode ser especificada durante a geração da chave para exigir que a chave seja utilizável na condição especificada. Ele precisa ser retornado com as principais características de generateKey e getKeyCharacteristics . Se o chamador especificar Tag::BLOB_USAGE_REQUIREMENTS com valor KeyBlobUsageRequirements::STANDALONE o trustlet retornará um blob de chave que pode ser usado sem suporte do sistema de arquivos. Isto é crítico para dispositivos com discos criptografados, onde o sistema de arquivos pode não estar disponível até que uma chave Keymaster seja usada para descriptografar o disco.
Etiqueta::BLOCK_MODE
Versão : 1, 2, 3, 4
Repetivel ? Sim
Especifica o(s) modo(s) de cifra de bloco com os quais a chave pode ser usada. Esta tag é relevante apenas para chaves AES.
Os valores possíveis são definidos pela seguinte enumeração:
Keymaster 3
enum class BlockMode : uint32_t {
ECB = 1,
CBC = 2,
CTR = 3,
GCM = 32,
};
Keymaster 2 e anteriores
typedef enum {
KM_MODE_ECB = 1,
KM_MODE_CBC = 2,
KM_MODE_CTR = 3,
KM_MODE_GCM = 32,
} keymaster_block_mode_t;
Esta tag é repetível e, para operações de chave AES, especifique um modo no argumento additionalParams de Begin . Se o modo especificado não estiver nos modos associados à chave, a operação falhará com ErrorCode::INCOMPATIBLE_BLOCK_MODE .
Etiqueta::BOOT_PATCHLEVEL
Versão : 4
Tag::BOOT_PATCHLEVEL especifica o nível do patch de segurança da imagem de inicialização (kernel) com o qual a chave pode ser usada. Esta tag nunca é enviada ao TA keymaster, mas é adicionada à lista de autorização imposta por hardware pelo TA. Qualquer tentativa de usar uma chave com um valor Tag::BOOT_PATCHLEVEL diferente do nível de patch do sistema atualmente em execução faz com que begin() , getKeyCharacteristics() ou exportKey() retorne ErrorCode::KEY_REQUIRES_UPGRADE . Consulte upgradeKey() para obter detalhes.
O valor da tag é um número inteiro no formato AAAAMMDD, onde AAAA é o ano de quatro dígitos da última atualização, MM é o mês de dois dígitos e DD é o dia de dois dígitos da última atualização. Por exemplo, para uma chave gerada em um dispositivo Android atualizado pela última vez em 5 de junho de 2018, o valor seria 20180605. Se o dia não for conhecido, 00 poderá ser substituído.
Durante cada inicialização, o bootloader deve fornecer o nível de patch da imagem de inicialização para o ambiente seguro (o mecanismo é definido pela implementação).
Deve ser aplicado por hardware.
Etiqueta::BOOTLOADER_ONLY
Versão : 1, 2, 3, 4
Repetivel ? Não
Especifica que apenas o bootloader pode usar a chave.
Esta tag é booleana, portanto os valores possíveis são verdadeiro (se a tag estiver presente) e falso (se a tag não estiver presente).
Qualquer tentativa de usar uma chave com Tag::BOOTLOADER_ONLY do sistema Android falha com ErrorCode::INVALID_KEY_BLOB .
Tag::CALLER_NONCE
Versão : 1, 2, 3, 4
Repetivel ? Não
Especifica que o chamador pode fornecer um nonce para operações que exigem nonce.
Esta tag é booleana, portanto os valores possíveis são verdadeiro (se a tag estiver presente) e falso (se a tag não estiver presente).
Esta tag é usada apenas para chaves AES e é relevante apenas para modos de bloco CBC, CTR e GCM. Se a tag não estiver presente, as implementações deverão rejeitar qualquer operação que forneça Tag::NONCE para começar com ErrorCode::CALLER_NONCE_PROHIBITED .
Tag::CREATION_DATETIME
Versão : 1, 2, 3, 4
Repetivel ? Não
Especifica a data e hora em que a chave foi criada, em milissegundos, desde 1º de janeiro de 1970. Esta tag é opcional e apenas informativa.
Tag::DIGESTIR
Versão : 1, 2, 3, 4
Repetivel ? Sim
Especifica os algoritmos de resumo que podem ser usados com a chave para executar operações de assinatura e verificação. Esta tag é relevante para chaves RSA, ECDSA e HMAC.
Os valores possíveis são definidos pela seguinte enumeração:
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 e 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 tag é repetível. Para operações de assinatura e verificação, especifique um resumo no argumento additionalParams de Begin . Se o resumo especificado não estiver nos resumos associados à chave, a operação falhará com ErrorCode::INCOMPATIBLE_DIGEST .
Etiqueta::EC_CURVE
Versão : 2, 3, 4
Repetivel ? Não
No Keymaster 1, a curva usada para chaves EC foi calculada a partir do tamanho de chave especificado. Para melhorar a flexibilidade no futuro, o Keymaster 2 introduziu uma maneira explícita de especificar curvas. As solicitações de geração de chave EC podem ter Tag::EC_CURVE , Tag::KEY_SIZE ou ambos.
Os valores possíveis são definidos pela seguinte enumeração:
Keymaster 3
enum class EcCurve : uint32_t {
P_224 = 0,
P_256 = 1,
P_384 = 2,
P_521 = 3,
};
Keymaster 2 e anteriores
enum class EcCurve : uint32_t {
P_224 = 0,
P_256 = 1,
P_384 = 2,
P_521 = 3,
};
Se uma solicitação de geração contiver apenas Tag::KEY_SIZE , volte para a lógica Keymaster 1, escolhendo a curva NIST apropriada.
Se a solicitação contiver apenas Tag::EC_CURVE , use a curva especificada. Para Keymaster 3 e posteriores, as curvas são definidas em EcCurve . Para Keymaster 2 e anteriores, as curvas são definidas em keymaster_ec_curve_t .
Se a solicitação contiver ambos, use a curva especificada por Tag::EC_CURVE e valide se o tamanho da chave especificado é apropriado para essa curva. Caso contrário, retorne ErrorCode::INVALID_ARGUMENT .
Etiqueta::INCLUDE_UNIQUE_ID
Versão : 2, 3, 4
Repetivel ? Não
Essa tag é especificada durante a geração de chave para indicar que um certificado de atestado para a chave gerada deve conter um ID exclusivo do dispositivo com escopo de aplicativo e limite de tempo, conforme especificado por Tag::UNIQUE_ID .
Esta tag é booleana, portanto os valores possíveis são verdadeiro (se a tag estiver presente) e falso (se a tag não estiver presente).
Etiqueta::KEY_SIZE
Versão : 1, 2, 3, 4
Repetivel ? Não
Especifica o tamanho, em bits, da chave, medindo da maneira normal para o algoritmo da chave. Por exemplo, para chaves RSA, Tag::KEY_SIZE especifica o tamanho do módulo público. Para chaves AES especifica o comprimento do material da chave secreta.
Etiqueta::MAC_LENGTH
Versão : 1, 2, 3, 4
Repetivel ? Não
Fornece o comprimento solicitado de uma etiqueta de autenticação MAC ou GCM, em bits.
O valor é o comprimento MAC em bits. É um múltiplo de 8 e pelo menos tão grande quanto o valor de Tag::MIN_MAC_LENGTH associado à chave.
Tag::MAX_USES_PER_BOOT
Versão : 1, 2, 3, 4
Repetivel ? Não
Especifica o número máximo de vezes que uma chave pode ser usada entre reinicializações do sistema. Este é outro mecanismo para limitar a taxa de uso da chave.
O valor é um número inteiro de 32 bits que representa os usos por inicialização.
Quando uma chave com esta tag é usada em uma operação, um contador associado à chave deve ser incrementado durante a chamada inicial . Depois que o contador de chaves exceder esse valor, todas as tentativas subsequentes de usar a chave falharão com ErrorCode::MAX_OPS_EXCEEDED , até que o dispositivo seja reiniciado. Isto implica que um trustlet mantém uma tabela de contadores de uso para chaves com esta tag. Como a memória do Keymaster é frequentemente limitada, esta tabela pode ter um tamanho máximo fixo e o Keymaster pode falhar em operações que tentem usar chaves com esta tag quando a tabela estiver cheia. A mesa precisa acomodar pelo menos 16 chaves. Se uma operação falhar porque a tabela está cheia, Keymaster retornará ErrorCode::TOO_MANY_OPERATIONS .
Etiqueta::MIN_MAC_LENGTH
Versão : 1, 2, 3, 4
Repetivel ? Não
Esta tag especifica o comprimento mínimo do MAC que pode ser solicitado ou verificado com esta chave para chaves HMAC e chaves AES que suportam o modo GCM.
Este valor é o comprimento mínimo do MAC, em bits. É um múltiplo de 8. Para chaves HMAC, o valor é pelo menos 64. Para chaves GCM, o valor é pelo menos 96 e não mais que 128.
Etiqueta::MIN_SECONDS_BETWEEN_OPS
Versão : 1, 2, 3, 4
Repetivel ? Não
Especifica o tempo mínimo decorrido entre as operações permitidas usando uma chave. Isso pode ser usado para limitar o uso de chaves em contextos onde o uso ilimitado pode permitir ataques de força bruta.
O valor é um número inteiro de 32 bits que representa os segundos entre as operações permitidas.
Quando uma chave com esta tag é usada em uma operação, inicia um cronômetro durante o término ou aborta a chamada. Qualquer chamada para começar recebida antes do cronômetro indica que o intervalo especificado por Tag::MIN_SECONDS_BETWEEN_OPS decorreu falha com ErrorCode::KEY_RATE_LIMIT_EXCEEDED . Isto implica que um trustlet mantém uma tabela de contadores de uso para chaves com esta tag. Como a memória do Keymaster é frequentemente limitada, esta tabela pode ter um tamanho máximo fixo e o Keymaster pode falhar em operações que tentem usar chaves com esta tag quando a tabela estiver cheia. A tabela precisa acomodar pelo menos 32 chaves em uso e reutilizar agressivamente os slots da tabela quando os intervalos de uso mínimo das chaves expirarem. Se uma operação falhar porque a tabela está cheia, Keymaster retornará ErrorCode::TOO_MANY_OPERATIONS .
Etiqueta::NO_AUTH_REQUIRED
Versão : 1, 2, 3, 4
Repetivel ? Não
Especifica que nenhuma autenticação é necessária para usar esta chave. Esta tag é mutuamente exclusiva com Tag::USER_SECURE_ID .
Esta tag é booleana, portanto os valores possíveis são verdadeiro (se a tag estiver presente) e falso (se a tag não estiver presente).
Tag::NÃO
Versão : 1, 2, 3, 4
Repetivel ? Não
Fornece ou retorna um nonce ou vetor de inicialização (IV) para criptografia ou descriptografia AES GCM, CBC ou CTR. Essa tag é fornecida para iniciar durante as operações de criptografia e descriptografia. Só é fornecido para começar se a chave tiver Tag::CALLER_NONCE . Se não for fornecido, um nonce ou IV apropriado será gerado aleatoriamente pelo Keymaster e retornado desde o início.
O valor é um blob, uma matriz de bytes de comprimento arbitrário. Os comprimentos permitidos dependem do modo: os nonces do GCM têm 12 bytes de comprimento; CBC e CTR IVs têm 16 bytes de comprimento.
Etiqueta::ORIGEM
Versão : 1, 2, 3, 4
Repetivel ? Não
Especifica onde a chave foi criada, se conhecida. Essa tag não pode ser especificada durante a geração ou importação da chave e deve ser adicionada às características da chave pelo trustlet.
Mestre-chave 3 Os valores possíveis são definidos em android::hardware::keymaster::v3_0::KeyOrigin :
enum class KeyOrigin : uint32_t {
GENERATED = 0,
DERIVED = 1,
IMPORTED = 2,
UNKNOWN = 3,
};
Keymaster 2 e anteriores Os valores possíveis são definidos em keymaster_origin_t :
typedef enum {
KM_ORIGIN_GENERATED = 0,
KM_ORIGIN_IMPORTED = 2,
KM_ORIGIN_UNKNOWN = 3,
} keymaster_key_origin_t
O significado completo do valor depende não apenas do valor, mas também de ele ser encontrado na lista de características impostas por hardware ou por software.
GENERATED indica que o Keymaster gerou a chave. Se estiver na lista imposta por hardware, a chave foi gerada em hardware seguro e está permanentemente vinculada ao hardware. Se estiver na lista imposta por software, a chave foi gerada no SoftKeymaster e não está vinculada ao hardware.
DERIVED indica que a chave foi derivada dentro do Keymaster. Provavelmente existe fora do dispositivo.
IMPORTED indica que a chave foi gerada fora do Keymaster e importada para o Keymaster. Se estiver na lista imposta por hardware, ele estará permanentemente vinculado ao hardware, embora possam existir cópias fora do hardware seguro. Se estiver na lista de aplicação de software, a chave foi importada para o SoftKeymaster e não está vinculada ao hardware.
UNKNOWN só deve aparecer na lista imposta por hardware. Indica que a chave está vinculada ao hardware, mas não se sabe se a chave foi gerada originalmente em hardware seguro ou foi importada. Isso ocorre apenas quando o hardware keymaster0 está sendo usado para emular serviços keymaster1.
Etiqueta::ORIGINATION_EXPIRE_DATETIME
Versão : 1, 2, 3, 4
Repetivel ? Não
Especifica a data e a hora em que a chave expira para fins de assinatura e criptografia. Após esse período, qualquer tentativa de usar uma chave com KeyPurpose::SIGN ou KeyPurpose::ENCRYPT fornecida para começar falhará com ErrorCode::KEY_EXPIRED .
O valor é um número inteiro de 64 bits que representa milissegundos desde 1º de janeiro de 1970.
Etiqueta::OS_PATCHLEVEL
Versão : 2, 3, 4
Repetivel ? Não
Esta tag nunca é enviada ao TA keymaster, mas é adicionada à lista de autorização imposta por hardware pelo TA.
O valor da tag é um número inteiro no formato AAAAMM, onde AAAA é o ano de quatro dígitos da última atualização e MM é o mês de dois dígitos da última atualização. Por exemplo, para uma chave gerada em um dispositivo Android atualizado pela última vez em dezembro de 2015, o valor seria 201512.
Chaves que possuem um nível de patch diferente do nível de patch atual não podem ser utilizadas. Uma tentativa de usar essa chave faz com que begin , getKeyCharacteristics ou exportKey retorne ErrorCode::KEY_REQUIRES_UPGRADE . Consulte Ligação de versão para obter mais detalhes.
Etiqueta::OS_VERSION
Versão : 2, 3, 4
Repetivel ? Não
Esta tag nunca é enviada ao TA keymaster, mas é adicionada à lista de autorização imposta por hardware pelo TA.
O valor da tag é um número inteiro no formato MMmmss, onde MM é o número da versão principal, mm é o número da versão secundária e ss é o número da versão subsecundária. Por exemplo, para uma chave gerada no Android versão 4.0.3, o valor seria 040003.
Tag::PADDING
Versão : 1, 2, 3, 4
Repetivel ? Sim
Especifica os modos de preenchimento que podem ser usados com a chave. Esta tag é relevante para chaves RSA e AES.
Os valores possíveis são definidos pela seguinte enumeração:
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 e 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 e PaddingMode::RSA_PKCS1_1_5_ENCRYPT são usados apenas para chaves de criptografia/descriptografia RSA e especificam o preenchimento RSA PKCS#1v2 OAEP e o preenchimento aleatório RSA PKCS#1 v1.5, respectivamente. PaddingMode::RSA_PSS e PaddingMode::RSA_PKCS1_1_5_SIGN são usados apenas para chaves de assinatura/verificação RSA e especificam o preenchimento PSS RSA PKCS#1v2 e o preenchimento determinístico RSA PKCS#1 v1.5, respectivamente.
PaddingMode::NONE pode ser usado com chaves RSA ou AES. Para chaves AES, se PaddingMode::NONE for usado com o modo de bloco ECB ou CBC e os dados a serem criptografados ou descriptografados não forem múltiplos do tamanho do bloco AES, a chamada para finalizar falhará com ErrorCode::INVALID_INPUT_LENGTH .
PaddingMode::PKCS7 só pode ser usado com chaves AES e apenas com os modos ECB e CBC.
Esta tag é repetível. Um modo de preenchimento deve ser especificado na chamada para começar . Se o modo especificado não estiver autorizado para a chave, a operação falhará com ErrorCode::INCOMPATIBLE_BLOCK_MODE .
Tag::OBJETIVO
Versão : 1, 2, 3, 4
Repetivel ? Sim
Especifica o conjunto de finalidades para as quais a chave pode ser usada.
Os valores possíveis são definidos pela seguinte enumeração:
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 e anteriores
typedef enum {
KM_PURPOSE_ENCRYPT = 0,
KM_PURPOSE_DECRYPT = 1,
KM_PURPOSE_SIGN = 2,
KM_PURPOSE_VERIFY = 3,
} keymaster_purpose_t;
Esta tag é repetível; as chaves podem ser geradas com vários valores, embora uma operação tenha um único propósito. Quando a função start é chamada para iniciar uma operação, o propósito da operação é especificado. Se a finalidade especificada para a operação não for autorizada pela chave, a operação falhará com ErrorCode::INCOMPATIBLE_PURPOSE .
Etiqueta::RESET_SINCE_ID_ROTATION
Versão : 3, 4
Repetivel ? Não
Especifica se o dispositivo foi redefinido para a configuração original desde a última rotação de ID exclusiva. Usado para atestado de chave.
Esta tag é booleana, portanto os valores possíveis são verdadeiro (se a tag estiver presente) e falso (se a tag não estiver presente).
Etiqueta::ROLLBACK_RESISTANT
Versão : 1, 2, 3, 4
Repetivel ? Não
Indica que a chave é resistente à reversão, o que significa que, quando excluída por deleteKey ou deleteAllKeys , a chave será excluída permanentemente e inutilizável. É possível que chaves sem essa tag sejam excluídas e restauradas do backup.
Esta tag é booleana, portanto os valores possíveis são verdadeiro (se a tag estiver presente) e falso (se a tag não estiver presente).
Tag::ROOT_OF_TRUST
Versão : 1, 2, 3, 4
Repetivel ? Não
Especifica a raiz de confiança , a chave usada pela inicialização verificada para validar o sistema operacional inicializado (se houver). Esta tag nunca é fornecida ou retornada pelo Keymaster nas características principais.
Etiqueta::RSA_PUBLIC_EXPONENT
Versão : 1, 2, 3, 4
Repetivel ? Não
Especifica o valor do expoente público para um par de chaves RSA. Essa tag é relevante somente para chaves RSA e necessária para todas as chaves RSA.
O valor é um número inteiro sem sinal de 64 bits que atende aos requisitos de um expoente público RSA. Este valor deve ser um número primo. Trustlets suportam o valor 2^16+1 e podem suportar outros valores razoáveis, em particular o valor 3. Se nenhum expoente for especificado ou se o expoente especificado não for suportado, a geração de chave falhará com ErrorCode::INVALID_ARGUMENT .
Etiqueta::UNIQUE_ID
Versão : 3, 4
Repetivel ? Não
Usado para fornecer um ID exclusivo no atestado.
O valor é um blob, uma matriz de bytes de comprimento arbitrário.
Etiqueta::USAGE_EXPIRE_DATETIME
Versão : 1, 2, 3, 4
Repetivel ? Não
Especifica a data e a hora em que a chave expira para fins de verificação e descriptografia. Após esse período, qualquer tentativa de usar uma chave com KeyPurpose::VERIFY ou KeyPurpose::DECRYPT fornecida para começar falhará com ErrorCode::KEY_EXPIRED .
O valor é um número inteiro de 64 bits que representa milissegundos desde 1º de janeiro de 1970.
Etiqueta::USER_AUTH_TYPE
Versão : 1, 2, 3, 4
Repetivel ? Não
Especifica os tipos de autenticadores de usuário que podem ser usados para autorizar esta chave. Quando o Keymaster é solicitado a realizar uma operação com uma chave com esta tag, ele recebe um token de autenticação e o campo authenticator_type do token precisa corresponder ao valor da tag. Por exemplo, (ntoh(token.authenticator_type) & auth_type_tag_value) != 0 , onde ntoh é uma função que converte inteiros ordenados pela rede em inteiros ordenados pelo host e auth_type_tag_value é o valor desta tag.
O valor é uma máscara de bits inteira de 32 bits com valores da enumeração:
Keymaster 3
enum class HardwareAuthenticatorType : uint32_t {
NONE = 0u, // 0
PASSWORD = 1 << 0,
FINGERPRINT = 1 << 1,
ANY = UINT32_MAX,
};
Keymaster 2 e 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
Versão : 1, 2, 3, 4
Repetivel ? Não
Especifica que uma chave só pode ser usada sob um determinado estado de autenticação de usuário seguro. Esta tag é mutuamente exclusiva com Tag::NO_AUTH_REQUIRED .
O valor é um número inteiro de 64 bits que especifica o valor do estado da política de autenticação que precisa estar presente em um token de autenticação (fornecido para começar com Tag::AUTH_TOKEN ) para autorizar o uso da chave. Qualquer chamada para começar com uma chave com esta tag que não forneça um token de autenticação ou forneça um token de autenticação sem um valor de estado de política correspondente falhará.
Esta tag é repetível. Se algum dos valores fornecidos corresponder a qualquer valor de estado de política no token de autenticação, a chave será autorizada para uso. Caso contrário, a operação falhará com ErrorCode::KEY_USER_NOT_AUTHENTICATED .
Etiqueta::VENDOR_PATCHLEVEL
Versão : 4
Esta tag especifica o nível de patch de segurança da imagem do fornecedor com o qual a chave pode ser usada. Esta tag nunca é enviada ao TA keymaster, mas é adicionada à lista de autorização imposta por hardware pelo TA. Qualquer tentativa de usar uma chave com um valor Tag::VENDOR_PATCHLEVEL diferente do nível de patch do sistema atualmente em execução deve fazer com que begin() , getKeyCharacteristics() ou exportKey() retorne ErrorCode::KEY_REQUIRES_UPGRADE . Consulte upgradeKey() para obter detalhes.
O valor da tag é um número inteiro no formato AAAAMMDD, onde AAAA é o ano de quatro dígitos da última atualização, MM é o mês de dois dígitos e DD é o dia de dois dígitos da última atualização. Por exemplo, para uma chave gerada em um dispositivo Android atualizado pela última vez em 5 de junho de 2018, o valor seria 20180605.
O HAL IKeymasterDevice deve ler o patchlevel do fornecedor atual da propriedade do sistema ro.vendor.build.security_patch e entregá-lo ao ambiente seguro quando o HAL for carregado pela primeira vez (o mecanismo é definido pela implementação). O ambiente seguro não deve aceitar outro nível de patch até depois da próxima inicialização.
Deve ser aplicado por hardware.