Esta página fornece detalhes para ajudar os implementadores do Keymaster Camadas de abstração de hardware (HALs). Ele aborda cada função API e em qual versão do Keymaster em que a função está disponível, e descreve a implementação padrão. Para tags, consulte a Tags do Keymaster.
Diretrizes gerais de implementação
As diretrizes a seguir se aplicam a todas as funções na API.
Parâmetros de ponteiro de entrada
Versão: 1, 2
Os parâmetros do ponteiro de entrada que não são usados para uma determinada chamada podem ser
NULL: O autor da chamada não precisa fornecer marcadores de posição.
Por exemplo, alguns tipos e modos de chave podem não usar valores do
argumento inParams como begin, para que o autor da chamada possa
Defina inParams como NULL ou forneça um parâmetro vazio.
definido. Os autores da chamada também podem fornecer parâmetros não utilizados, e os métodos do Keymaster devem
e não emitem erros.
Se um parâmetro de entrada obrigatório for NULL, os métodos do Keymaster retornarão
ErrorCode::UNEXPECTED_NULL_POINTER:
A partir do Keymaster 3, não há parâmetros de ponteiro. Todos os parâmetros são passados por referências value ou const.
Parâmetros do ponteiro de saída
Versão: 1, 2
Semelhantes aos parâmetros de ponteiro de entrada, os parâmetros de ponteiro de saída não utilizados
pode ser NULL. Se um método precisa retornar dados em uma saída
NULL for encontrado, ele retornará
ErrorCode::OUTPUT_PARAMETER_NULL.
A partir do Keymaster 3, não há parâmetros de ponteiro. Todos os parâmetros são passados por referências value ou const.
uso indevido da API
Versão: 1, 2, 3
Há muitas maneiras pelas quais os autores da chamada podem fazer solicitações que não fazem sentido ou são tolas, mas não tecnicamente erradas. As implementações do Keymaster não são para não falhar nesses casos ou emitir um diagnóstico. O uso de chaves muito pequenas, a especificação de parâmetros de entrada irrelevantes, reutilização de IVs ou valores de uso único geração de chaves sem propósitos (portanto, inúteis), e similares não devem ser diagnosticadas pelas implementações. Omissão de parâmetros obrigatórios, especificação de parâmetros obrigatórios inválidos e erros semelhantes precisam ser diagnosticados.
É responsabilidade dos apps, do framework e do keystore do Android garante que as chamadas para os módulos do Keymaster sejam sensíveis e úteis.
Funções
getHardwareFeatures
Versão: 3
O novo método getHardwareFeatures expõe aos clientes alguns
características importantes
do hardware seguro subjacente.
O método não recebe argumentos e retorna quatro valores, todos booleanos:
isSecureserátruese as chaves forem armazenadas em hardware protegido (TEE etc.) e nunca o deixe.supportsEllipticCurveétruese o suporte a criptografia de curva elíptica com as curvas NIST (P-224, P-256, P-384 e P-521).supportsSymmetricCryptographyétruese o hardware oferecer suporte à criptografia simétrica, incluindo AES e HMAC.supportsAttestationétruese o oferece suporte à geração de certificados de atestado de chave pública do Keymaster, assinado com uma chave injetada em um ambiente seguro.
Os únicos códigos de erro que esse método pode retornar são ErrorCode:OK,
ErrorCode::KEYMASTER_NOT_CONFIGURED ou um dos códigos de erro
indicando uma falha na comunicação com o hardware protegido.
getHardwareFeatures()
generates(bool isSecure, bool supportsEllipticCurve, bool supportsSymmetricCryptography,
bool supportsAttestation, bool supportsAllDigests, string keymasterName,
string keymasterAuthorName);
configurar
Versão: 2
Esta função foi introduzida no Keymaster 2 e descontinuada no Keymaster 3, já que essas informações estão disponíveis nos arquivos de propriedades do sistema e nos arquivos do as implementações leem esses arquivos durante a inicialização.
Configura o keymaster. Esse método é chamado uma vez após a abertura do dispositivo
e antes de serem usados. Ele é usado para fornecer
KM_TAG_OS_VERSION e
KM_TAG_OS_PATCHLEVEL a
o keymaster. Até que esse método seja chamado, todos os outros métodos retornam
KM_ERROR_KEYMASTER_NOT_CONFIGURED: Os valores fornecidos por
são aceitos pelo keymaster somente uma vez por inicialização. Depois
retornam KM_ERROR_OK, mas não fazem nada.
Se a implementação do keymaster estiver em um hardware seguro e na versão do SO, e
os valores no nível do patch fornecidos não correspondem aos valores fornecidos ao
pelo carregador de inicialização (ou se ele não tiver fornecido valores),
então esse método retorna KM_ERROR_INVALID_ARGUMENT e todos os outros
continuam retornando KM_ERROR_KEYMASTER_NOT_CONFIGURED.
keymaster_error_t (*configure)(const struct keymaster2_device* dev,
const keymaster_key_param_set_t* params);
addRngEntropy
Versão: 1, 2, 3
Essa função foi introduzida no Keymaster 1 como add_rng_entropy
e renomeada no Keymaster 3.
Adiciona a entropia fornecida pelo autor da chamada ao pool usado pela implementação do Keymaster 1 para gerar números aleatórios, chaves, IVs etc.
As implementações do Keymaster precisam combinar com segurança as
entropia no pool, que também deve conter
entropia gerada internamente a partir de um gerador de números aleatórios de hardware.
A mixagem deve ser realizada de forma que um invasor que tenha controle total
dos bits fornecidos pelo addRngEntropy ou dos bits gerados por hardware
bits, mas não ambos, não tem vantagem não insignificante na previsão dos bits
gerados a partir do pool de entropia.
Implementações do Keymaster que tentam estimar a entropia em suas
pool interno presume que os dados fornecidos pelo
addRngEntropy não contém entropia. As implementações do Keymaster podem
retornam ErrorCode::INVALID_INPUT_LENGTH se receberem mais de 2.
KiB de dados em uma única chamada.
generateKey
Versão: 1, 2, 3
Essa função foi introduzida no Keymaster 1 como generate_key
e renomeada no Keymaster 3.
Gera uma nova chave criptográfica especificando as autorizações associadas.
que são permanentemente vinculados à chave. As implementações do Keymaster facilitam
usar uma chave de alguma forma inconsistente com as autorizações
especificados no momento da geração. Com relação às autorizações que o sistema
hardware protegido, a obrigação do hardware seguro fica limitada
garantindo que as autorizações não executáveis associadas à chave não
ser modificada, de modo que todas as chamadas para
getKeyCharacteristics (link em inglês)
retorna o valor original. Além disso, as características retornadas
generateKey aloca autorizações corretamente entre as
impostas por hardware e por software. Consulte
getKeyCharacteristics para mais detalhes.
Os parâmetros fornecidos para generateKey dependem do tipo de chave
que está sendo gerado. Esta seção resume as tags necessárias e opcionais para
cada tipo de chave. Tag::ALGORITMO
é sempre necessário para especificar o tipo.
Chaves RSA
Os parâmetros a seguir são necessários para gerar uma Chave RSA.
- Tag::KEY_SIZE
especifica o tamanho do módulo público, em bits. Se omitido,
O método retornará
ErrorCode::UNSUPPORTED_KEY_SIZE. Os valores aceitos são 1024, 2048, 3072 e 4096. Valores recomendados são tamanhos de chave que são múltiplos de 8. - Tag::RSA_PUBLIC_EXPONENT
especifica o valor do expoente público RSA. Se omitido, o método
retorna
ErrorCode::INVALID_ARGUMENT. Os valores aceitos são 3 e 65537. Os valores recomendados são todos os valores primos até 2^64.
Os parâmetros a seguir não são necessários para gerar uma Chave RSA, mas
criar uma Chave RSA sem eles produz uma chave inutilizável. No entanto,
A função generateKey não vai retornar um erro se esses parâmetros
são omitidos.
- Tag::PURPOSE especifica: para fins permitidos. Todas as finalidades precisam ser compatíveis com chaves RSA, em qualquer combinação.
- Tag::DIGEST especifica:
de resumo que podem ser usados com a chave nova. Implementações
que não são compatíveis com todos os algoritmos de resumo precisam aceitar a geração de chaves
solicitações que incluem resumos não compatíveis. Os resumos não aceitos devem ser
colocado no sistema "aplicada por software", nas características principais retornadas.
Isso ocorre porque a chave pode ser usada com esses outros resumos, mas o resumo é
realizadas no software. Em seguida, o hardware é chamado para realizar a operação
com
Digest::NONE. - Tag::PADDING especifica
de padding que podem ser usados com a nova chave. Implementações
que não oferecem suporte a todos os algoritmos de resumo precisam colocar
PaddingMode::RSA_PSSePaddingMode::RSA_OAEPpol. a lista imposta por software das características principais, se houver são especificados.
Chaves ECDSA
Somente Tag::KEY_SIZE é necessárias para gerar uma chave ECDSA. Ele é usado para selecionar o grupo de EC. Os valores suportados são 224, 256, 384 e 521, que indicam os Curvas NIST p-224, p-256, p-384 e p521, respectivamente.
Tag::DIGEST também é necessário para uma chave ECDSA útil, mas não são necessários para a geração.
Chaves AES
Somente Tag::KEY_SIZE
para gerar uma chave AES. Se omitido, o método retorna
ErrorCode::UNSUPPORTED_KEY_SIZE: Os valores aceitos são
128 e 256, com suporte opcional para chaves AES de 192 bits.
Os parâmetros a seguir são especialmente relevantes para chaves AES, mas não necessário para gerar um:
Tag::BLOCK_MODEespecifica os modos de bloco com que a nova chave poderá ser usada.Tag::PADDINGespecifica os modos de padding que podem ser usados. Isso só é relevante para os modos ECB e CBC.
Se o modo de bloqueio do GCM for especificado, forneça o
Tag::MIN_MAC_LENGTH.
Se omitido, o método retornará ErrorCode::MISSING_MIN_MAC_LENGTH.
O valor da tag é um múltiplo de 8 e está entre 96 e 128.
Chaves HMAC
Os seguintes parâmetros são obrigatórios para a geração de chaves HMAC:
- Tag::KEY_SIZE especifica o tamanho da chave em bits. Valores menores que 64 e valores que não sejam múltiplos de 8 não serão aceitos. Todos múltiplos de 8, de 64 a 512, são suportados. Valores maiores podem ser suporte.
- Tag::MIN_MAC_LENGTH especifica o comprimento mínimo MACs que podem ser gerados ou verificados com essa chave. O valor é um múltiplo de 8 e pelo menos 64.
- Tag::DIGEST
especifica o algoritmo de resumo da chave. Exatamente
um resumo é especificado. Caso contrário, retorna
ErrorCode::UNSUPPORTED_DIGEST: Se o resumo não for compatível pelo trustlet, retornarErrorCode::UNSUPPORTED_DIGEST:
Principais características
Se o argumento das características não for NULL, generateKey retornará
as características da chave recém-gerada divididas corretamente em
impostas por hardware e por software. Consulte
getKeyCharacteristics para uma descrição
de quais características entram em qual lista. As características retornadas
incluem todos os parâmetros especificados para a geração de chaves, exceto
Tag::APPLICATION_ID e
Tag::APPLICATION_DATA.
Se essas tags forem incluídas nos parâmetros-chave, serão removidas dos
as características retornadas, de modo que não seja possível encontrar os valores
examinando o blob de chave retornado. No entanto, elas são vinculadas criptograficamente
ao blob da chave, para que, se os valores corretos não forem fornecidos quando a chave for
usado, o uso falhará. Da mesma forma,
Tag::ROOT_OF_TRUST é
vinculado criptograficamente à chave, mas ele pode não ser especificado durante
criação ou importação de chaves e nunca é retornado.
Além das tags fornecidas, o trustlet também
adiciona Tag::ORIGIN,
com o valor KeyOrigin::GENERATED,
e, se ela for resistente a reversões,
Resistência a reversão
A resistência à reversão significa que, quando uma chave é excluída com deleteKey ou deleteAllKeys, é garantida por um hardware seguro. nunca mais serão usados. Geralmente, as implementações sem resistência à reversão retornam material de chave gerado ou importado para o autor da chamada como um blob de chave, uma criptografado e autenticado. Quando o keystore exclui o blob da chave, a chave é mas um invasor que já conseguiu recuperar o material da chave poderá restaurá-lo no dispositivo.
Uma chave será resistente a reversão se o hardware seguro garantir que a exclusão não poderão ser restauradas depois. Isso geralmente é feito com o armazenamento os metadados em um local confiável que não possa ser manipulado por um invasor. Ativado Em dispositivos móveis, o mecanismo usado geralmente é a memória protegida Bloqueios (RPMB). Como o número de chaves que podem ser criadas é essencialmente ilimitada e o armazenamento confiável usado para a resistência à reversão pode ser limitado em tamanho, esse método precisa funcionar mesmo se houver resistência à reversão não pode ser fornecido para a nova chave. Nesse caso, Tag::ROLLBACK_RESISTANT não precisam ser adicionadas às características principais.
getKeyCharacteristics
Versão: 1, 2, 3
Essa função foi introduzida no Keymaster 1 como
get_key_characteristics e renomeado no Keymaster 3.
Retorna parâmetros e autorizações associados à chave fornecida. aplicadas por hardware e por software. Descrição aqui se aplica igualmente às listas de características das chaves retornadas por generateKey e importKey.
Se Tag::APPLICATION_ID tiver sido fornecido durante a geração da chave
ou importar, o mesmo valor é fornecido para
esse método no argumento clientId. Caso contrário, o
retorna ErrorCode::INVALID_KEY_BLOB. Da mesma forma,
se Tag::APPLICATION_DATA foi fornecido durante a geração
ou importar, o mesmo valor é fornecido para
esse método no argumento appData.
As características retornadas por esse método descrevem completamente o tipo e uso da chave especificada.
A regra geral para decidir se uma tag específica pertence "impostas por hardware" ou "impostas por software", se o significado da tag está totalmente garantido pelo hardware seguro, é aplicado ao hardware. Caso contrário, é a aplicação de software. Abaixo está uma lista de tags específicas cuja alocação correta podem não ser claros:
- Tag::ALGORITMO, Tag::KEY_SIZE, e Tag::RSA_PUBLIC_EXPONENT são propriedades intrínsecas da chave. Para qualquer chave protegida por hardware, e essas tags estarão na lista de recomendações de hardware.
- Tag::DIGEST compatíveis com o hardware seguro sejam colocados com suporte a hardware. Resumos sem suporte vão para a lista de softwares compatíveis.
- Tag::PADDING geralmente são incluídas na lista de suporte a hardware, a menos que exista uma possibilidade de que um modo de padding específico precise ser executado pelo software. Nesse caso, ele é colocado na lista de restrições por software. Essa possibilidade surge para chaves RSA que permitem preenchimento PSS ou OAEP com algoritmos de resumo que não são compatíveis com o hardware seguro.
- Tag::USER_SECURE_ID e Tag::USER_AUTH_TYPE são aplicadas por hardware apenas se a autenticação do usuário for aplicada por hardware. Para para isso, o trustlet do Keymaster e o protocolo de autenticação que precisam ser seguros e compartilhar uma chave HMAC secreta usada para assinar e e validar tokens de autenticação. Consulte a Autenticação para ver detalhes.
- Tag::ACTIVE_DATETIME, Tag::ORIGINATION_EXPIRE_DATETIME, e Tag::USAGE_EXPIRE_DATETIME precisam de acesso a um relógio de parede comprovávelmente correto. Hardware mais seguro tem acesso somente às informações de horário fornecidas pelo sistema operacional não seguro, que significa que as tags são aplicadas por software.
- Tag::ORIGIN é sempre na lista de hardware para chaves vinculadas a hardware. Sua presença nessa é a forma como as camadas mais altas determinam que uma chave tem suporte de hardware.
importKey
Versão: 1, 2, 3
Essa função foi introduzida no Keymaster 1 como import_key
e renomeada no Keymaster 3.
Importa o material da chave para o hardware do Keymaster. Principais parâmetros de definição e
as características de saída são tratadas da mesma forma que em generateKey,
com as seguintes exceções:
- Tag::KEY_SIZE e
Tag::RSA_PUBLIC_EXPONENT
(somente para chaves RSA) não são necessários nos parâmetros de entrada. Caso contrário,
o trustlet deduz os valores do material de chave fornecido e adiciona
tags e valores adequados às características-chave. Se os parâmetros forem
fornecido, o trustlet os valida em relação ao material da chave. Na
evento de incompatibilidade, o método retornará
ErrorCode::IMPORT_PARAMETER_MISMATCH. - A Tag::ORIGIN retornada tem a
mesmo valor que
KeyOrigin::IMPORTED.
exportKey.
Versão: 1, 2, 3
Essa função foi introduzida no Keymaster 1 como export_key
e renomeada no Keymaster 3.
Exporta uma chave pública de um par de chaves RSA ou EC do Keymaster.
Se Tag::APPLICATION_ID foi fornecido durante a geração de chaves ou
import, o mesmo valor será fornecido a esse método na
clientId. Caso contrário, o método retorna
ErrorCode::INVALID_KEY_BLOB: Da mesma forma, se
Tag::APPLICATION_DATA
foi fornecido durante a geração ou importação, o mesmo valor será fornecido para
esse método no argumento appData.
deleteKey
Versão: 1, 2, 3
Essa função foi introduzida no Keymaster 1 como delete_key
e renomeada no Keymaster 3.
Exclui a chave fornecida. Esse método é opcional e só implementado pelos módulos do Keymaster que oferecem resistência à reversão.
deleteAllKeys
Versão: 1, 2, 3
Essa função foi introduzida no Keymaster 1 como delete_all_keys
e renomeada no Keymaster 3.
Exclui todas as chaves. Esse método é opcional e só é implementado pelos módulos do Keymaster, que oferecem resistência a reversão.
destroyAttestationIds
Versão: 3
O método destroyAttestationIds() é usado para armazenar
desativar o novo (opcional, mas altamente recomendado)
Atestado de ID
. Se o TEE não tiver como garantir que o atestado de ID seja permanentemente
desativado depois que esse método for chamado, o atestado do ID não poderá ser
implementado. Nesse caso, o método não faz nada e
retorna ErrorCode::UNIMPLEMENTED. Se o atestado do ID for
suportado, esse método precisa ser implementado e deve desativar permanentemente
todas as tentativas futuras de atestado de ID. O método pode ser chamado de qualquer número
vezes. Se o atestado de ID já estiver desativado permanentemente, o método
nada e retorna ErrorCode::OK.
Os únicos códigos de erro que esse método pode retornar são
ErrorCode::UNIMPLEMENTED (se o atestado do ID não for compatível),
ErrorCode:OK, ErrorCode::KEYMASTER_NOT_CONFIGURED ou
um dos códigos de erro que indica uma falha na comunicação com o servidor
ao hardware.
begin
Versão: 1, 2, 3
Inicia uma operação criptográfica usando a chave especificada para o
com os parâmetros especificados (conforme apropriado) e retorna uma
identificador de operação usado com update e finish para concluir a operação. O identificador de operação é
também é usado como o "desafio", token em operações autenticadas, e para tais
está incluído no campo challenge da
token de autenticação.
Uma implementação do Keymaster oferece suporte a pelo menos 16 solicitações
as operações. O keystore usa até 15, deixando um para o vold usar para a senha
criptografia. Quando o Keystore tem 15 operações em andamento (begin tem
foi chamado, mas finish ou abort ainda não foram
for chamado) e receber uma solicitação para começar no 16, ele chama
abort na operação usada menos recentemente para reduzir o número de
operações ativas para 14 antes de chamar begin para iniciar a
operação recém-solicitada.
Se Tag::APPLICATION_ID
ou Tag::APPLICATION_DATA foram especificadas
durante a geração ou importação de chaves, as chamadas para begin incluem as
inclui os valores especificados originalmente no argumento inParams.
para este método.
Aplicação da autorização
Durante esse método, as seguintes autorizações de chave são aplicadas pelo
se a implementação os tiver colocado no arquivo "aplicado por hardware"
e se a operação não é de chave pública. Chave pública
operações, ou seja, KeyPurpose::ENCRYPT e KeyPurpose::VERIFY,
com chaves RSA ou EC, terão êxito mesmo se a autorização
requisitos não são atendidos.
- Tag::PURPOSE: a finalidade
especificado na chamada
begin()precisa corresponder a um dos objetivos. nas autorizações de chave, a menos que a operação solicitada seja de chave pública. operação Se a finalidade especificada não corresponder e a operação não for uma operação de chave pública,beginretornaráErrorCode::UNSUPPORTED_PURPOSE. As operações de chave pública são criptografia assimétrica ou operações de verificação. - Tag::ACTIVE_DATETIME
só poderá ser aplicado se uma fonte de horário UTC confiável estiver disponível. Se o
a data e a hora atuais forem anteriores ao valor da tag, o método retornará
ErrorCode::KEY_NOT_YET_VALID: - Tag::ORIGINATION_EXPIRE_DATETIME
só poderá ser aplicado se uma fonte de horário UTC confiável estiver disponível. Se o
a data e a hora atuais é posterior ao valor da tag e a finalidade é
KeyPurpose::ENCRYPTouKeyPurpose::SIGN, o método retornaErrorCode::KEY_EXPIRED. - Tag::USAGE_EXPIRE_DATETIME
só poderá ser aplicado se uma fonte de horário UTC confiável estiver disponível. Se o
a data e a hora atuais é posterior ao valor da tag e a finalidade é
KeyPurpose::DECRYPTouKeyPurpose::VERIFY, o método retornaErrorCode::KEY_EXPIRED. - Tag::MIN_SECONDS_BETWEEN_OPS
é comparado a um timer relativo confiável, que indica o último uso do
a chave. Se a hora do último uso mais o valor da tag for menor que a hora atual,
O método retornará
ErrorCode::KEY_RATE_LIMIT_EXCEEDED. Consulte a descrição da tag para detalhes importantes de implementação. - Tag::MAX_USES_PER_BOOT
é comparada com um contador seguro que rastreia os usos da chave
desde o momento da inicialização. Se a contagem de usos anteriores exceder o valor da tag, o
retorna
ErrorCode::KEY_MAX_OPS_EXCEEDED. - Tag::USER_SECURE_ID
é aplicado por esse método somente se a chave também tem
Tag::AUTH_TIMEOUT.
Se a chave tiver ambos, então este método deverá receber um valor válido
Tag::AUTH_TOKEN em
inParamsPara que o token de autenticação seja válido, todos os itens a seguir precisa ser verdadeira:- O campo HMAC é validado corretamente.
- Pelo menos um dos Tag::USER_SECURE_ID valores da chave correspondem a pelo menos um dos valores de ID seguro na com base no token correto anterior.
- A chave tem Tag::USER_AUTH_TYPE que corresponde ao tipo Auth no token.
Se alguma dessas condições não for atendida, o método retornará
ErrorCode::KEY_USER_NOT_AUTHENTICATED: - Tag::CALLER_NONCE
permite que o autor da chamada especifique um valor de uso único ou vetor de inicialização (IV). Se a chave
não tem essa tag, mas o autor da chamada forneceu
Use Tag::NONCE nesse método,
ErrorCode::CALLER_NONCE_PROHIBITEDé retornado. - Tag::BOOTLOADER_ONLY
especifica que somente o carregador de inicialização pode usar a chave. Se este método for
chamado com uma chave somente para o carregador de inicialização após o término da execução,
ela retornará
ErrorCode::INVALID_KEY_BLOB.
Chaves RSA
Todas as operações da Chave RSA especificam exatamente um modo de padding em inParams.
Se não for especificado ou for especificado mais de uma vez, o método retornará
ErrorCode::UNSUPPORTED_PADDING_MODE:
As operações de verificação e assinatura RSA precisam de um resumo, assim como a criptografia RSA.
e operações de descriptografia com o modo de padding OAEP. Nesses casos, o autor da chamada
especifica exatamente um resumo em inParams. Se não for especificado ou for especificado
mais de uma vez, o método retornará ErrorCode::UNSUPPORTED_DIGEST.
Operações de chave privada (KeyPurpose::DECYPT e KeyPurpose::SIGN)
precisam de autorização de resumo e preenchimento, ou seja, as autorizações da chave
precisam conter os valores especificados. Caso contrário, o método retorna
ErrorCode::INCOMPATIBLE_DIGEST
ou ErrorCode::INCOMPATIBLE_PADDING, conforme apropriado. Operações de chave pública
(KeyPurpose::ENCRYPT e KeyPurpose::VERIFY) têm permissão com
resumo ou preenchimento não autorizado.
Com exceção de PaddingMode::NONE, todos os modos de padding do RSA são
aplicáveis somente a determinados fins. Especificamente:
PaddingMode::RSA_PKCS1_1_5_SIGN e PaddingMode::RSA_PSS
oferecem suporte apenas a assinatura e verificação, enquanto PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT
e PaddingMode::RSA_OAEP oferecem suporte apenas a criptografia e descriptografia.
O método retornará ErrorCode::UNSUPPORTED_PADDING_MODE se a
especificado não oferece suporte à finalidade especificada.
Há algumas interações importantes entre os modos de preenchimento e resumos:
PaddingMode::NONEindica que um item "bruto" A operação RSA é realizada. Se você assinar ou verificar,Digest::NONEserá especificado para o resumo. Nenhum resumo é necessário para criptografia sem preenchimento ou com a descriptografia e descriptografia.- O padding
PaddingMode::RSA_PKCS1_1_5_SIGNrequer um resumo. A O resumo poderá serDigest::NONE. Nesse caso, o Keymaster não consegue criar uma estrutura de assinatura PKCS#1 v1.5 adequada, porque ele não pode adicionar a estrutura DigestInfo. Em vez disso, a implementação constrói0x00 || 0x01 || PS || 0x00 || M, em que M é o a mensagem fornecida, e PS é a string de padding. O tamanho da Chave RSA precisa ser pelo menos 11 bytes maior que a mensagem; caso contrário, o método retornaErrorCode::INVALID_INPUT_LENGTH: - O padding
PaddingMode::RSA_PKCS1_1_1_5_ENCRYPTnão requer um resumo. - O padding
PaddingMode::RSA_PSSexige um resumo, que pode não serDigest::NONE. SeDigest::NONEfor especificado, o retornaErrorCode::INCOMPATIBLE_DIGEST. Além disso, o tamanho da Chave RSA precisa ser pelo menos 2 + D bytes maior que o tamanho da saída tamanho do resumo, onde D é o tamanho do resumo, em bytes. Caso contrário O método retornaráErrorCode::INCOMPATIBLE_DIGEST. O tamanho do sal é D. - O padding
PaddingMode::RSA_OAEPexige um resumo, que pode não serDigest::NONE. SeDigest::NONEfor especificado, o retornaErrorCode::INCOMPATIBLE_DIGEST.
Chaves EC
As operações de chave de EC especificam exatamente um modo de padding em inParams.
Se não for especificado ou for especificado mais de uma vez, o método
retorna ErrorCode::UNSUPPORTED_PADDING_MODE.
As operações de chave privada (KeyPurpose::SIGN) precisam de autorização
de resumo e preenchimento, o que significa que as principais autorizações
precisam conter os valores especificados. Caso contrário, retorne
ErrorCode::INCOMPATIBLE_DIGEST: Operações de chave pública
(KeyPurpose::VERIFY) podem usar resumo ou padding não autorizados.
Chaves AES
As operações principais do AES especificam exatamente um modo de bloco e um modo de preenchimento
em inParams. Se um valor não for especificado ou for especificado mais
de uma vez, retorna ErrorCode::UNSUPPORTED_BLOCK_MODE ou
ErrorCode::UNSUPPORTED_PADDING_MODE. Os modos especificados precisam ser
autorizado pela chave. Caso contrário, o método retorna
ErrorCode::INCOMPATIBLE_BLOCK_MODE ou
ErrorCode::INCOMPATIBLE_PADDING_MODE.
Se o modo de bloqueio for BlockMode::GCM, inParams
especifica Tag::MAC_LENGTH, e o
o valor especificado é um múltiplo de 8 que não é maior que 128
ou menor que o valor de Tag::MIN_MAC_LENGTH no
autorizações de chave. Para comprimentos de MAC maiores que 128 ou não múltiplos de
8, retorna ErrorCode::UNSUPPORTED_MAC_LENGTH. Para valores menores
que o comprimento mínimo da chave, retorna ErrorCode::INVALID_MAC_LENGTH.
Se o modo de bloqueio for BlockMode::GCM ou BlockMode::CTR,
o modo de padding especificado precisa ser PaddingMode::NONE.
Para BlockMode::ECB ou BlockMode::CBC, o modo pode ser
PaddingMode::NONE ou PaddingMode::PKCS7. Se o modo de padding
não atender a essas condições, retornará ErrorCode::INCOMPATIBLE_PADDING_MODE.
Se o modo de bloco for BlockMode::CBC, BlockMode::CTR,
ou BlockMode::GCM, é necessário um vetor de inicialização ou um valor de uso único.
Na maioria dos casos, os autores de chamadas não devem fornecer um IV ou um valor de uso único. Nesse caso, o
A implementação do Keymaster gera um IV ou valor de uso único aleatório e o retorna por meio de
Tag::NONCE em outParams.
Os IVs de CBC e CTR têm 16 bytes. Os valores de uso único do GCM são de 12 bytes. Se a chave
autorizações contêm
Tag::CALLER_NONCE,
o autor da chamada poderá fornecer um valor de uso único/IV/valor de uso único com
Tag::NONCE
em inParams. Caso um valor de uso único seja fornecido quando
Tag::CALLER_NONCE
não autorizado, retorne ErrorCode::CALLER_NONCE_PROHIBITED.
Se um valor de uso único não for fornecido quando
Tag::CALLER_NONCE
for autorizado, gere um valor de uso único aleatório/IV.
Chaves HMAC
As operações de chave HMAC especificam Tag::MAC_LENGTH em inParams.
O valor especificado deve ser um múltiplo de 8 que não seja maior que o
tamanho de resumo por e-mail ou menor que o valor de Tag::MIN_MAC_LENGTH
nas autorizações de chave. Para tamanhos de MAC maiores que o comprimento do resumo por e-mail ou
não múltiplos de 8, retorna ErrorCode::UNSUPPORTED_MAC_LENGTH.
Para valores menores que o comprimento mínimo da chave, retorne
ErrorCode::INVALID_MAC_LENGTH:
update
Versão: 1, 2, 3
Fornece dados a serem processados em uma operação em andamento iniciada com begin.
A operação é especificada pelo parâmetro operationHandle.
Para oferecer mais flexibilidade no processamento do buffer, as implementações desse método
têm a opção de consumir menos dados do que foram fornecidos. O autor da chamada é
responsável pelo loop para alimentar o restante dos dados em chamadas subsequentes. A
a quantidade de entrada consumida é retornada no parâmetro inputConsumed.
As implementações sempre consomem pelo menos um byte, a menos que o
não pode mais aceitar. se forem fornecidos mais de 0 bytes
bytes são consumidos, os autores da chamada consideram isso um erro e abortam a operação.
As implementações também podem escolher quantos dados retornar, como resultado do atualizar. Isso só é relevante para operações de criptografia e descriptografia porque a assinatura e a verificação não retornam dados até concluir. Retorne os dados o mais cedo possível, em vez de armazená-los em buffer.
Tratamento de erros
Se esse método retornar um código de erro diferente de ErrorCode::OK,
a operação é cancelada e o identificador da operação é invalidado. Qualquer um
o uso futuro do identificador, com esse método,
finish ou abort.
retorna ErrorCode::INVALID_OPERATION_HANDLE.
Aplicação da autorização
A aplicação da autorização de chaves é realizada principalmente no início. A única exceção é quando a chave tem:
- uma ou mais Tag::USER_SECURE_IDs e
- Não tem uma Tag::AUTH_TIMEOUT
Nesse caso, a chave requer uma autorização por operação, e a atualização
recebe um evento Tag::AUTH_TOKEN
no argumento inParams. O HMAC verifica se o token é válido e contém
um ID de usuário seguro correspondente, que corresponde
Tag::USER_AUTH_TYPE,
e contém o identificador da operação atual no
campo de segurança. Se essas condições não forem atendidas,
ErrorCode::KEY_USER_NOT_AUTHENTICATED:
O autor da chamada fornece o token de autenticação a cada chamada para update e concluir. A implementação só precisa validar o token uma vez, se preferir.
Chaves RSA
Para operações de assinatura e verificação com Digest::NONE,
esse método aceita que todo o bloco seja assinado ou verificado em uma única
atualizar. Ela não pode consumir apenas uma parte do bloco. No entanto, se o autor da chamada
optar por fornecer os dados em várias atualizações, esse método a aceitará.
Se o autor da chamada fornecer mais dados para assinar do que podem ser usados (duração de
dados exceder o tamanho da chave RSA), retorne ErrorCode::INVALID_INPUT_LENGTH.
Chaves ECDSA
Para operações de assinatura e verificação com Digest::NONE,
esse método aceita que todo o bloco seja assinado ou verificado em uma única
atualizar. Esse método não pode consumir apenas uma parte do bloco.
No entanto, se o autor da chamada optar por fornecer os dados em várias atualizações, este método a aceita. Se o autor da chamada fornecer mais dados para assinar do que pode ser usado, os dados são silenciosamente truncados. Isso é diferente da gerenciamento de dados em excesso fornecidos em operações de RSA semelhantes. O motivo disso é a compatibilidade com clientes legados).
Chaves AES
O modo AES GCM suporta "dados de autenticação associados", fornecidas pela
Tag::ASSOCIATED_DATA
tag no argumento inParams.
Os dados associados podem ser fornecidos em chamadas repetidas (importante se
os dados sejam muito grandes para serem enviados em um único bloco), mas sempre precedem os dados
para criptografia ou descriptografia. Uma chamada de atualização pode receber os dois dados associados
e dados para criptografar/descriptografar, mas as atualizações subsequentes podem não incluir
dados. Se o autor da chamada fornecer dados associados a uma chamada de atualização após outra
que inclui dados para criptografar/descriptografar, retorne ErrorCode::INVALID_TAG.
Para a criptografia do GCM, a tag é anexada ao texto criptografado por:
concluir. Durante a descriptografia, o último
Tag::MAC_LENGTH bytes dos dados fornecidos ao último
de atualização é a tag. Como uma determinada invocação de
update não consegue saber se é a última invocação,
ele processa tudo menos o comprimento da tag e armazena em buffer os possíveis dados da tag
durante a conclusão.
concluir
Versão: 1, 2, 3
Conclui uma operação em andamento iniciada com begin processar todos os dados ainda não processados fornecidos atualizações.
Esse método é o último chamado em uma operação, portanto, dados processados são retornados.
Este método finaliza com êxito ou retorna um erro,
a operação e, portanto, invalida o identificador da operação fornecido. Qualquer um
uso futuro do identificador, com este método ou update ou
abort, retorna ErrorCode::INVALID_OPERATION_HANDLE.
As operações de assinatura retornam a assinatura como a saída. Operações de verificação
aceitam a assinatura no parâmetro signature e não retornam nenhuma saída.
Aplicação da autorização
A aplicação da autorização de chaves é realizada principalmente começar. A única exceção é quando a chave tem:
- Um ou mais Tag::USER_SECURE_IDs e
- Não tem um Tag::AUTH_TIMEOUT
Nesse caso, a chave requer uma autorização por operação, e a atualização
recebe um evento Tag::AUTH_TOKEN
no argumento inParams. O HMAC verifica se o token
é válido e contém um ID de usuário seguro correspondente, corresponde ao
Tag::USER_AUTH_TYPE e
contém o identificador da operação atual no
campo de segurança. Se essas condições não forem atendidas,
ErrorCode::KEY_USER_NOT_AUTHENTICATED:
O autor da chamada fornece o token de autenticação para cada chamada para update e finish. A implementação só precisa validar o token uma vez, se preferir.
Chaves RSA
Alguns requisitos adicionais, dependendo do modo de padding:
PaddingMode::NONE: Para operações de assinatura e criptografia sem preenchimento, se os dados fornecidos forem menores que a chave, os dados serão preenchidos com zeros que antecedem a assinatura/criptografia. Se os dados tiverem o mesmo comprimento que a chave, mas numericamente maior, retornaErrorCode::INVALID_ARGUMENT. Para de verificação e descriptografia, os dados devem ter exatamente como a chave. Caso contrário, retornaErrorCode::INVALID_INPUT_LENGTH..PaddingMode::RSA_PSS: Para operações de assinatura com PSS, o sal PSS é do tamanho do resumo de mensagens e gerado aleatoriamente. O resumo especificado com Tag::DIGEST eminputParamsem begin é usado como o resumo PSS e como algoritmo de resumo MGF1.PaddingMode::RSA_OAEP: O resumo especificado com Tag::DIGEST eminputParamsem begin é usado como o OAEP algoritmo de resumo, e SHA1 é usado como o algoritmo de resumo MGF1.
Chaves ECDSA
Se os dados fornecidos para assinatura ou verificação sem preenchimento forem muito longos, faça o truncamento reimplantá-lo.
Chaves AES
Algumas condições adicionais, dependendo do modo de bloqueio:
BlockMode::ECBouBlockMode::CBC. Se o padding forPaddingMode::NONEe a o comprimento dos dados não é um múltiplo do tamanho do bloco AES, retorneErrorCode::INVALID_INPUT_LENGTH. Se o padding forPaddingMode::PKCS7, preencha os dados de acordo com a especificação PKCS#7. O PKCS#7 recomenda adicionar mais um bloco de padding. se os dados forem um múltiplo do comprimento do bloco.BlockMode::GCM: Durante a criptografia, após o processamento texto simples, calcule a tag (Tag::MAC_LENGTH bytes) e anexá-lo ao texto criptografado retornado. Durante a descriptografia, processar a última Tag::MAC_LENGTH bytes da tag. Se a verificação da tag falhar, devolvaErrorCode::VERIFICATION_FAILED:
cancelar
Versão: 1, 2, 3
Cancela a operação em andamento. Após a chamada de cancelamento, retorne
ErrorCode::INVALID_OPERATION_HANDLE para
qualquer uso subsequente do identificador de operação fornecido com update,
concluir ou cancelar.
get_supported_algorithms
Versão: 1
Retorna a lista de algoritmos com suporte ao hardware do Keymaster implementação. Uma implementação de software retorna uma lista vazia. um híbrido implementação retorna uma lista que contém apenas os algoritmos que estão suportado pelo hardware.
As implementações do Keymaster 1 oferecem suporte a RSA, EC, AES e HMAC.
get_supported_block_modes
Versão: 1
Retorna a lista de modos de bloco AES compatíveis com o hardware do Keymaster para um algoritmo e propósito específicos.
Para RSA, EC e HMAC, que não são cifras de bloco, o método retorna uma
lista vazia para todas as finalidades válidas. Finalidades inválidas devem fazer com que o método
retorne ErrorCode::INVALID_PURPOSE.
As implementações do Keymaster 1 oferecem suporte a ECB, CBC, CTR e GCM para AES criptografia e descriptografia.
get_supported_padding_modes
Versão: 1
Retorna a lista de modos de preenchimento compatíveis com o hardware do Keymaster para um algoritmo e propósito específicos.
HMAC e EC não têm noção de padding, então o método retorna uma lista vazia
para todas as finalidades válidas. Finalidades inválidas devem fazer com que o método retorne
ErrorCode::INVALID_PURPOSE:
Para RSA, as implementações do Keymaster 1 oferecem suporte a:
- Criptografia, descriptografia, assinatura e verificação sem preenchimento. Para sem preenchimento criptografia e assinatura, se a mensagem for menor que o módulo público, as implementações precisam preenchê-la com zeros à esquerda. Para descriptografia e o comprimento da entrada precisa corresponder ao tamanho do módulo público.
- Modos de criptografia e padding de assinatura PKCS#1 v1.5
- PSS com um comprimento mínimo de sal de 20
- OAEP
Para AES nos modos ECB e CBC, as implementações do Keymaster 1 oferecem suporte a nenhum e padding PKCS#7-padding. Os modos CTR e GCM somente não suportam preenchimento.
get_supported_digests
Versão: 1
Retorna a lista de modos de resumo com suporte ao hardware do Keymaster para um algoritmo e propósito específicos.
Nenhum modo AES oferece suporte ou exige resumo, então o método retorna um valor para fins válidos.
As implementações do Keymaster 1 podem implementar um subconjunto dos resumos por e-mail. As implementações incluem SHA-256, MD5, SHA1, SHA-224, SHA-256, SHA384 e SHA512 (o conjunto completo de resumos definidos).
get_supported_import_formats
Versão: 1
Retorna a lista de formatos de importação compatíveis com o hardware do Keymaster implementação de um algoritmo especificado.
As implementações do Keymaster 1 oferecem suporte ao formato PKCS#8 (sem senha) do Google) para importar pares de chaves RSA e EC, e oferecer suporte à importação RAW de Material das chaves AES e HMAC.
get_supported_export_formats
Versão: 1
Retorna a lista de formatos de exportação compatíveis com o hardware do Keymaster implementação de um algoritmo especificado.
As implementações do Keymaster1 oferecem suporte ao formato X.509 para exportação de RSA e chaves públicas de EC. A exportação de chaves privadas ou assimétricas não é aceita.
Funções históricas
Keymaster 0
As funções a seguir pertencem à definição original do Keymaster 0. Eles estavam presentes no Keymaster 1 struct keymaster1_device_t. No entanto, no Keymaster 1.0 não foram implementados e os ponteiros de função foram definidos como NULL.
generate_keypairimport_keypairget_keypair_publicdelete_keypairdelete_allsign_dataVerify_data
Keymaster 1
As funções a seguir pertencem à definição do Keymaster 1, mas foram removidas no Keymaster 2, junto com as funções do Keymaster 0 listadas acima.
get_supported_algorithmsget_supported_block_modesget_supported_padding_modesget_supported_digestsget_supported_import_formatsget_supported_export_formats
Keymaster 2
As funções a seguir pertencem à definição do Keymaster 2, mas foram removidas no Keymaster 3, junto com as funções do Keymaster 1 listadas acima.
configure