Funções do Keymaster

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:

• isSecure será true se as chaves forem armazenadas em hardware protegido (TEE etc.) e nunca o deixe.
• supportsEllipticCurve é true se o suporte a criptografia de curva elíptica com as curvas NIST (P-224, P-256, P-384 e P-521).
• supportsSymmetricCryptography é true se o hardware oferecer suporte à criptografia simétrica, incluindo AES e HMAC.
• supportsAttestation é true se 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_PSS e PaddingMode::RSA_OAEP pol. 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_MODE especifica os modos de bloco com que a nova chave poderá ser usada.
• Tag::PADDING especifica 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, retornar ErrorCode::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,

Tag::ROLLBACK_RESISTANT.

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, begin retornará 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::ENCRYPT ou KeyPurpose::SIGN, o método retorna ErrorCode::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::DECRYPT ou KeyPurpose::VERIFY, o método retorna ErrorCode::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 inParams Para 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::NONE indica que um item "bruto" A operação RSA é realizada. Se você assinar ou verificar, Digest::NONE será 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_SIGN requer um resumo. A O resumo poderá ser Digest::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ói 0x00 || 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 retorna ErrorCode::INVALID_INPUT_LENGTH:
• O padding PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT não requer um resumo.
• O padding PaddingMode::RSA_PSS exige um resumo, que pode não ser Digest::NONE. Se Digest::NONE for especificado, o retorna ErrorCode::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_OAEP exige um resumo, que pode não ser Digest::NONE. Se Digest::NONE for especificado, o retorna ErrorCode::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, retorna ErrorCode::INVALID_ARGUMENT. Para de verificação e descriptografia, os dados devem ter exatamente como a chave. Caso contrário, retorna ErrorCode::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 em inputParams em begin é usado como o resumo PSS e como algoritmo de resumo MGF1.
• PaddingMode::RSA_OAEP: O resumo especificado com Tag::DIGEST em inputParams em 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::ECB ou BlockMode::CBC. Se o padding for PaddingMode::NONE e a o comprimento dos dados não é um múltiplo do tamanho do bloco AES, retorne ErrorCode::INVALID_INPUT_LENGTH. Se o padding for PaddingMode::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, devolva ErrorCode::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_keypair
• import_keypair
• get_keypair_public
• delete_keypair
• delete_all
• sign_data
• Verify_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_algorithms
• get_supported_block_modes
• get_supported_padding_modes
• get_supported_digests
• get_supported_import_formats
• get_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