Tags de autorização do Keymaster

Esta página fornece detalhes para auxiliar os implementadores de Keymaster HALs. Abrange cada tag no HAL, em qual versão do Keymaster essa tag está disponível e se a tag é repetível. Exceto conforme observado nas descrições das tags, todas as tags abaixo são usadas durante a geração da chave para especificar as características da chave.

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, as 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 hora em que a chave se torna ativa. Antes disso, 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

Essa tag é aplicável apenas a dispositivos Android Wear com sensores no corpo. Neste ponto, não se espera que qualquer TEE seja capaz de fornecer acesso seguro a um sensor no corpo ou que os sensores no corpo sejam muito seguros, portanto, espera-se que esse 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 começar precisam fornecer essa tag e os mesmos dados associados como parte do conjunto inParams . Se os dados corretos não forem fornecidos, a função retornará ErrorCode::INVALID_KEY_BLOB .

O conteúdo desta tag está vinculado à chave criptograficamente , o que significa que não deve ser possível para um adversário que tenha acesso a todos os segredos do mundo seguro, mas não tenha acesso ao conteúdo da tag, descriptografar a chave sem forçar a tag. conteúdo, que os aplicativos podem evitar especificando conteúdo de entropia suficientemente alta.

O valor é um blob, uma matriz de bytes de comprimento 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 começar precisam fornecer essa tag e os mesmos dados associados como parte do conjunto inParams . Se os dados corretos não forem fornecidos, a função retornará ErrorCode::INVALID_KEY_BLOB .

O conteúdo desta tag está vinculado à chave criptograficamente , o que significa que um adversário que pode acessar todos os segredos do mundo seguro - mas não tem acesso ao conteúdo da tag - não pode descriptografar a chave (sem forçar o conteúdo da tag ).

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

Etiqueta::ASSOCIATED_DATA

Versão : 1, 2, 3, 4

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.

Etiqueta::ATESTATION_APPLICATION_ID

Versão : 3, 4

Repetível ? Não

Usado para identificar o conjunto de aplicações possíveis das quais se iniciou um atestado de chave.

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

Etiqueta::ATESTATION_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.

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 suportar atestado de ID (ou destroyAttestationIds() foi chamado anteriormente e o dispositivo não puder mais atestar seus IDs), qualquer solicitação de atestado de chave que inclua essa tag falhará com ErrorCode::CANNOT_ATTEST_IDS .

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

Etiqueta::ATTESTATION_ID_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 suportar atestado de ID (ou destroyAttestationIds() foi chamado anteriormente e o dispositivo não puder mais atestar seus IDs), qualquer solicitação de atestado de chave que inclua essa tag falhará com ErrorCode::CANNOT_ATTEST_IDS .

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

Etiqueta::ATTESTATION_ID_IMEI

Versão : 3, 4

Repetível ? Sim

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

Se o dispositivo não suportar atestado de ID (ou destroyAttestationIds() foi chamado anteriormente e o dispositivo não puder mais atestar seus IDs), qualquer solicitação de atestado de chave que inclua essa tag falhará com ErrorCode::CANNOT_ATTEST_IDS .

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

Etiqueta::ATESTATION_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 suportar atestado de ID (ou destroyAttestationIds() foi chamado anteriormente e o dispositivo não puder mais atestar seus IDs), qualquer solicitação de atestado de chave que inclua essa tag falhará com ErrorCode::CANNOT_ATTEST_IDS .

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

Etiqueta::ATTESTATION_ID_MEID

Versão : 3, 4

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 suportar atestado de ID (ou destroyAttestationIds() foi chamado anteriormente e o dispositivo não puder mais atestar seus IDs), qualquer solicitação de atestado de chave que inclua essa tag falhará com ErrorCode::CANNOT_ATTEST_IDS .

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

Etiqueta::ATESTATION_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 suportar atestado de ID (ou destroyAttestationIds() foi chamado anteriormente e o dispositivo não puder mais atestar seus IDs), qualquer solicitação de atestado de chave que inclua essa tag falhará com ErrorCode::CANNOT_ATTEST_IDS .

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

Etiqueta::ATTESTATION_ID_PRODUCT

Versão : 3, 4

Repetível ? Não

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

Se o dispositivo não suportar atestado de ID (ou destroyAttestationIds() foi chamado anteriormente e o dispositivo não puder mais atestar seus IDs), qualquer solicitação de atestado de chave que inclua essa tag falhará com ErrorCode::CANNOT_ATTEST_IDS .

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

Etiqueta::ATTESTATION_ID_SERIAL

Versão : 3, 4

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 suportar atestado de ID (ou destroyAttestationIds() foi chamado anteriormente e o dispositivo não puder mais atestar seus IDs), qualquer solicitação de atestado de chave que inclua essa tag falhará com ErrorCode::CANNOT_ATTEST_IDS .

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

Etiqueta::AUTH_TIMEOUT

Versão : 1, 2, 3, 4

Repetível ? Não

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

O valor é um 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 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 começar , atualizar ou terminar , para provar a autenticação do usuário para uma operação de chave que a requeira (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 necessárias do ambiente do sistema 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 de chave de generateKey e getKeyCharacteristics . Se o chamador especificar Tag::BLOB_USAGE_REQUIREMENTS com o valor KeyBlobUsageRequirements::STANDALONE , o trustlet retornará um blob de chaves 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 os modos de cifra de bloco com os quais a chave pode ser usada. Essa 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 selectedmode 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 ao TA do keymaster, mas é adicionada à lista de autorizações impostas por hardware pelo TA. Qualquer tentativa de usar uma chave com um valor Tag::BOOT_PATCHLEVEL diferente do nível de patch do sistema atualmente em execução faz com que begin() , getKeyCharacteristics() ou exportKey() retorne ErrorCode::KEY_REQUIRES_UPGRADE . Consulte upgradeKey() para obter detalhes.

O valor da tag é um número inteiro no formato YYYYMMDD, onde YYYY é 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 atualizada pela última vez em 5 de junho de 2018, o valor seria 20180605. Se o dia não for conhecido, 00 poderá ser substituído.

Durante cada inicialização, o carregador de inicialização 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.

Esta tag é booleana, então 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 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 o mesmo.

Esta tag é booleana, então 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 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.

Etiqueta::DIGEST

Versão : 1, 2, 3, 4

Repetível ? Sim

Especifica os algoritmos de resumo que podem ser usados ​​com a chave para executar operações de assinatura e verificação. Essa 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 adivinhada 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 do 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 valide se o tamanho de chave especificado é 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 de chave para indicar que um certificado de atestado para a chave gerada deve conter um ID exclusivo de dispositivo com escopo de aplicativo e limitado por tempo, conforme especificado por Tag::UNIQUE_ID .

Esta tag é booleana, então os valores possíveis são true (se a tag estiver presente) e false (se a 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 de forma 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 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.

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 reinicializações do sistema. Esse é outro mecanismo para limitar o uso da chave.

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

Quando uma chave com esta tag é usada em uma operação, um contador associado à chave deve ser incrementado durante a chamada inicial . Depois que o contador de chaves exceder esse valor, todas as tentativas subsequentes de usar a chave falharão com ErrorCode::MAX_OPS_EXCEEDED , até que o dispositivo seja reiniciado. 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 em operações que tentam usar chaves com essa tag quando a tabela está cheia. A mesa precisa acomodar pelo menos 16 chaves. Se uma operação falhar porque a tabela está cheia, o Keymaster retornará ErrorCode::TOO_MANY_OPERATIONS .

Etiqueta::MIN_MAC_LENGTH

Versão : 1, 2, 3, 4

Repetível ? Não

Esta etiqueta especifica o comprimento mínimo do MAC que pode ser solicitado ou verificado com esta chave para chaves HMAC e chaves AES que suportam o modo GCM.

Este valor é o comprimento MAC mínimo, 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 de 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 o uso de chaves em contextos em que o uso ilimitado pode permitir ataques de força bruta.

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

Quando uma chave com esta tag for usada em uma operação, inicie um cronômetro durante o término ou aborte a chamada. Qualquer chamada para começar recebida antes do temporizador indica que o intervalo especificado por Tag::MIN_SECONDS_BETWEEN_OPS decorrido 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 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 de chave expirarem. Se uma operação falhar porque a tabela está cheia, o 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 essa chave. Esta tag é mutuamente exclusiva com Tag::USER_SECURE_ID .

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

Etiqueta::NOCE

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 iniciar 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 devolvido desde o início.

O valor é um blob, uma matriz de bytes de comprimento arbitrário. Os comprimentos permitidos dependem do modo: os 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 de ele ser encontrado na lista de características impostas por hardware ou por software.

GENERATED indica que o Keymaster gerou a chave. Se estiver na lista de hardware obrigatório, a chave foi gerada em hardware seguro e está permanentemente vinculada ao hardware. Se estiver na lista aplicada 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 de hardware obrigatório, ele estará permanentemente vinculado ao hardware, embora possam existir cópias fora do hardware seguro. Se estiver na lista de imposição de software, a chave foi importada para o SoftKeymaster e não está vinculada ao hardware.

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

Etiqueta::ORIGINATION_EXPIRE_DATETIME

Versão : 1, 2, 3, 4

Repetível ? Não

Especifica a data e 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 falha com ErrorCode::KEY_EXPIRED .

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

Etiqueta::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 impostas por hardware pelo TA.

O valor da tag é um número inteiro no formato YYYYMM, onde YYYY é 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 atualizada pela última vez em dezembro de 2015, o valor seria 201512.

As chaves que possuem um 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 Vinculação de versão para obter mais detalhes.

Etiqueta::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 impostas 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 secundária. Por exemplo, para uma chave gerada no Android versão 4.0.3, o valor seria 040003.

Etiqueta::PADING

Versão : 1, 2, 3, 4

Repetível ? Sim

Especifica os modos de preenchimento que podem ser usados ​​com a tecla. Essa 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 o preenchimento RSA PKCS#1v2 OAEP e o preenchimento aleatório RSA PKCS#1 v1.5, respectivamente. PaddingMode::RSA_PSS e PaddingMode::RSA_PKCS1_1_5_SIGN são usados ​​apenas para chaves de assinatura/verificação RSA e especificam o preenchimento 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 em comprimento, a chamada para concluir 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::PROPÓSITO

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 etiqueta é 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, a finalidade da operação é especificada. 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.

Esta tag é booleana, então os valores possíveis são true (se a tag estiver presente) e false (se a 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 tem a garantia de ser excluída permanentemente e inutilizável. É possível que as chaves sem essa tag possam ser excluídas e restauradas do backup.

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

Etiqueta::ROOT_OF_TRUST

Versão : 1, 2, 3, 4

Repetível ? Não

Especifica a raiz de trust , 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-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 chave falhará com ErrorCode::INVALID_ARGUMENT .

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

Etiqueta::USAGE_EXPIRE_DATETIME

Versão : 1, 2, 3, 4

Repetível ? Não

Especifica a data e hora em que a chave expira para fins de verificação e descriptografia. Após esse tempo, qualquer tentativa de usar uma chave com KeyPurpose::VERIFY ou KeyPurpose::DECRYPT fornecida para iniciar falha com ErrorCode::KEY_EXPIRED .

O valor é um 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 essa chave. Quando o Keymaster é solicitado a realizar uma operação com uma chave com essa 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 estado de autenticação de usuário seguro específico. 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 o Tag::AUTH_TOKEN ) para autorizar o uso da chave. Qualquer chamada para começar com uma chave com essa 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

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

O valor da tag é um número inteiro no formato YYYYMMDD, onde YYYY é 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 atualizada pela última vez em 5 de junho de 2018, o valor seria 20180605.

O IKeymasterDevice HAL deve ler o nível de patch do fornecedor atual da propriedade do sistema ro.vendor.build.security_patch e entregá-lo ao ambiente seguro quando o HAL for carregado pela primeira vez (o mecanismo é definido pela implementação). O ambiente seguro não deve aceitar outro nível de patch até a próxima inicialização.

Deve ser aplicado por hardware.