Esta página foi traduzida pela API Cloud Translation.

Funções Keymaster, Funções Keymaster

Esta página fornece detalhes para auxiliar os implementadores de Keymaster Hardware Abstraction Layers (HALs). Ele cobre cada função na API e em qual versão do Keymaster essa função está disponível e descreve a implementação padrão. Para tags, consulte a página Tags do Keymaster .

Observação: para oferecer suporte à transição do Keymaster 3 do antigo HAL de estrutura C para a interface C++ HAL gerada a partir de uma definição na nova linguagem de definição de interface de hardware (HIDL), os nomes das funções foram alterados no Android 8.0. Para apoiar isso, as funções estão agora em camel case. Por exemplo, get_key_characteristics agora é getKeyCharacteristics .

Diretrizes gerais de implementação

As diretrizes a seguir se aplicam a todas as funções da 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 chamador não é obrigado a fornecer espaços reservados. Por exemplo, alguns tipos e modos de chave podem não usar nenhum valor do argumento inParams para begin , portanto, o chamador pode definir inParams como NULL ou fornecer um conjunto de parâmetros vazio. Os chamadores também podem fornecer parâmetros não utilizados e os métodos Keymaster não devem emitir erros.

Se um parâmetro de entrada obrigatório for NULL, os métodos Keymaster deverão retornar 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 de valor ou const.

Parâmetros do ponteiro de saída

Versão : 1, 2

Semelhante aos parâmetros de ponteiro de entrada, os parâmetros de ponteiro de saída não utilizados podem ser NULL . Se um método precisar retornar dados em um parâmetro de saída considerado NULL , ele deverá 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 de valor ou const.

Uso indevido de API

Versão : 1, 2, 3

Há muitas maneiras pelas quais os chamadores podem fazer solicitações que não fazem sentido ou que são tolas, mas que não são tecnicamente erradas. As implementações do Keymaster não precisam falhar nesses casos ou emitir um diagnóstico. O uso de chaves muito pequenas, a especificação de parâmetros de entrada irrelevantes, a reutilização de IVs ou nonces, a geração de chaves sem propósito (portanto inúteis) e similares não devem ser diagnosticados pelas implementações. A omissão de parâmetros obrigatórios, a especificação de parâmetros obrigatórios inválidos e erros semelhantes devem ser diagnosticados.

É responsabilidade dos aplicativos, da estrutura e do keystore do Android garantir que as chamadas aos módulos Keymaster sejam sensatas e úteis.

Funções

getHardwareFeatures

Versão : 3

O novo método getHardwareFeatures expõe aos clientes algumas características importantes do hardware seguro subjacente. O método não aceita argumentos e retorna quatro valores, todos booleanos:

isSecure é true se as chaves forem armazenadas em hardware seguro (TEE, etc.) e nunca saírem dele.
supportsEllipticCurve será true se o hardware suportar criptografia de curva elíptica com as curvas NIST (P-224, P-256, P-384 e P-521).
supportsSymmetricCryptography será true se o hardware suportar criptografia simétrica, incluindo AES e HMAC.
supportsAttestation será true se o hardware suportar a geração de certificados de atestado de chave pública Keymaster, assinados com uma chave injetada em um ambiente seguro.

Os únicos códigos de erro que este 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 seguro.

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 obsoleta no Keymaster 3, pois esta informação está disponível nos arquivos de propriedades do sistema e as implementações do fabricante leem esses arquivos durante a inicialização.

Configura o keymaster. Este método é chamado uma vez após o dispositivo ser aberto e antes de ser usado. É usado para fornecer KM_TAG_OS_VERSION e KM_TAG_OS_PATCHLEVEL ao keymaster. Até que este método seja chamado, todos os outros métodos retornam KM_ERROR_KEYMASTER_NOT_CONFIGURED . Os valores fornecidos por este método são aceitos pelo keymaster apenas uma vez por inicialização. As chamadas subsequentes retornam KM_ERROR_OK , mas não fazem nada.

Se a implementação do keymaster estiver em hardware seguro e a versão do sistema operacional e os valores de nível de patch fornecidos não corresponderem aos valores fornecidos ao hardware seguro pelo bootloader (ou se o bootloader não forneceu valores), então este método retornará KM_ERROR_INVALID_ARGUMENT e todos os outros os métodos 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

Esta função foi introduzida no Keymaster 1 como add_rng_entropy e renomeada no Keymaster 3.

Adiciona entropia fornecida pelo chamador ao pool usado pela implementação do Keymaster 1 para gerar números aleatórios, para chaves, IVs, etc.

As implementações do Keymaster precisam misturar com segurança a entropia fornecida em seu pool, que também deve conter entropia gerada internamente a partir de um gerador de números aleatórios de hardware. A mistura deve ser tratada de forma que um invasor que tenha controle completo dos bits fornecidos pelo addRngEntropy ou dos bits gerados por hardware, mas não de ambos, não tenha nenhuma vantagem não negligenciável na previsão dos bits gerados a partir do pool de entropia.

As implementações do Keymaster que tentam estimar a entropia em seu pool interno assumem que os dados fornecidos por addRngEntropy não contêm entropia. As implementações do Keymaster podem retornar ErrorCode::INVALID_INPUT_LENGTH se receberem mais de 2 KiB de dados em uma única chamada.

gerarKey

Versão : 1, 2, 3

Esta 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 estão permanentemente vinculadas à chave. As implementações do Keymaster tornam impossível usar uma chave de qualquer forma inconsistente com as autorizações especificadas no momento da geração. Com relação às autorizações que o hardware seguro não pode impor, a obrigação do hardware seguro limita-se a garantir que as autorizações inexequíveis associadas à chave não possam ser modificadas, de modo que cada chamada para getKeyCharacteristics retorne o valor original. Além disso, as características retornadas por generateKey alocam autorizações corretamente entre as listas impostas por hardware e impostas por software. Consulte getKeyCharacteristics para obter mais detalhes.

Os parâmetros fornecidos para generateKey dependem do tipo de chave que está sendo gerada. 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 suportados são 1.024, 2.048, 3.072 e 4.096. Os valores recomendados são todos os tamanhos de chave 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 suportados são 3 e 65537. Os valores recomendados são todos 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 retorna um erro se esses parâmetros forem omitidos.

Tag::PURPOSE especifica finalidades permitidas. Todas as finalidades precisam ser suportadas por chaves RSA, em qualquer combinação.
Tag::DIGEST especifica algoritmos de resumo que podem ser usados com a nova chave. As implementações que não suportam todos os algoritmos de resumo precisam aceitar solicitações de geração de chaves que incluem resumos não suportados. Os resumos não suportados devem ser colocados na lista "aplicada por software" nas principais características retornadas. Isso ocorre porque a chave pode ser usada com esses outros resumos, mas o resumo é executado no software. Em seguida, o hardware é chamado para realizar a operação com Digest::NONE .
Tag::PADDING especifica os modos de preenchimento 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_PSS e PaddingMode::RSA_OAEP na lista de características principais imposta por software se algum algoritmo de resumo não suportado for especificado.

Chaves ECDSA

Apenas Tag::KEY_SIZE é necessário para gerar uma chave ECDSA. É usado para selecionar o grupo EC. Os valores suportados são 224, 256, 384 e 521, que indicam as 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 é necessário para geração.

Chaves AES

Apenas Tag::KEY_SIZE é necessário para gerar uma chave AES. Se omitido, o método retornará ErrorCode::UNSUPPORTED_KEY_SIZE . Os valores suportados são 128 e 256, com suporte opcional para chaves AES de 192 bits.

Os seguintes parâmetros são particularmente relevantes para chaves AES, mas não são necessários para gerar uma:

Tag::BLOCK_MODE especifica os modos de bloco com os quais a nova chave pode ser usada.
Tag::PADDING especifica os modos de preenchimento que podem ser usados. Isto é relevante apenas para os modos BCE e CBC.

Se o modo de bloco GCM for especificado, forneça Tag::MIN_MAC_LENGTH . Se omitido, o método retorna 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 necessários para geração de chave 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 são suportados. Todos os múltiplos de 8, de 64 a 512, são suportados. Valores maiores podem ser suportados.
Tag::MIN_MAC_LENGTH especifica o comprimento mínimo de MACs que podem ser gerados ou verificados com esta chave. O valor é um múltiplo de 8 e pelo menos 64.
Tag::DIGEST especifica o algoritmo de resumo para a chave. Exatamente um resumo é especificado, caso contrário, retorne ErrorCode::UNSUPPORTED_DIGEST . Se o resumo não for suportado pelo trustlet, retorne ErrorCode::UNSUPPORTED_DIGEST .

Caracteristicas principais

Se o argumento de características não for NULL, generateKey retornará as características da chave recém-gerada divididas apropriadamente em listas impostas por hardware e impostas por software. Consulte getKeyCharacteristics para obter uma descrição de quais características vão em qual lista. As características retornadas incluem todos os parâmetros especificados para geração de chave, exceto Tag::APPLICATION_ID e Tag::APPLICATION_DATA . Se essas tags foram incluídas nos parâmetros-chave, elas serão removidas das características retornadas para que não seja possível encontrar seus valores examinando o blob-chave retornado. No entanto, eles estão criptograficamente vinculados ao blob de chave, de modo que, se os valores corretos não forem fornecidos quando a chave for usada, o uso falhará. Da mesma forma, Tag::ROOT_OF_TRUST está criptograficamente vinculado à chave, mas pode não ser especificado durante a criação ou importação da chave e nunca é retornado.

Além das tags fornecidas, o trustlet também adiciona Tag::ORIGIN , com o valor KeyOrigin::GENERATED , e se a chave for resistente a rollback,

Etiqueta::ROLLBACK_RESISTANT .

Resistência à reversão

A resistência à reversão significa que, uma vez excluída uma chave com deleteKey ou deleteAllKeys , é garantido por hardware seguro que ela nunca mais poderá ser usada. Implementações sem resistência à reversão normalmente retornam material de chave gerado ou importado para o chamador como um blob de chave, um formato criptografado e autenticado. Quando o keystore exclui o blob de chave, a chave desaparece, mas um invasor que já conseguiu recuperar o material da chave pode potencialmente restaurá-lo no dispositivo.

Uma chave é resistente à reversão se o hardware seguro garantir que as chaves excluídas não possam ser restauradas posteriormente. Isso geralmente é feito armazenando metadados de chave adicionais em um local confiável que não pode ser manipulado por um invasor. Em dispositivos móveis, o mecanismo usado para isso geralmente é o Replay Protected Memory Blocks (RPMB). Como o número de chaves que podem ser criadas é essencialmente ilimitado e o armazenamento confiável usado para resistência à reversão pode ser limitado em tamanho, esse método precisa ser bem-sucedido mesmo que a resistência à reversão não possa ser fornecida para a nova chave. Nesse caso, Tag::ROLLBACK_RESISTANT não deve ser adicionado às características principais.

getKeyCharacteristics

Versão : 1, 2, 3

Esta função foi introduzida no Keymaster 1 como get_key_characteristics e renomeada no Keymaster 3.

Retorna parâmetros e autorizações associados à chave fornecida, divididos em dois conjuntos: impostos por hardware e impostos por software. A descrição aqui se aplica igualmente às listas de características principais retornadas por generateKey e importKey .

Se Tag::APPLICATION_ID foi fornecido durante a geração ou importação da chave, o mesmo valor será fornecido a este método no argumento clientId . Caso contrário, o método retornará 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 a este método no argumento appData .

As características retornadas por este método descrevem completamente o tipo e o uso da chave especificada.

A regra geral para decidir se uma determinada etiqueta pertence à lista imposta por hardware ou imposta por software é que se o significado da etiqueta for totalmente garantido por hardware seguro, ela será aplicada por hardware. Caso contrário, é aplicado por software. Abaixo está uma lista de tags específicas cuja alocação correta pode não ser clara:

Tag::ALGORITHM , Tag::KEY_SIZE e Tag::RSA_PUBLIC_EXPONENT são propriedades intrínsecas da chave. Para qualquer chave protegida por hardware, essas tags estarão na lista imposta por hardware.
Os valores Tag::DIGEST que são suportados pelo hardware seguro são colocados na lista de hardware suportado. Os resumos não suportados vão para a lista de software suportado.
Os valores de Tag::PADDING geralmente vão para a lista de suporte de hardware, a menos que haja a possibilidade de que um modo de preenchimento específico precise ser executado por software. Nesse caso, eles vão para a lista imposta por software. Tal possibilidade surge para chaves RSA que permitem preenchimento PSS ou OAEP com algoritmos de resumo que não são suportados pelo hardware seguro.
Tag::USER_SECURE_ID e Tag::USER_AUTH_TYPE serão impostos por hardware somente se a autenticação do usuário for imposta por hardware. Para conseguir isso, o trustlet Keymaster e o trustlet de autenticação relevante devem ser seguros e compartilhar uma chave HMAC secreta usada para assinar e validar tokens de autenticação. Consulte a página Autenticação para obter detalhes.
As tags Tag::ACTIVE_DATETIME , Tag::ORIGINATION_EXPIRE_DATETIME e Tag::USAGE_EXPIRE_DATETIME exigem acesso a um relógio de parede comprovadamente correto. A maioria dos hardwares seguros só tem acesso às informações de tempo fornecidas pelo sistema operacional não seguro, o que significa que as tags são aplicadas por software.
Tag::ORIGIN está sempre na lista de hardware para chaves vinculadas a hardware. Sua presença nessa lista é a forma como as camadas superiores determinam que uma chave é suportada por hardware.

chave de importação

Versão : 1, 2, 3

Esta função foi introduzida no Keymaster 1 como import_key e renomeada no Keymaster 3.

Importa material chave para o hardware Keymaster. Os parâmetros de definição de chave e as características de saída são tratados da mesma forma que para 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. Se não for fornecido, o trustlet deduz os valores do material-chave fornecido e adiciona tags e valores apropriados às características-chave. Se os parâmetros forem fornecidos, o trustlet os validará em relação ao material chave. Em caso de incompatibilidade, o método retorna ErrorCode::IMPORT_PARAMETER_MISMATCH .
O Tag::ORIGIN retornado tem o mesmo valor que KeyOrigin::IMPORTED .

chave de exportação

Versão : 1, 2, 3

Esta 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 Keymaster RSA ou EC.

deleteKey

Versão : 1, 2, 3

Esta função foi introduzida no Keymaster 1 como delete_key e renomeada no Keymaster 3.

Exclui a chave fornecida. Este método é opcional e só é implementado por módulos Keymaster que fornecem resistência à reversão.

excluir todas as chaves

Versão : 1, 2, 3

Esta função foi introduzida no Keymaster 1 como delete_all_keys e renomeada no Keymaster 3.

Exclui todas as chaves. Este método é opcional e só é implementado por módulos Keymaster que fornecem resistência à reversão.

destruirAtestadoIds

Versão : 3

O método destroyAttestationIds() é usado para desabilitar permanentemente o novo recurso de atestado de ID (opcional, mas altamente recomendado). Se o TEE não tiver como garantir que o atestado de ID seja permanentemente desativado após esse método ser chamado, então o atestado de ID não deverá ser implementado; nesse caso, esse método não fará nada e retornará ErrorCode::UNIMPLEMENTED . Se o atestado de ID for compatível, esse método precisará ser implementado e desabilitar permanentemente todas as tentativas futuras de atestado de ID. O método pode ser chamado inúmeras vezes. Se o atestado de ID já estiver desabilitado permanentemente, o método não fará nada e retornará ErrorCode::OK .

Os únicos códigos de erro que este método pode retornar são ErrorCode::UNIMPLEMENTED (se o atestado de ID não for suportado), ErrorCode:OK , ErrorCode::KEYMASTER_NOT_CONFIGURED ou um dos códigos de erro indicando uma falha na comunicação com o hardware seguro.

começar

Versão : 1, 2, 3

Inicia uma operação criptográfica, usando a chave especificada, para a finalidade especificada, com os parâmetros especificados (conforme apropriado) e retorna um identificador de operação que é usado com update e finish para concluir a operação. O identificador de operação também é usado como token de "desafio" em operações autenticadas e, para tais operações, é incluído no campo challenge do token de autenticação.

Uma implementação Keymaster suporta pelo menos 16 operações simultâneas. O Keystore usa até 15, deixando um para o vold usar para criptografia de senha. Quando o Keystore tem 15 operações em andamento ( begin foi chamado, mas finish ou abort ainda não foram chamados) e recebe uma solicitação para iniciar a 16ª, ele chama abort na operação usada menos recentemente para reduzir o número de operações ativas para 14 antes de iniciar a chamada para begin a operação recém-solicitada.

Se Tag::APPLICATION_ID ou Tag::APPLICATION_DATA foram especificados durante a geração ou importação de chave, as chamadas begin incluem essas tags com os valores originalmente especificados no argumento inParams para esse método.

Aplicação de autorização

Durante este método, as seguintes autorizações de chave serão impostas pelo trustlet se a implementação as tiver colocado nas características "impostas por hardware" e se a operação não for uma operação de chave pública. As operações de chave pública, ou seja, KeyPurpose::ENCRYPT e KeyPurpose::VERIFY , com chaves RSA ou EC, podem ter sucesso mesmo se os requisitos de autorização não forem atendidos.

Tag::PURPOSE : O propósito especificado na chamada begin() deve corresponder a um dos propósitos nas autorizações de chave, a menos que a operação solicitada seja uma operação de chave pública. Se a finalidade especificada não corresponder e a operação não for uma operação de chave pública, begin retornará ErrorCode::UNSUPPORTED_PURPOSE . As operações de chave pública são operações de criptografia ou verificação assimétrica.
Tag::ACTIVE_DATETIME só pode ser aplicado se uma fonte de horário UTC confiável estiver disponível. Se a data e hora atuais forem anteriores ao valor da tag, o método retornará ErrorCode::KEY_NOT_YET_VALID .
Tag::ORIGINATION_EXPIRE_DATETIME só pode ser aplicada se uma fonte de horário UTC confiável estiver disponível. Se a data e hora atuais forem posteriores ao valor da tag e a finalidade for KeyPurpose::ENCRYPT ou KeyPurpose::SIGN , o método retornará ErrorCode::KEY_EXPIRED .
Tag::USAGE_EXPIRE_DATETIME só pode ser aplicada se uma fonte de horário UTC confiável estiver disponível. Se a data e hora atuais forem posteriores ao valor da tag e a finalidade for KeyPurpose::DECRYPT ou KeyPurpose::VERIFY , o método retornará ErrorCode::KEY_EXPIRED .
Tag::MIN_SECONDS_BETWEEN_OPS é comparado com um temporizador relativo confiável que indica o último uso da chave. Se o tempo do último uso mais o valor da tag for menor que o tempo atual, o método retornará ErrorCode::KEY_RATE_LIMIT_EXCEEDED . Consulte a descrição da tag para obter detalhes importantes de implementação.
Tag::MAX_USES_PER_BOOT é comparado 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 método retornará ErrorCode::KEY_MAX_OPS_EXCEEDED .
Tag::USER_SECURE_ID é aplicado por este método somente se a chave também tiver Tag::AUTH_TIMEOUT . Se a chave tiver ambos, então este método deverá receber um Tag::AUTH_TOKEN válido em inParams . Para que o token de autenticação seja válido, todas as afirmações a seguir devem ser verdadeiras:
- O campo HMAC é validado corretamente.
- Pelo menos um dos valores Tag::USER_SECURE_ID da chave corresponde a pelo menos um dos valores de ID seguro no token.
- A chave possui uma Tag::USER_AUTH_TYPE que corresponde ao tipo de autenticação 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 chamador especifique um nonce ou vetor de inicialização (IV). Se a chave não tiver essa tag, mas o chamador forneceu Tag::NONCE para esse método, ErrorCode::CALLER_NONCE_PROHIBITED será retornado.
Tag::BOOTLOADER_ONLY especifica que apenas o bootloader pode usar a chave. Se este método for chamado com uma chave somente do bootloader após a conclusão da execução do bootloader, ele retornará ErrorCode::INVALID_KEY_BLOB .

Chaves RSA

Todas as operações de chave RSA especificam exatamente um modo de preenchimento 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 assinatura e verificação RSA precisam de um resumo, assim como as operações de criptografia e descriptografia RSA com modo de preenchimento OAEP. Para esses casos, o chamador 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 .

As operações de chave privada ( KeyPurpose::DECYPT e KeyPurpose::SIGN ) precisam de autorização de resumo e preenchimento, o que significa que as autorizações de chave precisam conter os valores especificados. Caso contrário, o método retornará ErrorCode::INCOMPATIBLE_DIGEST ou ErrorCode::INCOMPATIBLE_PADDING , conforme apropriado. Operações de chave pública ( KeyPurpose::ENCRYPT e KeyPurpose::VERIFY ) são permitidas com resumo ou preenchimento não autorizado.

Com exceção de PaddingMode::NONE , todos os modos de preenchimento RSA são aplicáveis apenas para determinadas finalidades. Especificamente, PaddingMode::RSA_PKCS1_1_5_SIGN e PaddingMode::RSA_PSS suportam apenas assinatura e verificação, enquanto PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT e PaddingMode::RSA_OAEP suportam apenas criptografia e descriptografia. O método retorna ErrorCode::UNSUPPORTED_PADDING_MODE se o modo especificado não oferece suporte à finalidade especificada.

Existem algumas interações importantes entre modos de preenchimento e resumos:

PaddingMode::NONE indica que uma operação RSA "bruta" é executada. Se estiver assinando ou verificando, Digest::NONE será especificado para o resumo. Nenhum resumo é necessário para criptografia ou descriptografia não preenchida.
O preenchimento PaddingMode::RSA_PKCS1_1_5_SIGN requer um resumo. O resumo pode ser Digest::NONE , caso em que a implementação do Keymaster não pode construir uma estrutura de assinatura PKCS#1 v1.5 adequada, porque não pode adicionar a estrutura DigestInfo. Em vez disso, a implementação constrói 0x00 || 0x01 || PS || 0x00 || M , onde M é a mensagem fornecida e PS é a sequência de preenchimento. O tamanho da chave RSA deve ser pelo menos 11 bytes maior que a mensagem, caso contrário o método retornará ErrorCode::INVALID_INPUT_LENGTH .
O preenchimento PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT não requer um resumo.
O preenchimento PaddingMode::RSA_PSS requer um resumo, que pode não ser Digest::NONE . Se Digest::NONE for especificado, o método retornará ErrorCode::INCOMPATIBLE_DIGEST . Além disso, o tamanho da chave RSA deve ser pelo menos 2 + D bytes maior que o tamanho de saída 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 preenchimento PaddingMode::RSA_OAEP requer um resumo, que pode não ser Digest::NONE . Se Digest::NONE for especificado, o método retornará ErrorCode::INCOMPATIBLE_DIGEST .

Chaves CE

As operações da tecla EC especificam exatamente um modo de preenchimento 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 chave privada ( KeyPurpose::SIGN ) precisam de autorização de resumo e preenchimento, o que significa que as autorizações de chave precisam conter os valores especificados. Caso contrário, retorne ErrorCode::INCOMPATIBLE_DIGEST . Operações de chave pública ( KeyPurpose::VERIFY ) são permitidas com resumo ou preenchimento não autorizado.

Chaves AES

As operações de chave AES especificam exatamente um modo de bloco e um modo de preenchimento em inParams . Se um dos valores não for especificado ou for especificado mais de uma vez, retorne ErrorCode::UNSUPPORTED_BLOCK_MODE ou ErrorCode::UNSUPPORTED_PADDING_MODE . Os modos especificados devem ser autorizados pela chave, caso contrário o método retornará ErrorCode::INCOMPATIBLE_BLOCK_MODE ou ErrorCode::INCOMPATIBLE_PADDING_MODE .

Se o modo de bloco for BlockMode::GCM , inParams especifica Tag::MAC_LENGTH e o valor especificado é um múltiplo de 8 que não é maior que 128 ou menor que o valor de Tag::MIN_MAC_LENGTH nas autorizações de chave. Para comprimentos MAC maiores que 128 ou não múltiplos de 8, retorne ErrorCode::UNSUPPORTED_MAC_LENGTH . Para valores menores que o comprimento mínimo da chave, retorne ErrorCode::INVALID_MAC_LENGTH .

Se o modo de bloco for BlockMode::GCM ou BlockMode::CTR , o modo de preenchimento especificado deverá ser PaddingMode::NONE . Para BlockMode::ECB ou BlockMode::CBC , o modo pode ser PaddingMode::NONE ou PaddingMode::PKCS7 . Se o modo de preenchimento não atender a essas condições, retorne ErrorCode::INCOMPATIBLE_PADDING_MODE .

Se o modo de bloco for BlockMode::CBC , BlockMode::CTR ou BlockMode::GCM , um vetor de inicialização ou nonce será necessário. Na maioria dos casos, os chamadores não devem fornecer IV ou nonce. Nesse caso, a implementação do Keymaster gera um IV ou nonce aleatório e o retorna via Tag::NONCE em outParams . CBC e CTR IVs têm 16 bytes. Os nonces do GCM têm 12 bytes. Se as autorizações de chave contiverem Tag::CALLER_NONCE , o chamador poderá fornecer um IV/nonce com Tag::NONCE em inParams . Se um nonce for fornecido quando Tag::CALLER_NONCE não for autorizado, retorne ErrorCode::CALLER_NONCE_PROHIBITED . Se um nonce não for fornecido quando Tag::CALLER_NONCE for autorizado, gere um IV/nonce aleatório.

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 comprimento do resumo nem menor que o valor de Tag::MIN_MAC_LENGTH nas autorizações de chave. Para comprimentos MAC maiores que o comprimento do resumo ou não múltiplos de 8, retorne ErrorCode::UNSUPPORTED_MAC_LENGTH . Para valores menores que o comprimento mínimo da chave, retorne ErrorCode::INVALID_MAC_LENGTH .

atualizar

Versão : 1, 2, 3

Fornece dados para processar em uma operação contínua iniciada com start . A operação é especificada pelo parâmetro operationHandle .

Para fornecer mais flexibilidade no manuseio do buffer, as implementações deste método têm a opção de consumir menos dados do que os fornecidos. O chamador é responsável pelo loop para alimentar o restante dos dados nas chamadas subsequentes. A quantidade de entrada consumida é retornada no parâmetro inputConsumed . As implementações sempre consomem pelo menos um byte, a menos que a operação não possa aceitar mais; se mais de zero bytes forem fornecidos e zero bytes forem consumidos, os chamadores consideram isso um erro e abortam a operação.

As implementações também podem escolher quantos dados retornar, como resultado da atualização. Isso só é relevante para operações de criptografia e descriptografia, porque a assinatura e a verificação não retornam dados até o término . Retorne os dados o mais cedo possível, em vez de armazená-los em buffer.

Manipulação de erros

Se este método retornar um código de erro diferente de ErrorCode::OK , a operação será abortada e o identificador da operação será invalidado. Qualquer uso futuro do identificador, com este método, finish ou abort , retorna ErrorCode::INVALID_OPERATION_HANDLE .

Aplicação de autorização

A imposição de autorização de chave é executada principalmente em start . A única exceção é o caso em que a chave possui:

Uma ou mais Tag::USER_SECURE_IDs e
Não possui tag::AUTH_TIMEOUT

Neste caso, a chave requer uma autorização por operação, e o método update recebe um 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 da chave e contém o identificador da operação atual no campo de desafio. Se essas condições não forem atendidas, retorne ErrorCode::KEY_USER_NOT_AUTHENTICATED .

O chamador fornece o token de autenticação para cada chamada atualizar e finalizar . 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 , este método aceita que todo o bloco seja assinado ou verificado em uma única atualização. Não pode consumir apenas uma parte do bloco. No entanto, se o chamador optar por fornecer os dados em múltiplas atualizações, este método os aceitará. Se o chamador fornecer mais dados para assinar do que podem ser usados (o comprimento dos dados excede o tamanho da chave RSA), retorne ErrorCode::INVALID_INPUT_LENGTH .

Chaves ECDSA

Para operações de assinatura e verificação com Digest::NONE , este método aceita que todo o bloco seja assinado ou verificado em uma única atualização. Este método não pode consumir apenas uma parte do bloco.

No entanto, se o chamador optar por fornecer os dados em múltiplas atualizações, este método os aceitará. Se o chamador fornecer mais dados para assinar do que podem ser usados, os dados serão truncados silenciosamente. (Isso difere do tratamento do excesso de dados fornecidos em operações RSA semelhantes. A razão para isso é a compatibilidade com clientes legados.)

Chaves AES

O modo AES GCM suporta "dados de autenticação associados", fornecidos por meio da tag Tag::ASSOCIATED_DATA no argumento inParams . Os dados associados podem ser fornecidos em chamadas repetidas (importante se os dados forem muito grandes para serem enviados em um único bloco), mas sempre precedem os dados a serem criptografados ou descriptografados. Uma chamada de atualização pode receber dados associados e dados para criptografar/descriptografar, mas atualizações subsequentes podem não incluir dados associados. Se o chamador fornecer dados associados a uma chamada de atualização após uma chamada que inclui dados para criptografar/descriptografar, retorne ErrorCode::INVALID_TAG .

Para criptografia GCM, a tag é anexada ao texto cifrado por finish . Durante a descriptografia, os últimos Tag::MAC_LENGTH bytes dos dados fornecidos para a última chamada de atualização são a tag. Como uma determinada invocação de update não pode saber se é a última invocação, ela processa tudo, exceto o comprimento da tag, e armazena em buffer os possíveis dados da tag durante finish .

terminar

Versão : 1, 2, 3

Termina uma operação em andamento iniciada com start , processando todos os dados ainda não processados fornecidos por update (s).

Este método é o último chamado em uma operação; portanto, todos os dados processados são retornados.

Seja concluído com êxito ou retorna um erro, esse método finaliza a operação e, portanto, invalida o identificador de operação fornecido. Qualquer uso futuro do identificador, com este método ou atualização ou aborto , retorna ErrorCode::INVALID_OPERATION_HANDLE .

As operações de assinatura retornam a assinatura como saída. As operações de verificação aceitam a assinatura no parâmetro signature e retorne nenhuma saída.

Aplicação da autorização

A aplicação da autorização -chave é realizada principalmente no início . A única exceção é o caso em que 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 o método de atualização recebe uma 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 à tag da chave :: user_auth_type e contém o identificador de operação da operação atual no campo Desafio. Se essas condições não forem atendidas, retorne ErrorCode::KEY_USER_NOT_AUTHENTICATED .

O chamador fornece o token de autenticação para todas as chamadas para atualizar e terminar . A implementação precisa apenas validar o token uma vez se ele preferir.

RSA Keys

Alguns requisitos adicionais, dependendo do modo de preenchimento:

PaddingMode::NONE . Para operações de assinatura e criptografia não-incorporadas, se os dados fornecidos forem mais curtos que a chave, os dados ficarão com zero à esquerda antes de assinar/criptografia. Se os dados tiverem o mesmo comprimento que a chave, mas numericamente maior, retorne ErrorCode::INVALID_ARGUMENT . Para operações de verificação e descriptografia, os dados devem ser exatamente enquanto a chave. Caso contrário, retorne ErrorCode::INVALID_INPUT_LENGTH.
PaddingMode::RSA_PSS . Para operações de assinatura acolchoadas com PSS, o sal PSS é o tamanho do resumo da mensagem e gerado aleatoriamente. O resumo especificado com tag :: digers in inputParams no início é usado como algoritmo PSS Digest e como o algoritmo MGF1 Digest.
PaddingMode::RSA_OAEP . O resumo especificado com tag :: digers in inputParams no começo é usado como o algoritmo OAEP Digest, e o sha1 é usado como o algoritmo MGF1 Digest.

Chaves ECDSA

Se os dados fornecidos para assinatura ou verificação não incadicados forem muito longos, truque -os.

Aes Keys

Algumas condições adicionais, dependendo do modo de bloco:

BlockMode::ECB ou BlockMode::CBC . Se o preenchimento for PaddingMode::NONE e o comprimento dos dados não for um múltiplo do tamanho do bloco AES, retorne ErrorCode::INVALID_INPUT_LENGTH . Se o preenchimento for PaddingMode::PKCS7 , dê os dados de acordo com a especificação PKCS#7. Observe que o PKCS#7 recomenda adicionar um bloco de preenchimento adicional se os dados forem um múltiplo do comprimento do bloco.
BlockMode::GCM . Durante a criptografia, após o processamento de todo o texto simples, calcule a tag ( tag :: mac_length bytes) e anexá -lo ao CipherText devolvido. Durante a descriptografia, processe a última tag :: mac_length bytes como a tag. Se a verificação da tag falhar, retorne ErrorCode::VERIFICATION_FAILED .

abortar

Versão : 1, 2, 3

Aborta a operação em andamento. Após a chamada para abortar, retorne ErrorCode::INVALID_OPERATION_HANDLE para qualquer uso subsequente do identificador de operação fornecido com atualização , acabamento ou aborto .

get_supported_algorithms

Versão 1

Retorna a lista de algoritmos suportados pela implementação de hardware Keymaster. Uma implementação de software retorna uma lista vazia; Uma implementação híbrida retorna uma lista que contém apenas os algoritmos suportados pelo hardware.

As implementações da Keymaster 1 suportam RSA, CE, AES e HMAC.

get_supported_block_modes

Versão 1

Retorna a lista de modos de bloco AES suportados pela implementação de hardware Keymaster para um algoritmo e objetivo especificado.

Para RSA, CE e HMAC, que não são cifras de bloco, o método retorna uma lista vazia para todos os fins válidos. Os fins inválidos devem fazer com que o método retorne ErrorCode::INVALID_PURPOSE .

As implementações da Keymaster 1 suportam o BCE, CBC, CTR e GCM para criptografia e descriptografia de AES.

get_supported_padding_modes

Versão 1

Retorna a lista de modos de preenchimento suportados pela implementação de hardware Keymaster para um algoritmo e objetivo especificado.

HMAC e CE não têm noção de preenchimento, portanto o método retorna uma lista vazia para todos os fins válidos. Os fins inválidos devem fazer com que o método retorne ErrorCode::INVALID_PURPOSE .

Para RSA, Keymaster 1 implementações Suporte:

Criptografia, descriptografia, assinatura e verificação não nascadas. Para criptografia e assinatura não masbutas, se a mensagem for mais curta que o módulo público, as implementações deverão atingir-a com Zeros. Para descriptografia e verificação não masgidas, o comprimento da entrada deve corresponder ao tamanho do módulo público.
PKCS#1 V1.5 Criptografia e assinatura modos de preenchimento
PSS com um comprimento mínimo de sal de 20
OAEP

Para os modos de AES nos MEC e CBC, as implementações do Keymaster 1 não suportam o preenchimento e o PKCS#7-Padding. Os modos CTR e GCM suportam apenas nenhum preenchimento.

get_supported_digests

Versão 1

Retorna a lista de modos Digest suportados pela implementação de hardware Keymaster para um algoritmo e objetivo especificado.

Nenhum dos modos AES suporta ou requer digestão; portanto, o método retorna uma lista vazia para fins válidos.

As implementações do Keymaster 1 podem implementar um subconjunto dos digestos definidos. As implementações fornecem SHA-256 e podem fornecer MD5, SHA1, SHA-224, SHA-256, SHA384 e SHA512 (o conjunto completo de digestas definidas).

get_supported_import_formats

Versão 1

Retorna a lista de formatos de importação suportados pela implementação de hardware Keymaster de um algoritmo especificado.

As implementações do Keymaster 1 suportam o formato PKCS#8 (sem proteção de senha) para importar pares de chave RSA e CE e suportar a importação crua do material da chave AES e do HMAC.

get_supported_export_formats

Versão 1

Retorna a lista de formatos de exportação suportados pela implementação de hardware Keymaster de um algoritmo especificado.

As implementações da Keymaster1 suportam o formato X.509 para a exportação de chaves públicas RSA e CE. A exportação de chaves privadas ou chaves assimétricas não é suportada.

Funções históricas

Keymaster 0

As seguintes funções pertencem à definição original do Keymaster 0. Eles estavam presentes no keymaster 1 struct keymaster1_device_t. No entanto, no Keymaster 1.0, eles não foram implementados e seus ponteiros de função foram definidos como nulos.

generate_keypair
import_keypair
get_keypair_public
delete_keypair
delete_all
sign_data
Verify_data

Keymaster 1

As seguintes funções pertencem à definição Keymaster 1, mas foram removidas no Keymaster 2, juntamente com as funções Keymaster 0 listadas acima.

get_supported_algorithms
get_supported_block_modes
get_supported_padding_modes
get_supported_digests
get_supported_import_formats
get_supported_export_formats

Keymaster 2

As seguintes funções pertencem à definição Keymaster 2, mas foram removidas em Keymaster 3, juntamente com as funções Keymaster 1 listadas acima.

configure