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 se torna ativa. Antes deste qualquer tentativa de usar a chave com ErrorCode::KEY_NOT_YET_VALID:

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

Tag::ALGORITMO

Versão: 1, 2, 3, 4

Repetí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 (link em inglês)

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 se aplica apenas a dispositivos Android Wear com sensores no bolso. Em nenhum TEE será capaz de fornecer 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 fornecido para generateKey (link em inglês) 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 para o parâmetro clientId e chamar começar precisa fornecer essa tag e os mesmos dados associados como parte do inParams definido. 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 aplicativos 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 fornecido para generateKey (link em inglês) 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 da inParams definido. Se os dados corretos não forem fornecidos, a função retorna ErrorCode::INVALID_KEY_BLOB.

O conteúdo dessa tag está vinculado à chave criptograficamente, ou seja, um adversário que consegue acessar todos os segredos do mundo seguro, não tem acesso ao conteúdo da tag ou não pode descriptografar (sem forçar bruto o conteúdo da tag).

O valor é um blob, uma matriz de bytes de tamanho 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 é fornecido para update e especifica dados que não estão criptografados/descriptografados, mas são usados na computação tag GCM.

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

Tag::ATTESTATION_APPLICATION_ID

Versão: 3, 4

Repetível? Não

Usado para identificar o conjunto de possíveis aplicações de qual 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 um desafio no atestado.

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

Tag::ATTESTATION_ID_BRAND

Versão: 3, 4

Repetível? Não

Informa o nome da marca do dispositivo, conforme retornado por Build.BRAND no Android. Este campo é definido apenas ao solicitar o atestado da 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_DEVICE

Versão: 3, 4

Repetível? Não

Informa o nome do dispositivo, conforme retornado por Build.DEVICE. no Android. Este campo é definido apenas ao solicitar o atestado da 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_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

Repetível? Não

Fornece o nome do fabricante do dispositivo, conforme retornado por Build.MANUFACTURER no Android. Esse campo é definido apenas quando solicitando 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_MEID

Versão: 3, 4

Repetível? Sim

Fornece os MEIDs para todos os rádios no dispositivo. Esse campo só será definido 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_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() 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_PRODUCT

Versão: 3, 4

Repetível? Não

Informa o nome do produto do dispositivo, conforme retornado por Build.PRODUCT no Android. Esse campo é definido apenas quando solicitando 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_SERIAL

Versão: 3, 4

Repetível? Não

Informa o número de série do dispositivo. Esse campo é definido apenas quando solicitando 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::AUTH_TIMEOUT

Versão: 1, 2, 3, 4

Repetível? Não

Especifica o tempo em segundos durante o qual a chave é autorizada para uso, após 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 especificado por Tag::USER_SECURE_ID com o método de autenticação especificado por Tag::USER_AUTH_TYPE que a chave pode ser usados.

Tag::AUTH_TOKEN

Versão: 1, 2, 3, 4

Repetível? Não

Oferece um autenticação token para begin update ou concluir, para comprovar a autenticação do usuário em uma operação de chave que exige ele (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 valor KeyBlobUsageRequirements::STANDALONE o trustlet retorna um blob de chave que pode ser usado sem suporte ao sistema de arquivos. Isso é fundamental para dispositivos com discos criptografados, em que o sistema de arquivos pode ficar indisponível até depois que uma chave do Keymaster é 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 os quais a chave pode ser usada. Essa tag só é relevante 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, o falha com ErrorCode::INCOMPATIBLE_BLOCK_MODE.

Tag::BOOT_PATCHLEVEL

Versão: 4

Tag::BOOT_PATCHLEVEL especifica o nível do 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 atualizado pela última vez em 5 de junho de 2018. O valor seria 20180605. Se o dia for desconhecido, o valor 00 pode ser substituído.

Durante cada inicialização, o carregador precisa fornecer o nível do 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

Repetível? Não

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

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).

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 somente para chaves AES e só é relevante para CBC, CTR e GCM. modos de bloco. 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 1o de janeiro de 1970. Essa tag é opcional e apenas informativa.

Tag::DIGEST

Versão: 1, 2, 3, 4

Repetível? Sim

Especifica os algoritmos de resumo que podem ser usados com a chave para executar assinaturas e verificações. Essa tag é relevante para RSA, ECDSA e Chaves HMAC.

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

Keymaster 3 (link em inglês)

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, o falha 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 foi adivinhada com base na chave especificada tamanho. 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 (link em inglês)

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 contiver apenas Tag::EC_CURVE, use o curva especificada. Para o Keymaster 3 e versões mais recentes, as curvas são definidas em EcCurve: Para o 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 um escopo do aplicativo e ID exclusivo do dispositivo com limite de tempo, conforme especificado por Tag::UNIQUE_ID

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::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 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

Repetí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 com pelo menos tão grande quanto o valor de Tag::MIN_MAC_LENGTH. associados à 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 o sistema é reinicializado. 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 deve ser incrementada 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 implica que um trustlet mantém uma tabela de contadores de uso para chaves com este tag. Como a memória do Keymaster é muitas vezes limitada, essa tabela pode ter um valor fixo tamanho máximo, e o Keymaster pode falhar em operações que tentam usar chaves com dessa tag quando a tabela estiver 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 tamanho mínimo do MAC que pode ser solicitado ou verificada com essa chave para chaves HMAC e chaves AES compatíveis com o modo GCM.

Esse valor é o comprimento mínimo de 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 do 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 os segundos entre o número as operações.

Quando uma chave com essa tag for usada em uma operação, inicie um timer. durante o final ou abort. Qualquer um chamada para begin que é recebida antes do timer indica que o intervalo especificado pelo Tag::MIN_SECONDS_BETWEEN_OPS decorridos falha 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 é muitas vezes limitada, essa tabela pode ter um valor máximo fixo e o Keymaster pode falhar em operações que tentam usar chaves com essa tag quando a tabela estiver cheia. A tabela precisa acomodar pelo menos 32 em uso e reutilizar os slots de tabela quando os intervalos de uso mínimo de chaves 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 exclusivo com Tag::USER_SECURE_ID.

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::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 AES GCM, CBC, ou a criptografia e descriptografia de CTR. Essa tag é fornecida para começar durante operações de criptografia e descriptografia. Ele é fornecido apenas para começar se a chave tiver Tag::CALLER_NONCE. Caso contrário, um valor de uso único apropriado ou IV será gerado aleatoriamente pelo Keymaster e retornadas do início.

O valor é um blob, uma matriz de bytes de tamanho arbitrário. Durações permitidas dependem do modo: 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 conhecido. Esta tag não pode ser especificada durante a geração ou importação de chaves e precisam ser adicionadas às características pelo fiel.

Keymaster 3 (link em inglês)

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 não depende apenas dele, mas se ela for encontrada na lista de características impostas 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 dentro do 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 protegido. Se, no lista de aplicações de software, a chave foi importada para o SoftKeymaster e não vinculado ao hardware.

UNKNOWN só vai aparecer na lista de restrições de hardware. Ela indica que a chave é vinculado por hardware, mas não se sabe se a chave foi originalmente gerada em hardware protegido ou foi importado. 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. Depois disso, qualquer tentativa de usar uma chave com KeyPurpose::SIGN ou KeyPurpose::ENCRYPT (fornecido) falha ao começar com ErrorCode::KEY_EXPIRED.

O valor é um número inteiro de 64 bits que representa milissegundos, pois 1o de janeiro de 1970.

Tag::OS_PATCHLEVEL

Versão: 2, 3, 4

Repetível? Não

Essa tag nunca é enviada ao keymaster TA, mas é adicionada ao lista de autorização imposta por 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 atualizado pela última vez em dezembro de 2015, o valor seria 201.512.

As chaves com um nível de patch diferente do atual não são utilizáveis. Uma tentativa de usar essa chave causa começar, getKeyCharacteristics, ou exportKey para retornar 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 keymaster TA, mas é adicionada ao lista de autorização imposta por 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 no Android 4.0.3, o valor seria 040003.

Tag::PADDING

Versão: 1, 2, 3, 4

Repetível? Sim

Especifica os modos de padding 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 (link em inglês)

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 for múltiplo do tamanho do bloco AES, a chamada para finalizar falha com ErrorCode::INVALID_INPUT_LENGTH.

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

Essa tag pode ser repetida. Um modo de preenchimento deve ser especificado na chamada para começar. 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 de ID exclusivo. Usado para atestado de chaves.

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::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 é relevantes apenas para chaves RSA e necessárias para todas as chaves RSA.

O valor é um número inteiro não assinado de 64 bits que satisfaz os requisitos de uma Expoente público RSA. Esse valor precisa ser um número primo. Os Trustlets dão suporte à valor 2^16+1 e podem aceitar outros valores razoáveis, em especial o valor 3. Se nenhum expoente for especificado ou se não houver suporte para esse expoente, 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 tamanho 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, pois 1o 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 para inteiros ordenados pelo host e auth_type_tag_value é o valor da tag.

O valor é uma máscara de bits inteira de 32 bits de 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 só pode ser usada com um usuário seguro específico o estado de autenticação. Esta tag é mutuamente exclusiva com Tag::NO_AUTH_REQUIRED.

O valor é um número inteiro de 64 bits que especifica o estado da política de autenticação que precisa estar presente em um token de autenticação (fornecido ao comece 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 um 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 política no token de autenticação, a chave tem autorização 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 com que a chave podem ser usados. 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 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 atualizado pela última vez em 5 de junho de 2018. O valor seria 20180605.

A HAL IKeymasterDevice precisa ler o nível de patch do fornecedor atual no sistema. propriedade ro.vendor.build.security_patch e a entregue ao um ambiente seguro quando a HAL é carregada pela primeira vez (o mecanismo é definido pela implementação). O ambiente seguro não pode aceitar outra de nível de patch até a próxima inicialização.

Precisa ser aplicada por hardware.