Tags de autorização do Keymaster

Esta página fornece detalhes para ajudar os implementadores de Keymaster HALs. Ele abrange cada tag no HAL, em 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 as características das chaves.

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 abaixo, 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

Repetível ? Não

Especifica a data e a hora em que a chave se torna ativa. Antes dessa hora, qualquer tentativa de usar a chave falha com ErrorCode::KEY_NOT_YET_VALID .

O valor é um inteiro de 64 bits representando milissegundos desde 1º de janeiro de 1970.

Etiqueta::ALGORITMO

Versão : 1, 2, 3, 4

Repetível ? Não

Especifica o algoritmo criptográfico com o qual a chave é usada.

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

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

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

Etiqueta::ALL_APPLICATIONS

Versão : 1, 2, 3, 4

Repetível ? Não

Reservado para uso futuro.

Etiqueta::ALLOW_WHILE_ON_BODY

Versão : 2, 3, 4

Repetível ? Não

Esta tag é aplicável apenas para 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 no corpo, ou que os sensores no corpo sejam muito seguros, portanto, espera-se que seja um recurso puramente imposto por software.

Etiqueta::ALL_USERS

Versão : 3, 4

Repetível ? Não

Reservado para uso futuro.

Etiqueta::APPLICATION_DATA

Versão : 1, 2, 3, 4

Repetível ? Não

Quando fornecida para 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 para um adversário que tenha acesso a todos os segredos mundiais seguros, 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 suficientemente alto de entropia.

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

Etiqueta::APPLICATION_ID

Versão : 1, 2, 3, 4

Repetível ? Não

Quando fornecida para 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 no 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 desta tag está vinculado à chave criptograficamente , o que significa que um adversário que pode acessar todos os segredos mundiais seguros - mas não tem acesso ao conteúdo da tag - não pode descriptografar a chave (sem força bruta no conteúdo da tag ).

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

Etiqueta::ASSOCIATED_DATA

Versão : 1, 2, 3, 4

Repetível ? Não

Fornece "dados associados" para criptografia ou descriptografia AES-GCM. Esta tag é fornecida para atualizar e especifica os 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 tamanho arbitrário.

Etiqueta::ATTESTATION_APPLICATION_ID

Versão : 3, 4

Repetível ? Não

Usado para identificar o conjunto de possíveis aplicativos dos quais um iniciou um atestado de chave.

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

Etiqueta::ATTESTATION_CHALLENGE

Versão : 3, 4

Repetível ? Não

Usado para fornecer desafio em atestado.

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

Etiqueta::ATTESTATION_ID_BRAND

Versão : 3, 4

Repetível ? Não

Fornece o nome da marca do dispositivo, conforme retornado por Build.BRAND no Android. Este campo é definido apenas ao solicitar a comprovação dos identificadores do dispositivo.

Se o dispositivo não for compatível com o atestado de ID (ou destroyAttestationIds() foi chamado anteriormente e o dispositivo não pode 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 tamanho arbitrário.

Etiqueta::ATTESTATION_ID_DEVICE

Versão : 3, 4

Repetível ? Não

Fornece o nome do dispositivo do dispositivo, conforme retornado por Build.DEVICE no Android. Este campo é definido apenas ao solicitar a comprovação dos identificadores do dispositivo.

Se o dispositivo não for compatível com o atestado de ID (ou destroyAttestationIds() foi chamado anteriormente e o dispositivo não pode 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 tamanho arbitrário.

Etiqueta::ATTESTATION_ID_IMEI

Versão : 3, 4

Repetível ? Sim

Fornece os IMEIs para todos os rádios do dispositivo. Este campo é definido apenas ao solicitar a comprovação dos identificadores do dispositivo.

Se o dispositivo não for compatível com o atestado de ID (ou destroyAttestationIds() foi chamado anteriormente e o dispositivo não pode 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 tamanho arbitrário.

Etiqueta::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. Este campo é definido apenas ao solicitar a comprovação dos identificadores do dispositivo.

Se o dispositivo não for compatível com o atestado de ID (ou destroyAttestationIds() foi chamado anteriormente e o dispositivo não pode 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 tamanho arbitrário.

Etiqueta::ATTESTATION_ID_MEID

Versão : 3, 4

Repetível ? Sim

Fornece os MEIDs para todos os rádios no dispositivo. Este campo só será definido ao solicitar a comprovação dos identificadores do dispositivo.

Se o dispositivo não for compatível com o atestado de ID (ou destroyAttestationIds() foi chamado anteriormente e o dispositivo não pode 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 tamanho arbitrário.

Etiqueta::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 ao solicitar a comprovação dos identificadores do dispositivo.

Se o dispositivo não for compatível com o atestado de ID (ou destroyAttestationIds() foi chamado anteriormente e o dispositivo não pode 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 tamanho arbitrário.

Etiqueta::ATTESTATION_ID_PRODUCT

Versão : 3, 4

Repetível ? Não

Fornece o nome do produto do dispositivo, conforme retornado por Build.PRODUCT no Android. Este campo é definido apenas ao solicitar a comprovação dos identificadores do dispositivo.

Se o dispositivo não for compatível com o atestado de ID (ou destroyAttestationIds() foi chamado anteriormente e o dispositivo não pode 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 tamanho arbitrário.

Etiqueta::ATTESTATION_ID_SERIAL

Versão : 3, 4

Repetível ? Não

Fornece o número de série do dispositivo. Este campo é definido apenas ao solicitar a comprovação dos identificadores do dispositivo.

Se o dispositivo não for compatível com o atestado de ID (ou destroyAttestationIds() foi chamado anteriormente e o dispositivo não pode 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 tamanho arbitrário.

Etiqueta::AUTH_TIMEOUT

Versão : 1, 2, 3, 4

Repetível ? Não

Especifica o tempo em segundos pelo qual a chave é autorizada para uso, após a autenticação. Se Tag::USER_SECURE_ID estiver presente e esta tag não, então a chave precisa de autenticação para cada uso (consulte o início para obter os detalhes do fluxo de autenticação por operação).

O valor é um inteiro de 32 bits especificando 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 em que a chave pode ser usada.

Etiqueta::AUTH_TOKEN

Versão : 1, 2, 3, 4

Repetível ? Não

Fornece um token de autenticação para begin , update ou finish , para provar a autenticação do usuário para uma operação de chave que o exija (a chave tem 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

Repetível ? 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:

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

typedef enum {
    KM_BLOB_STANDALONE = 0,
    KM_BLOB_REQUIRES_FILE_SYSTEM = 1,
} keymaster_key_blob_usage_requirements_t;

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 características-chave de generateKey e getKeyCharacteristics . Se o responsável pela chamada especificar Tag::BLOB_USAGE_REQUIREMENTS com o valor KeyBlobUsageRequirements::STANDALONE o trustlet retornará um blob de chave que pode ser usado sem suporte ao sistema de arquivos. Isso é 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

Repetível ? 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:

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

typedef enum {
    KM_MODE_ECB = 1,
    KM_MODE_CBC = 2,
    KM_MODE_CTR = 3,
    KM_MODE_GCM = 32,
} keymaster_block_mode_t;

Essa 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 de patch de segurança da imagem de inicialização (kernel) com o qual a chave pode ser usada. Essa tag nunca é enviada para o 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 patchlevel 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 pode 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

Repetível ? Não

Especifica que apenas o bootloader pode usar a chave.

Este tag é booleano, então os valores possíveis são true (se o tag estiver presente) e false (se o tag não estiver presente).

Qualquer tentativa de usar uma chave com Tag::BOOTLOADER_ONLY do sistema Android falha com ErrorCode::INVALID_KEY_BLOB .

Etiqueta::CALLER_NONCE

Versão : 1, 2, 3, 4

Repetível ? Não

Especifica que o chamador pode fornecer um nonce para operações que não requerem once.

Este tag é booleano, então os valores possíveis são true (se o tag estiver presente) e false (se o tag não estiver presente).

Esta tag é usada apenas para chaves AES e é relevante apenas para os modos de bloco CBC, CTR e GCM. Se a tag não estiver presente, as implementações devem rejeitar qualquer operação que forneça Tag::NONCE para começar com ErrorCode::CALLER_NONCE_PROHIBITED .

Etiqueta::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 apenas informativa.

Tag::DIGEST

Versão : 1, 2, 3, 4

Repetível ? Sim

Especifica os algoritmos resumidos 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:

enum class Digest : uint32_t {
    NONE = 0,
    MD5 = 1,
    SHA1 = 2,
    SHA_2_224 = 3,
    SHA_2_256 = 4,
    SHA_2_384 = 5,
    SHA_2_512 = 6,
};

typedef enum {
    KM_DIGEST_NONE = 0,
    KM_DIGEST_MD5 = 1,
    KM_DIGEST_SHA1 = 2,
    KM_DIGEST_SHA_2_224 = 3,
    KM_DIGEST_SHA_2_256 = 4,
    KM_DIGEST_SHA_2_384 = 5,
    KM_DIGEST_SHA_2_512 = 6,
}
keymaster_digest_t;

Esta etiqueta é 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

Repetível ? 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:

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

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

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 posterior, 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 confirme se o tamanho da chave especificada é apropriado para essa curva. Caso contrário, retorne ErrorCode::INVALID_ARGUMENT .

Etiqueta::INCLUDE_UNIQUE_ID

Versão : 2, 3, 4

Repetível ? Não

Essa tag é especificada durante a geração da chave para indicar que um certificado de atestado para a chave gerada deve conter um ID exclusivo de dispositivo com escopo de aplicativo e limite de tempo, conforme especificado por Tag::UNIQUE_ID .

Este tag é booleano, então os valores possíveis são true (se o tag estiver presente) e false (se o tag não estiver presente).

Etiqueta::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, especifica o comprimento do material da chave secreta.

Etiqueta::MAC_LENGTH

Versão : 1, 2, 3, 4

Repetível ? Não

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

Etiqueta::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. 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 tecla com esta tag é usada em uma operação, um contador associado à tecla deve ser incrementado durante a chamada inicial . Depois que o contador de chaves excedeu esse valor, todas as tentativas subsequentes de usar a chave falham 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 essa tag. Como a memória do Keymaster geralmente é limitada, essa tabela pode ter um tamanho máximo fixo e o Keymaster pode falhar nas 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, Keymaster retornará ErrorCode::TOO_MANY_OPERATIONS .

Etiqueta::MIN_MAC_LENGTH

Versão : 1, 2, 3, 4

Repetível ? 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.

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.

Etiqueta::MIN_SECONDS_BETWEEN_OPS

Versão : 1, 2, 3, 4

Repetível ? Não

Especifica o tempo mínimo decorrido entre as operações permitidas usando uma chave. Isso pode ser usado para limitar a taxa de uso 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 as operações permitidas.

Quando uma tecla com esta tag é usada em uma operação, inicia um cronômetro durante a chamada de término ou cancelamento . Qualquer chamada para iniciar recebida antes do cronômetro indica que o intervalo especificado por Tag::MIN_SECONDS_BETWEEN_OPS decorreu falha com ErrorCode::KEY_RATE_LIMIT_EXCEEDED . Isso implica que um trustlet mantém uma tabela de contadores de uso para chaves com essa tag. Como a memória do Keymaster geralmente é limitada, essa tabela pode ter um tamanho máximo fixo e o Keymaster pode falhar nas 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 da tabela quando os intervalos mínimos de uso da chave 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

Repetível ? Não

Especifica que nenhuma autenticação é necessária para usar esta chave. Esta tag é mutuamente exclusiva com Tag::USER_SECURE_ID .

Este tag é booleano, então os valores possíveis são true (se o tag estiver presente) e false (se o tag não estiver presente).

Etiqueta::NONCE

Versão : 1, 2, 3, 4

Repetível ? 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 começar durante as operações de criptografia e descriptografia. Só é fornecido para iniciar 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 tamanho arbitrário. Os comprimentos permitidos dependem do modo: nonces 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

Repetível ? 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.

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

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á localizado 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, está 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 originalmente gerada em hardware seguro ou se foi importada. Isso ocorre apenas quando o hardware keymaster0 está sendo usado para emular os serviços keymaster1.

Etiqueta::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 fins de assinatura e criptografia. Após esse período, qualquer tentativa de usar uma chave com KeyPurpose::SIGN ou KeyPurpose::ENCRYPT fornecida para iniciar falhará com ErrorCode::KEY_EXPIRED .

O valor é um inteiro de 64 bits representando milissegundos desde 1º de janeiro de 1970.

Tag::OS_PATCHLEVEL

Versão : 2, 3, 4

Repetível ? Não

Essa tag nunca é enviada para o 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.

Teclas com nível de patch diferente do nível de patch atual não podem ser usadas. 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

Repetível ? Não

Essa tag nunca é enviada para o 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

Repetível ? Sim

Especifica os modos de preenchimento que podem ser usados ​​com a tecla. Esta tag é relevante para chaves RSA e AES.

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

enum class PaddingMode : uint32_t {
    NONE = 1,
    RSA_OAEP = 2,
    RSA_PSS = 3,
    RSA_PKCS1_1_5_ENCRYPT = 4,
    RSA_PKCS1_1_5_SIGN = 5,
    PKCS7 = 64,
};

typedef enum {
    KM_PAD_NONE = 1,
    KM_PAD_RSA_OAEP = 2,
    KM_PAD_RSA_PSS = 3,
    KM_PAD_RSA_PKCS1_1_5_ENCRYPT = 4,
    KM_PAD_RSA_PKCS1_1_5_SIGN = 5,
    KM_PAD_PKCS7 = 64,
} keymaster_padding_t;

PaddingMode::RSA_OAEP e PaddingMode::RSA_PKCS1_1_5_ENCRYPT são usados ​​apenas para chaves de criptografia/descriptografia RSA e especificam preenchimento RSA PKCS#1v2 OAEP e 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 RSA PKCS#1v2 PSS 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 etiqueta é repetível. 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 falhará com ErrorCode::INCOMPATIBLE_BLOCK_MODE .

Etiqueta::PURPOSE

Versão : 1, 2, 3, 4

Repetível ? 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:

enum class KeyPurpose : uint32_t {
    ENCRYPT = 0,
    DECRYPT = 1,
    SIGN = 2,
    VERIFY = 3,
    DERIVE_KEY = 4,  // since 3.0
    WRAP_KEY = 5,    // since 3.0
};

typedef enum {
    KM_PURPOSE_ENCRYPT = 0,
    KM_PURPOSE_DECRYPT = 1,
    KM_PURPOSE_SIGN = 2,
    KM_PURPOSE_VERIFY = 3,
} keymaster_purpose_t;

Esta marca é repetível; as chaves podem ser geradas com vários valores, embora uma operação tenha um único propósito. Quando a função begin é 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

Repetível ? Não

Especifica se o dispositivo foi redefinido de fábrica desde a última rotação de ID exclusiva. Usado para atestado de chave.

Este tag é booleano, então os valores possíveis são true (se o tag estiver presente) e false (se o tag não estiver presente).

Etiqueta::ROLLBACK_RESISTANT

Versão : 1, 2, 3, 4

Repetível ? Não

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

Este tag é booleano, então os valores possíveis são true (se o tag estiver presente) e false (se o tag não estiver presente).

Etiqueta::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 o sistema operacional inicializado (se houver). Esta tag nunca é fornecida ou retornada pelo Keymaster nas características da chave.

Etiqueta::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 inteiro sem sinal de 64 bits que atende aos requisitos de um expoente público RSA. Este valor tem que 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 chaves falhará com ErrorCode::INVALID_ARGUMENT .

Etiqueta::UNIQUE_ID

Versão : 3, 4

Repetível ? Não

Usado para fornecer ID exclusivo no atestado.

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

Etiqueta::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 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 iniciar falhará com ErrorCode::KEY_EXPIRED .

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

Etiqueta::USER_AUTH_TYPE

Versão : 1, 2, 3, 4

Repetível ? Não

Especifica os tipos de autenticadores de usuário que podem ser usados ​​para autorizar esta chave. Quando o Keymaster é solicitado a executar 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 na tag. Por exemplo, (ntoh(token.authenticator_type) & auth_type_tag_value) != 0 , em que ntoh é uma função que converte inteiros ordenados pela rede em inteiros ordenados pelo host e auth_type_tag_value é o valor dessa tag.

O valor é uma máscara de bits inteira de 32 bits de valores da enumeração:

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

typedef enum {
    HW_AUTH_NONE = 0,
    HW_AUTH_PASSWORD = 1 << 0,
    HW_AUTH_FINGERPRINT = 1 << 1,
    // Additional entries should be powers of 2.
    HW_AUTH_ANY = UINT32_MAX,
} hw_authenticator_type_t;

Etiqueta::USER_SECURE_ID

Versão : 1, 2, 3, 4

Repetível ? Não

Especifica que uma chave só pode ser usada em um determinado estado de autenticação de usuário seguro. Esta tag é mutuamente exclusiva com Tag::NO_AUTH_REQUIRED .

O valor é um 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 etiqueta é 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 do patch de segurança da imagem do fornecedor com o qual a chave pode ser usada. Essa tag nunca é enviada para o keymaster TA, 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 patchlevel 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 IKeymasterDevice HAL 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 patchlevel até a próxima inicialização.

Deve ser aplicado por hardware.