Tags de autorização do keymaster

Esta página fornece detalhes para ajudar os implementadores de HALs do Keymaster. Abrange cada tag na HAL, qual versão do Keymaster essa tag está disponível e se a tag pode ser repetida. Exceto conforme indicado nas descrições das tags, Todas as tags abaixo são usadas durante a geração de chaves para especificar e as características determinantes.

Para o Keymaster 4, as tags são definidas em platform/hardware/interfaces/keymaster/keymaster-version/types.hal, como 3.0/types.hal para o Keymaster 3 e 4.0/types.hal para o Keymaster 4. No Keymaster 2 e versões anteriores, as tags são definidas em platform/hardware/libhardware/include/hardware/keymaster_defs.h:

Para funções, consulte a Página Keymaster Functions.

Tag::ACTIVE_DATETIME

Versão: 1, 2, 3, 4

Repetível? Não

Especifica a data e a hora em que a chave vai ser ativada. Antes desse período, qualquer tentativa de uso da chave falha 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

Reproduzível? Não

Especifica o algoritmo criptográfico com que 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::ALL_APPLICATIONS

Versão: 1, 2, 3, 4

Repetível? Não

Reservado para uso futuro.

Tag::ALLOW_WHILE_ON_BODY

Versão: 2, 3, 4

Repetível? Não

Essa tag é aplicável apenas a dispositivos Android Wear com sensores no corpo. Em nenhum TEE pode oferecer acesso seguro a um sensor corporal ou que os sensores no corpo são muito seguros, então seja simplesmente aplicado por software.

Marcar::ALL_USERS

Versão: 3, 4

Repetível? Não

Reservado para uso futuro.

Tag::APPLICATION_DATA

Versão: 1, 2, 3, 4

Repetível? Não

Quando fornecida a generateKey ou importKey, essa 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 begin 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 dessa tag está vinculado à chave criptograficamente, o que significa que não deve ser possível que um adversário com acesso a todos os segredos mundiais seguros, mas não tem acesso ao conteúdo da tag para descriptografar a sem forçar brutalmente o conteúdo da tag, o que os apps podem evitar ao especificando conteúdo com entropia alta o suficiente.

O valor é um blob, uma matriz de bytes de tamanho arbitrário.

Tag::APPLICATION_ID

Versão: 1, 2, 3, 4

Repetível? Não

Quando fornecida a generateKey ou importKey, essa tag especifica os dados necessários durante todos os usos da chave. Em especialmente chamadas exportKey e getKeyCharacteristics (em inglês) fornecer o mesmo valor no parâmetro clientId; chamadas para begin precisam forneça essa tag e os mesmos dados associados como parte inParams definido. Se os dados corretos não forem fornecidos, a função retorna ErrorCode::INVALID_KEY_BLOB.

O conteúdo dessa tag é vinculado à chave criptograficamente, o que significa que um invasor 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 usar força bruta no conteúdo da tag.

O valor é um blob, uma matriz de bytes de comprimento arbitrário.

Tag::ASSOCIATED_DATA

Versão: 1, 2, 3, 4

Repetível? Não

Fornece "dados associados" para criptografia ou descriptografia AES-GCM. Essa 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.

Tag::ATTESTATION_APPLICATION_ID

Versão: 3, 4

Repetível? Não

Usado para identificar o conjunto de possíveis apps de qual deles iniciou um atestado de chaves.

O valor é um blob, uma matriz de bytes de tamanho arbitrário.

Tag::ATTESTATION_CHALLENGE

Versão: 3, 4

Repetível? Não

Usado para fornecer desafio no atestado.

O valor é um blob, uma matriz de bytes de comprimento arbitrário.

Tag::ATTESTATION_ID_BRAND

Versão: 3, 4

Reproduzível? Não

Informa o nome da marca do dispositivo, conforme retornado por Build.BRAND no Android. Esse campo é definido apenas quando a solicitação de atestado dos identificadores do dispositivo é feita.

Se o dispositivo não oferecer suporte ao atestado de ID (ou destroyAttestationIds() já foi chamado, e o dispositivo pode não atestar mais seus IDs), qualquer solicitação de atestado de chaves que inclua essa tag vai 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

Repetível? Não

Fornece o nome do dispositivo, conforme retornado por Build.DEVICE no Android. Esse campo é definido apenas quando a solicitação de atestado dos identificadores do dispositivo é feita.

Se o dispositivo não oferecer suporte ao atestado de ID (ou destroyAttestationIds() já foi chamado, e o dispositivo pode não atestar mais seus IDs), qualquer solicitação de atestado de chaves que inclua essa tag vai falhar com ErrorCode::CANNOT_ATTEST_IDS.

O valor é um blob, uma matriz de bytes de tamanho arbitrário.

Tag::ATTESTATION_ID_IMEI

Versão: 3, 4

Repetível? Sim

Informa os IMEIs de todos os rádios no dispositivo. Este campo é definido apenas ao solicitar o atestado dos identificadores do dispositivo.

Se o dispositivo não oferecer suporte ao atestado de ID (ou destroyAttestationIds() já foi chamado, e o dispositivo pode não atestar mais seus IDs), qualquer solicitação de atestado de chaves que inclua essa tag vai falhar com ErrorCode::CANNOT_ATTEST_IDS.

O valor é um blob, uma matriz de bytes de tamanho arbitrário.

Tag::ATTESTATION_ID_MANUFACTURER

Versão: 3, 4

Reproduzível? Não

Fornece o nome do fabricante do dispositivo, conforme retornado por Build.MANUFACTURER no Android. Este campo é definido apenas quando solicitando o atestado dos identificadores do dispositivo.

Se o dispositivo não oferecer suporte ao atestado de ID (ou destroyAttestationIds() tiver sido chamado anteriormente e o dispositivo não poder mais atestar os IDs), qualquer solicitação de atestado de chave que inclua essa tag vai falhar com ErrorCode::CANNOT_ATTEST_IDS.

O valor é um blob, uma matriz de bytes de comprimento arbitrário.

Tag::ATTESTATION_ID_MEID

Versão: 3, 4

Repetível? Sim

Fornece os MEIDs de todos os rádios no dispositivo. Este campo é definido apenas ao solicitar o atestado dos identificadores do dispositivo.

Se o dispositivo não oferecer suporte ao atestado de ID (ou destroyAttestationIds() já foi chamado, e o dispositivo pode não atestar mais seus IDs), qualquer solicitação de atestado de chaves que inclua essa tag vai falhar com ErrorCode::CANNOT_ATTEST_IDS.

O valor é um blob, uma matriz de bytes de comprimento arbitrário.

Tag::ATTESTATION_ID_MODEL

Versão: 3, 4

Repetível? Não

Fornece o nome do modelo do dispositivo, conforme retornado por Build.MODEL no Android. Este campo é definido apenas quando solicitando o atestado dos identificadores do dispositivo.

Se o dispositivo não oferecer suporte ao atestado de ID (ou destroyAttestationIds() tiver sido chamado anteriormente e o dispositivo não poder mais atestar os IDs), qualquer solicitação de atestado de chave que inclua essa tag vai falhar com ErrorCode::CANNOT_ATTEST_IDS.

O valor é um blob, uma matriz de bytes de comprimento arbitrário.

Tag::ATTESTATION_ID_PRODUCT

Versão: 3, 4

Reproduzível? Não

Fornece o nome do produto do dispositivo, conforme retornado por Build.PRODUCT no Android. Esse campo é definido apenas ao solicitar atestado dos identificadores do dispositivo.

Se o dispositivo não oferecer suporte ao atestado de ID (ou destroyAttestationIds() tiver sido chamado anteriormente e o dispositivo não poder mais atestar os IDs), qualquer solicitação de atestado de chave que inclua essa tag vai falhar com ErrorCode::CANNOT_ATTEST_IDS.

O valor é um blob, uma matriz de bytes de tamanho arbitrário.

Tag::ATTESTATION_ID_SERIAL

Versão: 3, 4

Repetível? Não

Informa o número de série do dispositivo. Esse campo é definido apenas ao solicitar atestado dos identificadores do dispositivo.

Se o dispositivo não oferecer suporte ao atestado de ID (ou destroyAttestationIds() tiver sido chamado anteriormente e o dispositivo não poder mais atestar os IDs), qualquer solicitação de atestado de chave que inclua essa tag vai falhar com ErrorCode::CANNOT_ATTEST_IDS.

O valor é um blob, uma matriz de bytes de comprimento arbitrário.

Tag::AUTH_TIMEOUT

Versão: 1, 2, 3, 4

Repetível? Não

Especifica o tempo em segundos em que a chave está autorizada para uso após a autenticação. Se Tag::USER_SECURE_ID estiver presente e esta tag não estiver, a chave precisará de autenticação para cada do uso (consulte início para 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 especificada por Tag::USER_SECURE_ID com o método de autenticação especificado por Tag::USER_AUTH_TYPE que a chave pode ser usada.

Tag::AUTH_TOKEN

Versão: 1, 2, 3, 4

Repetível? Não

Fornece um token de autenticação para iniciar, atualizar ou finalizar, para provar a autenticação do usuário para uma operação de chave que a exige (a chave tem Tag::USER_SECURE_ID).

O valor é um blob que contém uma estrutura hw_auth_token_t.

Tag::BLOB_USAGE_REQUIREMENTS

Versão: 1, 2, 3, 4

Repetível? Não

Especifica as condições de ambiente necessárias do sistema para o a ser usada.

Os valores possíveis são definidos pela seguinte enumeração:

Keymaster 3 (link em inglês) 
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. Ela precisa ser retornada com a chave características generateKey e getKeyCharacteristics. Se o autor da chamada especificar Tag::BLOB_USAGE_REQUIREMENTS com o valor KeyBlobUsageRequirements::STANDALONE, o trustlet vai retornar um blob de chave que pode ser usado sem suporte ao sistema de arquivos. Isso é essencial para dispositivos com discos criptografados, em que o sistema de arquivos pode não estar disponível até que uma chave Keymaster seja usada para descriptografar o disco.

Tag::BLOCK_MODE

Versão: 1, 2, 3, 4

Repetível? Sim

Especifica os modos de cifra de bloco com que a chave pode ser usada. Essa tag é relevante apenas para chaves AES.

Os valores possíveis são definidos pela seguinte enumeração:

Keymaster 3 (link em inglês) 
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;

Essa tag pode ser repetida, e para operações de chave AES especifique um modo no o argumento additionalParams de começar. Se o modo especificado não estiver nos modos associados à chave, a operação falhará com ErrorCode::INCOMPATIBLE_BLOCK_MODE.

Tag::BOOT_PATCHLEVEL

Versão: 4

Tag::BOOT_PATCHLEVEL especifica o nível de patch de segurança da imagem de inicialização (kernel) com que a chave pode ser usada. Essa tag nunca é enviada ao keymaster TA, mas é adicionada à lista de autorizações impostas por hardware pelo TA. Qualquer tentativa de use uma chave com um valor Tag::BOOT_PATCHLEVEL diferente do atualmente em execução no nível do patch do sistema causa begin(), getKeyCharacteristics() ou exportKey() para devolução ErrorCode::KEY_REQUIRES_UPGRADE. Consulte upgradeKey() para mais detalhes.

O valor da tag é um número inteiro no formato AAAAMMDD, em que AAAA é o ano com quatro dígitos da última atualização, MM é o mês com 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 atualizada pela última vez em 5 de junho de 2018, o valor seria 20180605. Se o dia não for conhecido, 00 pode ser substituído.

Durante cada inicialização, o carregador de inicialização precisa fornecer o nível de patch da imagem de inicialização ao ambiente seguro (o mecanismo é definido pela implementação).

Precisa ser aplicada por hardware.

Tag::BOOTLOADER_ONLY

Versão: 1, 2, 3, 4

Reproduzível? Não

Especifica que apenas o carregador de inicialização pode usar a chave.

Essa tag é booleana, então 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 O sistema Android falha com ErrorCode::INVALID_KEY_BLOB.

Tag::CALLER_NONCE

Versão: 1, 2, 3, 4

Repetível? Não

Especifica que o autor da chamada pode fornecer um valor de uso único para operações que exigem valor de uso único.

Essa tag é booleana. Portanto, os valores possíveis são "true" (se a tag estiver presente). e "false" (se a tag não estiver presente).

Essa tag é usada apenas para chaves AES e é relevante apenas para os modos de bloqueio CBC, CTR e GCM. Se a tag não estiver presente, as implementações deverão rejeitar todas as operação que fornece Tag::NONCE para início com ErrorCode::CALLER_NONCE_PROHIBITED.

Tag::CREATION_DATETIME

Versão: 1, 2, 3, 4

Repetível? Não

Especifica a data e a hora em que a chave foi criada, em milissegundos desde 1º de janeiro de 1970. Essa tag é opcional e serve apenas para fins informativos.

Tag::DIGEST

Versão: 1, 2, 3, 4

Repetível? Sim

Especifica os algoritmos de resumo que podem ser usados com a chave para realizar operações de assinatura e verificação. Essa tag é relevante para RSA, ECDSA e Chaves 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;

Essa tag pode ser repetida. Para operações de assinatura e verificação, especifique um resumo no argumento additionalParams de começar. Se o resumo especificado não estiver nos resumos associados à chave, a operação falhará com ErrorCode::INCOMPATIBLE_DIGEST.

Tag::EC_CURVE

Versão: 2, 3, 4

Repetível? Não

No Keymaster 1, a curva usada para chaves EC era adivinhada com base no tamanho especificado. Para melhorar a flexibilidade no futuro, o Keymaster 2 introduziu uma de especificar curvas. As solicitações de geração de chaves de 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 só contiver Tag::KEY_SIZE, voltar à lógica do Keymaster 1 e escolher a curva NIST adequada.

Se a solicitação tiver apenas Tag::EC_CURVE, use a curva especificada. Para o Keymaster 3 e versões mais recentes, as curvas são definidas em EcCurve. Para Keymaster 2 e versões 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 validar se o tamanho de chave especificado é apropriada para a curva. Caso contrário, retorne ErrorCode::INVALID_ARGUMENT.

Tag::INCLUDE_UNIQUE_ID

Versão: 2, 3, 4

Repetível? Não

Essa tag é especificada durante a geração de chaves para indicar que um atestado da chave gerada deve conter uma string com escopo do app ID exclusivo do dispositivo com limite de tempo, conforme especificado por Tag::UNIQUE_ID

Essa tag é booleana, então os valores possíveis são verdadeiro (se a tag estiver presente) e falso (se a tag não estiver presente).

Tag::KEY_SIZE

Versão: 1, 2, 3, 4

Repetível? 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, ele especifica o comprimento do material da chave secreta.

Tag::MAC_LENGTH

Versão: 1, 2, 3, 4

Reproduzível? Não

Fornece o comprimento solicitado de uma tag 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

Repetível? Não

Especifica o número máximo de vezes que uma chave pode ser usada entre as reinicializações do sistema. Esse é outro mecanismo para limitar a taxa do uso de chaves.

O valor é um número inteiro de 32 bits que representa os usos por inicialização.

Quando uma chave com essa tag é usada em uma operação, um contador associado à chave precisa ser incrementado durante a chamada begin. Após a chave o contador tiver excedido esse valor, todas as tentativas subsequentes de usar a chave falharão com ErrorCode::MAX_OPS_EXCEEDED até que o dispositivo seja reiniciado. Isso indica que um trustlet mantém uma tabela de contadores de uso para chaves com este tag. Como a memória do Keymaster geralmente é limitada, essa tabela pode ter um tamanho máximo fixo, e o Keymaster pode falhar em operações que tentam usar chaves com essa tag quando a tabela está cheia. A tabela precisa acomodar pelo menos 16 chaves. Se uma operação falhar porque a tabela está cheia, o Keymaster retornará ErrorCode::TOO_MANY_OPERATIONS:

Tag::MIN_MAC_LENGTH

Versão: 1, 2, 3, 4

Repetível? Não

Essa tag especifica o comprimento mínimo de MAC que pode ser solicitado ou verificado com essa chave para chaves HMAC e AES que oferecem suporte ao modo GCM.

Esse valor é o comprimento mínimo do MAC, em bits. É um múltiplo de 8. Para chaves HMAC, o valor é de pelo menos 64. Para chaves GCM, o valor é de pelo menos 96 e não mais que 128.

Tag::MIN_SECONDS_BETWEEN_OPS

Versão: 1, 2, 3, 4

Repetível? Não

Especifica o período mínimo decorrido entre o intervalo permitido operações usando uma chave. Isso pode ser usado para limitar a taxa de usos de chaves em contextos em que o uso ilimitado pode permitir ataques de força bruta.

O valor é um número inteiro de 32 bits que representa segundos entre as operações permitidas.

Quando uma chave com essa tag é usada em uma operação, inicie um timer durante a chamada finish ou abort. Qualquer chamada para begin que seja recebida antes que o timer indique que o intervalo especificado por Tag::MIN_SECONDS_BETWEEN_OPS tenha decorrido falhará com ErrorCode::KEY_RATE_LIMIT_EXCEEDED. Isso implica que um trustlet mantém uma tabela de contadores de uso para chaves com esta tag. Como a memória do Keymaster geralmente é limitada, essa tabela pode ter um tamanho máximo fixo e o Keymaster pode falhar em operações que tentam usar chaves com essa tag quando a tabela está cheia. A tabela precisa acomodar pelo menos 32 chaves em uso e reutilizar agressivamente os slots de tabela quando os intervalos de uso mínimo da chave expirarem. Se uma operação falhar porque a tabela está cheia, o Keymaster retornará ErrorCode::TOO_MANY_OPERATIONS:

Tag::NO_AUTH_REQUIRED

Versão: 1, 2, 3, 4

Repetível? Não

Especifica que nenhuma autenticação é necessária para usar essa chave. Essa tag é mutuamente exclusiva de Tag::USER_SECURE_ID.

Essa tag é booleana, então os valores possíveis são verdadeiro (se a tag estiver presente) e falso (se a tag não estiver presente).

Tag::NONCE

Versão: 1, 2, 3, 4

Repetível? Não

Fornece ou retorna um valor de uso único ou vetor de inicialização (IV) para criptografia ou descriptografia AES GCM, CBC ou CTR. Essa tag é fornecida para iniciar as operações de criptografia e descriptografia. Ele só é fornecido para begin se a chave tiver Tag::CALLER_NONCE. Caso contrário, um valor de uso único apropriado ou IV é gerado aleatoriamente pelo Keymaster e retornadas do início.

O valor é um blob, uma matriz de bytes de comprimento arbitrário. Durações permitidas dependem do modo: os valores de uso único do GCM têm 12 bytes de comprimento. CBC e CTR IVs são 16 bytes de comprimento.

Tag::ORIGIN

Versão: 1, 2, 3, 4

Repetível? Não

Especifica onde a chave foi criada, se for conhecida. Essa tag não pode ser especificada durante a geração ou importação de chaves e precisa ser adicionada às características de chave pelo trustlet.

Keymaster 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 se ele está na lista de características aplicadas por hardware ou por software.

GENERATED indica que o Keymaster gerou a chave. Se ela estiver na lista de restrições de hardware, A chave foi gerada em um hardware seguro e está permanentemente vinculada ao hardware. Se na lista de aplicações de software, ela foi gerada no SoftKeymaster sem limitação de hardware.

DERIVED indica que a chave foi derivada no Keymaster. Provavelmente existe fora do dispositivo.

IMPORTED indica que a chave foi gerada fora do Keymaster e importadas para o Keymaster: Se estiver na lista de restrições de hardware, ele é permanentemente vinculado ao hardware. embora possam existir cópias fora do hardware seguro. Se estiver na lista de restrições de software, a chave foi importada para o Keymaster e não está vinculada ao hardware.

UNKNOWN só deve aparecer na lista de hardware. Ele indica que a chave está vinculada ao hardware, mas não se sabe se ela foi gerada originalmente em hardware seguro ou se foi importada. Isso só ocorre quando o hardware keymaster0 está que estão sendo usados para emular os serviços de keymaster1.

Tag::ORIGINATION_EXPIRE_DATETIME

Versão: 1, 2, 3, 4

Repetível? Não

Especifica a data e a hora em que a chave expira para assinatura e para fins de criptografia. Após esse período, qualquer tentativa de usar uma chave com KeyPurpose::SIGN ou KeyPurpose::ENCRYPT fornecida a begin falha com ErrorCode::KEY_EXPIRED.

O valor é um número inteiro de 64 bits que representa milissegundos desde 1º de janeiro de 1970.

Tag::OS_PATCHLEVEL

Versão: 2, 3, 4

Repetível? Não

Essa tag nunca é enviada ao TA do keymaster, mas é adicionada à lista de autorizações aplicada pelo hardware pelo TA.

O valor da tag é um número inteiro no formato AAAAMM, em que AAAA é o ano com quatro dígitos da última atualização e MM é o mês com dois dígitos da última atualização atualizar. Por exemplo, para uma chave gerada em um dispositivo Android atualizada pela última vez em dezembro de 2015, o valor seria 201512.

As chaves com um nível de patch diferente do atual não são utilizáveis. Uma tentativa de usar essa chave faz com que begin, getKeyCharacteristics ou exportKey retornem ErrorCode::KEY_REQUIRES_UPGRADE. Consulte Vinculação de versões para mais detalhes.

Tag::OS_VERSION

Versão: 2, 3, 4

Repetível? Não

Essa tag nunca é enviada ao TA do keymaster, mas é adicionada à lista de autorizações aplicada pelo hardware pelo TA.

O valor da tag é um número inteiro no formato MMmmss, em que MM é o maior número da versão, mm é o número da versão secundária e ss é a versão subsecundária. número Por exemplo, para uma chave gerada na versão 4.0.3 do Android, o valor seria 040003.

Tag::PADDING

Versão: 1, 2, 3, 4

Repetível? Sim

Especifica os modos de preenchimento que podem ser usados com a tecla. Essa tag é relevantes 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 somente para chaves de criptografia/descriptografia RSA e especifique o OAEP RSA PKCS#1v2 padding e padding aleatório PKCS#1 v1.5 do RSA, respectivamente. PaddingMode::RSA_PSS e PaddingMode::RSA_PKCS1_1_5_SIGN são usados apenas para RSAs chaves de assinatura/verificação e especificar RSA PKCS#1v2 PSS padding e padding determinístico RSA PKCS#1 v1.5, respectivamente.

PaddingMode::NONE pode ser usado com RSA ou chaves 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 um múltiplo do tamanho do bloco AES em comprimento, a chamada para terminar falhará com ErrorCode::INVALID_INPUT_LENGTH.

PaddingMode::PKCS7 só pode ser usado com chaves AES e somente com os modos ECB e CBC.

Essa tag pode ser repetida. Um modo de preenchimento precisa ser especificado na chamada para begin. Se o modo especificado não for autorizado para a chave, a operação vai falhar com ErrorCode::INCOMPATIBLE_BLOCK_MODE.

Tag::PURPOSE

Versão: 1, 2, 3, 4

Repetível? Sim

Especifica o conjunto de finalidades para o uso da chave.

Os valores possíveis são definidos pela seguinte enumeração:

Keymaster 3 (link em inglês) 
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;

Essa tag pode ser repetida. as chaves podem ser geradas com vários valores, embora uma operação tenha um único propósito. Quando o função begin é chamada para iniciar uma operação, a finalidade dela é especificada. Se a finalidade especificada para a operação não for autorizada pelo a operação vai falhar com ErrorCode::INCOMPATIBLE_PURPOSE.

Tag::RESET_SINCE_ID_ROTATION

Versão: 3, 4

Repetível? Não

Especifica se o dispositivo foi redefinido para a configuração original desde a última rotação do ID exclusivo. Usado para atestado de chave.

Essa tag é booleana, então os valores possíveis são verdadeiro (se a tag estiver presente) e falso (se a tag não estiver presente).

Tag::ROLLBACK_RESISTANT

Versão: 1, 2, 3, 4

Repetível? Não

Indica que a chave é resistente a reversão, o que significa que, quando excluída por deleteKey ou deleteAllKeys, a chave será permanentemente excluída e inutilizável. É possível que as chaves sem essa tag possam ser excluídas e, em seguida, restauradas do backup.

Essa tag é booleana. Portanto, os valores possíveis são "true" (se a tag estiver presente). e "false" (se a tag não estiver presente).

Tag::ROOT_OF_TRUST

Versão: 1, 2, 3, 4

Repetível? Não

Especifica a raiz de confiança, a chave usada pela inicialização verificada para validar se o sistema operacional foi inicializado (se houver). Essa tag nunca é fornecida ou retornados do Keymaster nas características da chave.

Tag::RSA_PUBLIC_EXPONENT

Versão: 1, 2, 3, 4

Repetível? Não

Especifica o valor do expoente público para um par de chaves RSA. Essa tag é relevante apenas para chaves RSA e é necessária para todas as chaves RSA.

O valor é um número inteiro não assinado de 64 bits que atende aos requisitos de um exponencial público RSA. Esse valor precisa ser um número primo. Os Trustlets oferecem suporte ao valor 2^16+1 e podem oferecer suporte a outros valores razoáveis, em particular o valor 3. Se nenhum expoente for especificado ou se não houver suporte para ele, a geração de chaves falha com ErrorCode::INVALID_ARGUMENT.

Tag::UNIQUE_ID

Versão: 3, 4

Repetível? Não

Usado para fornecer um ID exclusivo no atestado.

O valor é um blob, uma matriz de bytes de comprimento arbitrário.

Tag::USAGE_EXPIRE_DATETIME

Versão: 1, 2, 3, 4

Repetível? Não

Especifica a data e a hora em que a chave expira para verificação. para fins de descriptografia. Depois disso, qualquer tentativa de usar uma chave com KeyPurpose::VERIFY ou KeyPurpose::DECRYPT informado para falha em begin com ErrorCode::KEY_EXPIRED.

O valor é um número inteiro de 64 bits que representa milissegundos desde 1º de janeiro de 1970.

Tag::USER_AUTH_TYPE

Versão: 1, 2, 3, 4

Repetível? Não

Especifica os tipos de autenticadores de usuários que podem ser usados para autorizar essa de dados. Quando o Keymaster é solicitado a executar uma operação com uma chave com esse tag, ele recebe um token de autenticação, e a tag O campo authenticator_type precisa corresponder ao valor na tag. Por exemplo, (ntoh(token.authenticator_type) & auth_type_tag_value) != 0, em que ntoh é uma função que converte números inteiros ordenados pela rede em números inteiros ordenados pelo host e auth_type_tag_value é o valor dessa tag.

O valor é uma máscara de bits de número inteiro de 32 bits dos valores da enumeração:

Keymaster 3 (link em inglês) 
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;

Tag::USER_SECURE_ID

Versão: 1, 2, 3, 4

Repetível? Sim

Especifica que uma chave pode ser usada apenas sob um determinado usuário seguro o estado de autenticação. Essa 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 iniciar com Tag::AUTH_TOKEN) para autorizar o uso da chave. Qualquer um chamada para begin com uma chave com essa tag que não fornece uma token de autenticação ou fornece um token de autenticação sem um valor de estado da política correspondente, falha.

Essa tag pode ser repetida. Se algum dos valores fornecidos corresponder a qualquer valor de estado da política no token de autenticação, a chave será autorizada para uso. Caso contrário, a operação falhará ErrorCode::KEY_USER_NOT_AUTHENTICATED:

Tag::VENDOR_PATCHLEVEL

Versão: 4

Essa tag especifica o nível do patch de segurança da imagem do fornecedor que a chave pode ser usado. Essa tag nunca é enviada ao keymaster TA, mas é adicionada ao lista de autorização imposta por hardware pelo TA. Qualquer tentativa de usar uma chave com um Valor de Tag::VENDOR_PATCHLEVEL diferente do valor em execução no momento do sistema precisa causar begin(), getKeyCharacteristics() ou exportKey() para devolução ErrorCode::KEY_REQUIRES_UPGRADE. Consulte upgradeKey() para mais detalhes.

O valor da tag é um número inteiro no formato AAAAMMDD, em que 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 precisa ler o patchlevel atual do fornecedor da propriedade ro.vendor.build.security_patch do sistema e enviá-lo ao ambiente seguro quando o HAL for carregado pela primeira vez (o mecanismo é definido pela implementação). O ambiente seguro não pode aceitar outro patchlevel até a próxima inicialização.

Precisa ser aplicada por hardware.