Esta página fornece detalhes para ajudar os implementadores de HALs do Keymaster. Abrange cada tag na HAL, qual versão do Keymaster essa tag está disponível e se a tag pode ser repetida. Exceto conforme indicado nas descrições das tags, Todas as tags abaixo são usadas durante a geração de chaves para especificar e as características determinantes.
Para o Keymaster 4, as tags são definidas em
platform/hardware/interfaces/keymaster/keymaster-version/types.hal
,
como
3.0/types.hal para o Keymaster 3 e
4.0/types.hal para o Keymaster 4. No Keymaster 2 e versões anteriores, as tags são definidas em
platform/hardware/libhardware/include/hardware/keymaster_defs.h
:
Para funções, consulte a Página Keymaster Functions.
Tag::ACTIVE_DATETIME
Versão: 1, 2, 3, 4
Repetível? Não
Especifica a data e a hora em que a chave vai ser ativada. Antes desse
período, qualquer tentativa de uso da chave falha com
ErrorCode::KEY_NOT_YET_VALID
.
O valor é um número inteiro de 64 bits que representa milissegundos desde 1º de janeiro de 1970.
Tag::ALGORITMO
Versão: 1, 2, 3, 4
Reproduzível? Não
Especifica o algoritmo criptográfico com que a chave é usada.
Os valores possíveis são definidos pela seguinte enumeração:
Keymaster 3enum 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;
Tag::ALL_APPLICATIONS
Versão: 1, 2, 3, 4
Repetível? Não
Reservado para uso futuro.
Tag::ALLOW_WHILE_ON_BODY
Versão: 2, 3, 4
Repetível? Não
Essa tag é aplicável apenas a dispositivos Android Wear com sensores no corpo. Em nenhum TEE pode oferecer acesso seguro a um sensor corporal ou que os sensores no corpo são muito seguros, então seja simplesmente aplicado por software.
Marcar::ALL_USERS
Versão: 3, 4
Repetível? Não
Reservado para uso futuro.
Tag::APPLICATION_DATA
Versão: 1, 2, 3, 4
Repetível? Não
Quando fornecida a
generateKey
ou importKey,
essa tag especifica os dados necessários durante todos os usos da chave. Em
particular, as chamadas para
exportKey e
getKeyCharacteristics
precisam fornecer o mesmo valor para o parâmetro clientId
, e as chamadas
para begin precisam fornecer
essa tag e os mesmos dados associados como parte do conjunto
inParams
. Se os dados corretos não forem fornecidos, a função retornará
ErrorCode::INVALID_KEY_BLOB
.
O conteúdo dessa tag está vinculado à chave criptograficamente, o que significa que não deve ser possível que um adversário com acesso a todos os segredos mundiais seguros, mas não tem acesso ao conteúdo da tag para descriptografar a sem forçar brutalmente o conteúdo da tag, o que os apps podem evitar ao especificando conteúdo com entropia alta o suficiente.
O valor é um blob, uma matriz de bytes de tamanho arbitrário.
Tag::APPLICATION_ID
Versão: 1, 2, 3, 4
Repetível? Não
Quando fornecida a
generateKey
ou importKey,
essa tag especifica os dados necessários durante todos os usos da chave. Em
especialmente chamadas
exportKey e
getKeyCharacteristics (em inglês)
fornecer o mesmo valor no parâmetro clientId
;
chamadas para begin precisam
forneça essa tag e os mesmos dados associados como parte
inParams
definido. Se os dados corretos não forem fornecidos, a função
retorna ErrorCode::INVALID_KEY_BLOB
.
O conteúdo dessa tag é vinculado à chave criptograficamente, o que significa que um invasor que pode acessar todos os segredos do mundo seguro, mas não tem acesso ao conteúdo da tag, não pode descriptografar a chave sem usar força bruta no conteúdo da tag.
O valor é um blob, uma matriz de bytes de comprimento arbitrário.
Tag::ASSOCIATED_DATA
Versão: 1, 2, 3, 4
Repetível? Não
Fornece "dados associados" para criptografia ou descriptografia AES-GCM. Essa tag é fornecida para atualizar e especifica dados que não são criptografados/descriptografados, mas são usados no cálculo da tag GCM.
O valor é um blob, uma matriz de bytes de comprimento arbitrário.
Tag::ATTESTATION_APPLICATION_ID
Versão: 3, 4
Repetível? Não
Usado para identificar o conjunto de possíveis apps de qual deles iniciou um atestado de chaves.
O valor é um blob, uma matriz de bytes de tamanho arbitrário.
Tag::ATTESTATION_CHALLENGE
Versão: 3, 4
Repetível? Não
Usado para fornecer desafio no atestado.
O valor é um blob, uma matriz de bytes de comprimento arbitrário.
Tag::ATTESTATION_ID_BRAND
Versão: 3, 4
Reproduzível? Não
Informa o nome da marca do dispositivo, conforme retornado por Build.BRAND
no Android. Esse campo é definido apenas quando a solicitação de atestado dos
identificadores do dispositivo é feita.
Se o dispositivo não oferecer suporte ao atestado de ID (ou
destroyAttestationIds()
já foi chamado, e o dispositivo pode
não atestar mais seus IDs), qualquer solicitação de atestado de chaves que inclua
essa tag vai falhar com ErrorCode::CANNOT_ATTEST_IDS
.
O valor é um blob, uma matriz de bytes de comprimento arbitrário.
Tag::ATTESTATION_ID_DEVICE
Versão: 3, 4
Repetível? Não
Fornece o nome do dispositivo, conforme retornado por Build.DEVICE
no Android. Esse campo é definido apenas quando a solicitação de atestado dos
identificadores do dispositivo é feita.
Se o dispositivo não oferecer suporte ao atestado de ID (ou
destroyAttestationIds()
já foi chamado, e o dispositivo pode
não atestar mais seus IDs), qualquer solicitação de atestado de chaves que inclua
essa tag vai falhar com ErrorCode::CANNOT_ATTEST_IDS
.
O valor é um blob, uma matriz de bytes de tamanho arbitrário.
Tag::ATTESTATION_ID_IMEI
Versão: 3, 4
Repetível? Sim
Informa os IMEIs de todos os rádios no dispositivo. Este campo é definido apenas ao solicitar o atestado dos identificadores do dispositivo.
Se o dispositivo não oferecer suporte ao atestado de ID (ou
destroyAttestationIds()
já foi chamado, e o dispositivo pode
não atestar mais seus IDs), qualquer solicitação de atestado de chaves que inclua
essa tag vai falhar com ErrorCode::CANNOT_ATTEST_IDS
.
O valor é um blob, uma matriz de bytes de tamanho arbitrário.
Tag::ATTESTATION_ID_MANUFACTURER
Versão: 3, 4
Reproduzível? Não
Fornece o nome do fabricante do dispositivo, conforme retornado por
Build.MANUFACTURER
no Android. Este campo é definido apenas quando
solicitando o atestado dos identificadores do dispositivo.
Se o dispositivo não oferecer suporte ao atestado de ID (ou
destroyAttestationIds()
tiver sido chamado anteriormente e o dispositivo não
poder mais atestar os IDs), qualquer solicitação de atestado de chave que inclua
essa tag vai falhar com ErrorCode::CANNOT_ATTEST_IDS
.
O valor é um blob, uma matriz de bytes de comprimento arbitrário.
Tag::ATTESTATION_ID_MEID
Versão: 3, 4
Repetível? Sim
Fornece os MEIDs de todos os rádios no dispositivo. Este campo é definido apenas ao solicitar o atestado dos identificadores do dispositivo.
Se o dispositivo não oferecer suporte ao atestado de ID (ou
destroyAttestationIds()
já foi chamado, e o dispositivo pode
não atestar mais seus IDs), qualquer solicitação de atestado de chaves que inclua
essa tag vai falhar com ErrorCode::CANNOT_ATTEST_IDS
.
O valor é um blob, uma matriz de bytes de comprimento arbitrário.
Tag::ATTESTATION_ID_MODEL
Versão: 3, 4
Repetível? Não
Fornece o nome do modelo do dispositivo, conforme retornado por
Build.MODEL
no Android. Este campo é definido apenas quando
solicitando o atestado dos identificadores do dispositivo.
Se o dispositivo não oferecer suporte ao atestado de ID (ou
destroyAttestationIds()
tiver sido chamado anteriormente e o dispositivo não
poder mais atestar os IDs), qualquer solicitação de atestado de chave que inclua
essa tag vai falhar com ErrorCode::CANNOT_ATTEST_IDS
.
O valor é um blob, uma matriz de bytes de comprimento arbitrário.
Tag::ATTESTATION_ID_PRODUCT
Versão: 3, 4
Reproduzível? Não
Fornece o nome do produto do dispositivo, conforme retornado por
Build.PRODUCT
no Android. Esse campo é definido apenas ao
solicitar atestado dos identificadores do dispositivo.
Se o dispositivo não oferecer suporte ao atestado de ID (ou
destroyAttestationIds()
tiver sido chamado anteriormente e o dispositivo não
poder mais atestar os IDs), qualquer solicitação de atestado de chave que inclua
essa tag vai falhar com ErrorCode::CANNOT_ATTEST_IDS
.
O valor é um blob, uma matriz de bytes de tamanho arbitrário.
Tag::ATTESTATION_ID_SERIAL
Versão: 3, 4
Repetível? Não
Informa o número de série do dispositivo. Esse campo é definido apenas ao solicitar atestado dos identificadores do dispositivo.
Se o dispositivo não oferecer suporte ao atestado de ID (ou
destroyAttestationIds()
tiver sido chamado anteriormente e o dispositivo não
poder mais atestar os IDs), qualquer solicitação de atestado de chave que inclua
essa tag vai falhar com ErrorCode::CANNOT_ATTEST_IDS
.
O valor é um blob, uma matriz de bytes de comprimento arbitrário.
Tag::AUTH_TIMEOUT
Versão: 1, 2, 3, 4
Repetível? Não
Especifica o tempo em segundos em que a chave está autorizada para uso após a autenticação. Se Tag::USER_SECURE_ID estiver presente e esta tag não estiver, a chave precisará de autenticação para cada do uso (consulte início para detalhes do fluxo de autenticação por operação).
O valor é um número inteiro de 32 bits que especifica o tempo em segundos após uma autenticação bem-sucedida do usuário especificada por Tag::USER_SECURE_ID com o método de autenticação especificado por Tag::USER_AUTH_TYPE que a chave pode ser usada.
Tag::AUTH_TOKEN
Versão: 1, 2, 3, 4
Repetível? Não
Fornece um token de autenticação para iniciar, atualizar ou finalizar, para provar a autenticação do usuário para uma operação de chave que a exige (a chave tem Tag::USER_SECURE_ID).
O valor é um blob que contém uma estrutura hw_auth_token_t
.
Tag::BLOB_USAGE_REQUIREMENTS
Versão: 1, 2, 3, 4
Repetível? Não
Especifica as condições de ambiente necessárias do sistema para o a ser usada.
Os valores possíveis são definidos pela seguinte enumeração:
Keymaster 3 (link em inglês)enum class KeyBlobUsageRequirements : uint32_t { STANDALONE = 0, REQUIRES_FILE_SYSTEM = 1, };
typedef enum { KM_BLOB_STANDALONE = 0, KM_BLOB_REQUIRES_FILE_SYSTEM = 1, } keymaster_key_blob_usage_requirements_t;
Essa tag pode ser especificada durante a geração da chave para exigir que a chave seja
utilizável na condição especificada. Ela precisa ser retornada com a chave
características
generateKey e
getKeyCharacteristics.
Se o autor da chamada especificar Tag::BLOB_USAGE_REQUIREMENTS
com
o valor KeyBlobUsageRequirements::STANDALONE
, o trustlet vai retornar um blob de chave
que pode ser usado sem suporte ao sistema de arquivos. Isso é essencial para dispositivos
com discos criptografados, em que o sistema de arquivos pode não estar disponível até
que uma chave Keymaster seja usada para descriptografar o disco.
Tag::BLOCK_MODE
Versão: 1, 2, 3, 4
Repetível? Sim
Especifica os modos de cifra de bloco com que a chave pode ser usada. Essa tag é relevante apenas para chaves AES.
Os valores possíveis são definidos pela seguinte enumeração:
Keymaster 3 (link em inglês)enum class BlockMode : uint32_t { ECB = 1, CBC = 2, CTR = 3, GCM = 32, };
typedef enum { KM_MODE_ECB = 1, KM_MODE_CBC = 2, KM_MODE_CTR = 3, KM_MODE_GCM = 32, } keymaster_block_mode_t;
Essa tag pode ser repetida, e para operações de chave AES especifique um modo no
o argumento additionalParams
de
começar.
Se o modo especificado não estiver nos modos associados à chave, a
operação falhará com ErrorCode::INCOMPATIBLE_BLOCK_MODE
.
Tag::BOOT_PATCHLEVEL
Versão: 4
Tag::BOOT_PATCHLEVEL especifica o nível de patch de segurança da imagem de inicialização (kernel)
com que a chave pode ser usada. Essa tag nunca é enviada ao keymaster TA, mas
é adicionada à lista de autorizações impostas por hardware pelo TA. Qualquer tentativa de
use uma chave com um valor Tag::BOOT_PATCHLEVEL
diferente do
atualmente em execução no nível do patch do sistema causa begin()
,
getKeyCharacteristics()
ou exportKey()
para devolução
ErrorCode::KEY_REQUIRES_UPGRADE
. Consulte upgradeKey()
para mais detalhes.
O valor da tag é um número inteiro no formato AAAAMMDD, em que AAAA é o ano com quatro dígitos da última atualização, MM é o mês com dois dígitos e DD é o dia de dois dígitos da última atualização. Por exemplo, para uma chave gerada em um dispositivo Android atualizada pela última vez em 5 de junho de 2018, o valor seria 20180605. Se o dia não for conhecido, 00 pode ser substituído.
Durante cada inicialização, o carregador de inicialização precisa fornecer o nível de patch da imagem de inicialização ao ambiente seguro (o mecanismo é definido pela implementação).
Precisa ser aplicada por hardware.
Tag::BOOTLOADER_ONLY
Versão: 1, 2, 3, 4
Reproduzível? Não
Especifica que apenas o carregador de inicialização pode usar a chave.
Essa tag é booleana, então os valores possíveis são verdadeiro (se a tag estiver presente) e falso (se a tag não estiver presente).
Qualquer tentativa de usar uma chave com Tag::BOOTLOADER_ONLY
do
O sistema Android falha com ErrorCode::INVALID_KEY_BLOB
.
Tag::CALLER_NONCE
Versão: 1, 2, 3, 4
Repetível? Não
Especifica que o autor da chamada pode fornecer um valor de uso único para operações que exigem valor de uso único.
Essa tag é booleana. Portanto, os valores possíveis são "true" (se a tag estiver presente). e "false" (se a tag não estiver presente).
Essa tag é usada apenas para chaves AES e é relevante apenas para os modos de bloqueio CBC, CTR e GCM. Se a tag não estiver presente, as implementações deverão rejeitar todas as
operação que fornece Tag::NONCE para
início
com ErrorCode::CALLER_NONCE_PROHIBITED
.
Tag::CREATION_DATETIME
Versão: 1, 2, 3, 4
Repetível? Não
Especifica a data e a hora em que a chave foi criada, em milissegundos desde 1º de janeiro de 1970. Essa tag é opcional e serve apenas para fins informativos.
Tag::DIGEST
Versão: 1, 2, 3, 4
Repetível? Sim
Especifica os algoritmos de resumo que podem ser usados com a chave para realizar operações de assinatura e verificação. Essa tag é relevante para RSA, ECDSA e Chaves HMAC.
Os valores possíveis são definidos pela seguinte enumeração:
Keymaster 3enum 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;
Essa tag pode ser repetida. Para operações de assinatura e verificação, especifique
um resumo no argumento additionalParams
de
começar.
Se o resumo especificado não estiver nos resumos associados à chave, a
operação falhará com ErrorCode::INCOMPATIBLE_DIGEST
.
Tag::EC_CURVE
Versão: 2, 3, 4
Repetível? Não
No Keymaster 1, a curva usada para chaves EC era adivinhada com base no tamanho
especificado. Para melhorar a flexibilidade no futuro, o Keymaster 2 introduziu uma
de especificar curvas. As solicitações de geração de chaves de EC podem ter
Tag::EC_CURVE
, Tag::KEY_SIZE
ou ambos.
Os valores possíveis são definidos pela seguinte enumeração:
Keymaster 3enum 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 só contiver Tag::KEY_SIZE
,
voltar à lógica do Keymaster 1 e escolher a curva NIST adequada.
Se a solicitação tiver apenas Tag::EC_CURVE
, use a
curva especificada. Para o Keymaster 3 e versões mais recentes, as curvas são definidas em
EcCurve
. Para Keymaster 2 e versões anteriores, as curvas são definidas
em keymaster_ec_curve_t
.
Se a solicitação contiver ambos, use a curva especificada por
Tag::EC_CURVE
e validar se o tamanho de chave especificado é
apropriada para a curva. Caso contrário, retorne
ErrorCode::INVALID_ARGUMENT
.
Tag::INCLUDE_UNIQUE_ID
Versão: 2, 3, 4
Repetível? Não
Essa tag é especificada durante a geração de chaves para indicar que um atestado da chave gerada deve conter uma string com escopo do app ID exclusivo do dispositivo com limite de tempo, conforme especificado por Tag::UNIQUE_ID
Essa tag é booleana, então os valores possíveis são verdadeiro (se a tag estiver presente) e falso (se a tag não estiver presente).
Tag::KEY_SIZE
Versão: 1, 2, 3, 4
Repetível? Não
Especifica o tamanho, em bits, da chave, medindo da maneira normal para o
algoritmo da chave. Por exemplo, para chaves RSA, Tag::KEY_SIZE
especifica
o tamanho do módulo público. Para chaves AES, ele especifica o comprimento
do material da chave secreta.
Tag::MAC_LENGTH
Versão: 1, 2, 3, 4
Reproduzível? Não
Fornece o comprimento solicitado de uma tag de autenticação MAC ou GCM, em bits.
O valor é o comprimento MAC em bits. É um múltiplo de 8 e pelo menos tão grande quanto o valor de Tag::MIN_MAC_LENGTH associado à chave.
Tag::MAX_USES_PER_BOOT
Versão: 1, 2, 3, 4
Repetível? Não
Especifica o número máximo de vezes que uma chave pode ser usada entre as reinicializações do sistema. Esse é outro mecanismo para limitar a taxa do uso de chaves.
O valor é um número inteiro de 32 bits que representa os usos por inicialização.
Quando uma chave com essa tag é usada em uma operação, um contador associado à chave
precisa ser incrementado durante a chamada
begin. Após a chave
o contador tiver excedido esse valor, todas as tentativas subsequentes de usar a chave falharão
com ErrorCode::MAX_OPS_EXCEEDED
até que o dispositivo seja reiniciado.
Isso indica que um trustlet mantém uma tabela de contadores de uso para chaves com este
tag. Como a memória do Keymaster geralmente é limitada, essa tabela pode ter um tamanho máximo fixo, e o Keymaster pode falhar em operações que tentam usar chaves com essa tag quando a tabela está cheia. A tabela precisa acomodar pelo menos 16 chaves.
Se uma operação falhar porque a tabela está cheia, o Keymaster retornará
ErrorCode::TOO_MANY_OPERATIONS
:
Tag::MIN_MAC_LENGTH
Versão: 1, 2, 3, 4
Repetível? Não
Essa tag especifica o comprimento mínimo de MAC que pode ser solicitado ou verificado com essa chave para chaves HMAC e AES que oferecem suporte ao modo GCM.
Esse valor é o comprimento mínimo do MAC, em bits. É um múltiplo de 8. Para chaves HMAC, o valor é de pelo menos 64. Para chaves GCM, o valor é de pelo menos 96 e não mais que 128.
Tag::MIN_SECONDS_BETWEEN_OPS
Versão: 1, 2, 3, 4
Repetível? Não
Especifica o período mínimo decorrido entre o intervalo permitido operações usando uma chave. Isso pode ser usado para limitar a taxa de usos de chaves em contextos em que o uso ilimitado pode permitir ataques de força bruta.
O valor é um número inteiro de 32 bits que representa segundos entre as operações permitidas.
Quando uma chave com essa tag é usada em uma operação, inicie um timer
durante a chamada finish ou
abort. Qualquer
chamada para begin que seja
recebida antes que o timer indique que o intervalo especificado por
Tag::MIN_SECONDS_BETWEEN_OPS
tenha decorrido falhará com
ErrorCode::KEY_RATE_LIMIT_EXCEEDED
. Isso
implica que um trustlet mantém uma tabela de contadores de uso para chaves com esta tag.
Como a memória do Keymaster geralmente é limitada, essa tabela pode ter um tamanho máximo fixo
e o Keymaster pode falhar em operações que tentam usar chaves com essa tag
quando a tabela está cheia. A tabela precisa acomodar pelo menos 32 chaves em uso
e reutilizar agressivamente os slots de tabela quando os intervalos de uso mínimo da chave expirarem.
Se uma operação falhar porque a tabela está cheia, o Keymaster retornará
ErrorCode::TOO_MANY_OPERATIONS
:
Tag::NO_AUTH_REQUIRED
Versão: 1, 2, 3, 4
Repetível? Não
Especifica que nenhuma autenticação é necessária para usar essa chave. Essa tag é mutuamente exclusiva de Tag::USER_SECURE_ID.
Essa tag é booleana, então os valores possíveis são verdadeiro (se a tag estiver presente) e falso (se a tag não estiver presente).
Tag::NONCE
Versão: 1, 2, 3, 4
Repetível? Não
Fornece ou retorna um valor de uso único ou vetor de inicialização (IV) para criptografia ou descriptografia AES GCM, CBC ou CTR. Essa tag é fornecida para iniciar as operações de criptografia e descriptografia. Ele só é fornecido para begin se a chave tiver Tag::CALLER_NONCE. Caso contrário, um valor de uso único apropriado ou IV é gerado aleatoriamente pelo Keymaster e retornadas do início.
O valor é um blob, uma matriz de bytes de comprimento arbitrário. Durações permitidas dependem do modo: os valores de uso único do GCM têm 12 bytes de comprimento. CBC e CTR IVs são 16 bytes de comprimento.
Tag::ORIGIN
Versão: 1, 2, 3, 4
Repetível? Não
Especifica onde a chave foi criada, se for conhecida. Essa tag não pode ser especificada durante a geração ou importação de chaves e precisa ser adicionada às características de chave pelo trustlet.
Keymaster 3Os 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á na lista de características aplicadas por hardware ou por software.
GENERATED
indica que o Keymaster gerou a chave.
Se ela estiver na lista de restrições de hardware,
A chave foi gerada em um hardware seguro e está permanentemente vinculada ao hardware. Se
na lista de aplicações de software, ela foi gerada no SoftKeymaster
sem limitação de hardware.
DERIVED
indica que a chave foi derivada no Keymaster.
Provavelmente existe fora do dispositivo.
IMPORTED
indica que a chave foi gerada fora
do Keymaster e importadas para
o Keymaster: Se estiver na lista de restrições de hardware, ele é permanentemente vinculado ao hardware.
embora possam existir cópias fora do hardware seguro. Se estiver na
lista de restrições de software, a chave foi importada para o Keymaster e não está
vinculada ao hardware.
UNKNOWN
só deve aparecer na lista de hardware.
Ele indica que a chave está
vinculada ao hardware, mas não se sabe se ela foi gerada originalmente em
hardware seguro ou se foi importada. Isso só ocorre quando o hardware keymaster0 está
que estão sendo usados para emular os serviços de keymaster1.
Tag::ORIGINATION_EXPIRE_DATETIME
Versão: 1, 2, 3, 4
Repetível? Não
Especifica a data e a hora em que a chave expira para assinatura e
para fins de criptografia. Após esse período, qualquer tentativa de usar uma chave com
KeyPurpose::SIGN ou
KeyPurpose::ENCRYPT fornecida
a begin falha
com ErrorCode::KEY_EXPIRED
.
O valor é um número inteiro de 64 bits que representa milissegundos desde 1º de janeiro de 1970.
Tag::OS_PATCHLEVEL
Versão: 2, 3, 4
Repetível? Não
Essa tag nunca é enviada ao TA do keymaster, mas é adicionada à lista de autorizações aplicada pelo hardware pelo TA.
O valor da tag é um número inteiro no formato AAAAMM, em que AAAA é o ano com quatro dígitos da última atualização e MM é o mês com dois dígitos da última atualização atualizar. Por exemplo, para uma chave gerada em um dispositivo Android atualizada pela última vez em dezembro de 2015, o valor seria 201512.
As chaves com um nível de patch diferente do atual não são
utilizáveis. Uma tentativa de usar essa chave faz com que
begin,
getKeyCharacteristics
ou exportKey
retornem ErrorCode::KEY_REQUIRES_UPGRADE
. Consulte
Vinculação de versões para mais
detalhes.
Tag::OS_VERSION
Versão: 2, 3, 4
Repetível? Não
Essa tag nunca é enviada ao TA do keymaster, mas é adicionada à lista de autorizações aplicada pelo hardware pelo TA.
O valor da tag é um número inteiro no formato MMmmss, em que MM é o maior número da versão, mm é o número da versão secundária e ss é a versão subsecundária. número Por exemplo, para uma chave gerada na versão 4.0.3 do Android, o valor seria 040003.
Tag::PADDING
Versão: 1, 2, 3, 4
Repetível? Sim
Especifica os modos de preenchimento que podem ser usados com a tecla. Essa tag é relevantes para chaves RSA e AES.
Os valores possíveis são definidos pela seguinte enumeração:
Keymaster 3enum 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
somente para chaves de criptografia/descriptografia RSA e especifique o OAEP RSA PKCS#1v2
padding e padding aleatório PKCS#1 v1.5 do RSA, respectivamente.
PaddingMode::RSA_PSS
e
PaddingMode::RSA_PKCS1_1_5_SIGN
são usados apenas para RSAs
chaves de assinatura/verificação e especificar RSA PKCS#1v2 PSS
padding e padding determinístico RSA PKCS#1 v1.5, respectivamente.
PaddingMode::NONE
pode ser usado com RSA ou
chaves AES. Para chaves AES, se PaddingMode::NONE
for usado
com o modo de bloco ECB ou CBC e os dados a serem criptografados ou descriptografados
não forem um múltiplo do tamanho do bloco AES em comprimento, a chamada para terminar
falhará com ErrorCode::INVALID_INPUT_LENGTH
.
PaddingMode::PKCS7
só pode ser usado com chaves AES e
somente com os modos ECB e CBC.
Essa tag pode ser repetida. Um modo de preenchimento precisa ser especificado na chamada para
begin.
Se o modo especificado não for autorizado para a chave, a operação vai falhar
com ErrorCode::INCOMPATIBLE_BLOCK_MODE
.
Tag::PURPOSE
Versão: 1, 2, 3, 4
Repetível? Sim
Especifica o conjunto de finalidades para o uso da chave.
Os valores possíveis são definidos pela seguinte enumeração:
Keymaster 3 (link em inglês)enum class KeyPurpose : uint32_t { ENCRYPT = 0, DECRYPT = 1, SIGN = 2, VERIFY = 3, DERIVE_KEY = 4, // since 3.0 WRAP_KEY = 5, // since 3.0 };
typedef enum { KM_PURPOSE_ENCRYPT = 0, KM_PURPOSE_DECRYPT = 1, KM_PURPOSE_SIGN = 2, KM_PURPOSE_VERIFY = 3, } keymaster_purpose_t;
Essa tag pode ser repetida. as chaves podem ser geradas com vários valores,
embora uma operação tenha um único propósito. Quando o
função begin é chamada
para iniciar uma operação, a finalidade dela é especificada.
Se a finalidade especificada para a operação não for autorizada pelo
a operação vai falhar com ErrorCode::INCOMPATIBLE_PURPOSE
.
Tag::RESET_SINCE_ID_ROTATION
Versão: 3, 4
Repetível? Não
Especifica se o dispositivo foi redefinido para a configuração original desde a última rotação do ID exclusivo. Usado para atestado de chave.
Essa tag é booleana, então os valores possíveis são verdadeiro (se a tag estiver presente) e falso (se a tag não estiver presente).
Tag::ROLLBACK_RESISTANT
Versão: 1, 2, 3, 4
Repetível? Não
Indica que a chave é resistente a reversão, o que significa que, quando excluída por deleteKey ou deleteAllKeys, a chave será permanentemente excluída e inutilizável. É possível que as chaves sem essa tag possam ser excluídas e, em seguida, restauradas do backup.
Essa tag é booleana. Portanto, os valores possíveis são "true" (se a tag estiver presente). e "false" (se a tag não estiver presente).
Tag::ROOT_OF_TRUST
Versão: 1, 2, 3, 4
Repetível? Não
Especifica a raiz de confiança, a chave usada pela inicialização verificada para validar se o sistema operacional foi inicializado (se houver). Essa tag nunca é fornecida ou retornados do Keymaster nas características da chave.
Tag::RSA_PUBLIC_EXPONENT
Versão: 1, 2, 3, 4
Repetível? Não
Especifica o valor do expoente público para um par de chaves RSA. Essa tag é relevante apenas para chaves RSA e é necessária para todas as chaves RSA.
O valor é um número inteiro não assinado de 64 bits que atende aos requisitos de um
exponencial público RSA. Esse valor precisa ser um número primo. Os Trustlets oferecem suporte ao
valor 2^16+1 e podem oferecer suporte a outros valores razoáveis, em particular o valor 3.
Se nenhum expoente for especificado ou se não houver suporte para ele,
a geração de chaves falha com ErrorCode::INVALID_ARGUMENT
.
Tag::UNIQUE_ID
Versão: 3, 4
Repetível? Não
Usado para fornecer um ID exclusivo no atestado.
O valor é um blob, uma matriz de bytes de comprimento arbitrário.
Tag::USAGE_EXPIRE_DATETIME
Versão: 1, 2, 3, 4
Repetível? Não
Especifica a data e a hora em que a chave expira para verificação.
para fins de descriptografia. Depois disso, qualquer tentativa de usar uma chave com
KeyPurpose::VERIFY ou
KeyPurpose::DECRYPT informado para
falha em begin
com ErrorCode::KEY_EXPIRED
.
O valor é um número inteiro de 64 bits que representa milissegundos desde 1º de janeiro de 1970.
Tag::USER_AUTH_TYPE
Versão: 1, 2, 3, 4
Repetível? Não
Especifica os tipos de autenticadores de usuários que podem ser usados para autorizar essa
de dados. Quando o Keymaster é solicitado a executar uma operação com uma chave com esse
tag, ele recebe um token de autenticação, e a tag
O campo authenticator_type
precisa corresponder ao valor na tag.
Por exemplo, (ntoh(token.authenticator_type) &
auth_type_tag_value) != 0
, em que ntoh
é uma função que
converte números inteiros ordenados pela rede em números inteiros ordenados pelo host e
auth_type_tag_value
é o valor dessa tag.
O valor é uma máscara de bits de número inteiro de 32 bits dos valores da enumeração:
Keymaster 3 (link em inglês)enum class HardwareAuthenticatorType : uint32_t { NONE = 0u, // 0 PASSWORD = 1 << 0, FINGERPRINT = 1 << 1, ANY = UINT32_MAX, };
typedef enum { HW_AUTH_NONE = 0, HW_AUTH_PASSWORD = 1 << 0, HW_AUTH_FINGERPRINT = 1 << 1, // Additional entries should be powers of 2. HW_AUTH_ANY = UINT32_MAX, } hw_authenticator_type_t;
Tag::USER_SECURE_ID
Versão: 1, 2, 3, 4
Repetível? Sim
Especifica que uma chave pode ser usada apenas sob um determinado usuário seguro o estado de autenticação. Essa tag é mutuamente exclusiva com Tag::NO_AUTH_REQUIRED.
O valor é um número inteiro de 64 bits que especifica o valor do estado da política de autenticação, que precisa estar presente em um token de autenticação (fornecido para iniciar com Tag::AUTH_TOKEN) para autorizar o uso da chave. Qualquer um chamada para begin com uma chave com essa tag que não fornece uma token de autenticação ou fornece um token de autenticação sem um valor de estado da política correspondente, falha.
Essa tag pode ser repetida. Se algum dos valores fornecidos corresponder a qualquer valor de estado
da política no token de autenticação, a chave será autorizada para uso.
Caso contrário, a operação falhará
ErrorCode::KEY_USER_NOT_AUTHENTICATED
:
Tag::VENDOR_PATCHLEVEL
Versão: 4
Essa tag especifica o nível do patch de segurança da imagem do fornecedor que a chave
pode ser usado. Essa tag nunca é enviada ao keymaster TA, mas é adicionada ao
lista de autorização imposta por hardware pelo TA. Qualquer tentativa de usar uma chave com um
Valor de Tag::VENDOR_PATCHLEVEL
diferente do valor em execução no momento
do sistema precisa causar begin()
,
getKeyCharacteristics()
ou exportKey()
para devolução
ErrorCode::KEY_REQUIRES_UPGRADE
. Consulte upgradeKey()
para mais detalhes.
O valor da tag é um número inteiro no formato AAAAMMDD, em que AAAA é o ano de quatro dígitos da última atualização, MM é o mês de dois dígitos e DD é o dia de dois dígitos da última atualização. Por exemplo, para uma chave gerada em um Dispositivo Android atualizado pela última vez em 5 de junho de 2018. O valor seria 20180605.
O HAL IKeymasterDevice precisa ler o patchlevel atual do fornecedor da propriedade
ro.vendor.build.security_patch
do sistema e enviá-lo ao
ambiente seguro quando o HAL for carregado pela primeira vez (o mecanismo é
definido pela implementação). O ambiente seguro não pode aceitar outro
patchlevel até a próxima inicialização.
Precisa ser aplicada por hardware.