Referência de estrutura keymaster2_device
#include < keymaster2.h >
Descrição detalhada
Definição do dispositivo Keymaster2
Definição na linha 28 do arquivo keymaster2.h .
Documentação de campo
| keymaster_error_t (* abortar)(const struct keymaster2_device *dev, keymaster_operação_handle_t operação_handle) |
Anula uma operação criptográfica iniciada com begin() , liberando todos os recursos internos e invalidando operation_handle .
Definição na linha 415 do arquivo keymaster2.h .
| keymaster_error_t (* add_rng_entropy)(const struct keymaster2_device *dev, const uint8_t *dados, size_t data_length) |
Adiciona entropia ao RNG usado pelo keymaster. É garantido que a entropia adicionada por meio deste método não seja a única fonte de entropia usada, e a função de mistura deve ser segura, no sentido de que se o RNG for semeado (de qualquer fonte) com quaisquer dados que o invasor não possa prever (ou controle), então a saída RNG é indistinguível da aleatória. Assim, se a entropia de qualquer fonte for boa, o resultado será bom.
- Parâmetros
[em] desenvolvedor A estrutura do dispositivo keymaster. [em] dados Dados aleatórios a serem misturados. [em] comprimento_dados Comprimento dos data.
Definição na linha 74 do arquivo keymaster2.h .
| keymaster_error_t (* attest_key)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key_to_attest, const keymaster_key_param_set_t *attest_params, keymaster_cert_chain_t *cert_chain) |
Gera uma cadeia de certificados X.509 assinada atestando a presença de key_to_attest no keymaster (TODO(swillden): Descreva o conteúdo do certificado com mais detalhes). O certificado conterá uma extensão com OID 1.3.6.1.4.1.11129.2.1.17 e valor definido em <TODO:swillden – insira link aqui> que contém a descrição da chave.
- Parâmetros
[em] desenvolvedor A estrutura do dispositivo keymaster. [em] chave_para_atestar A chave mestra para a qual o certificado de atestado será gerado. [em] attest_params Parâmetros que definem como fazer o atestado. Atualmente o único parâmetro é KM_TAG_ALGORITHM, que deve ser KM_ALGORITHM_EC ou KM_ALGORITHM_RSA. Isso seleciona qual das chaves de atestado provisionadas será usada para assinar o certificado. [fora] cadeia_certificada Uma matriz de certificados X.509 codificados por DER. O primeiro será o certificado para key_to_attest. As entradas restantes serão encadeadas de volta à raiz. O chamador assume a propriedade e deve desalocar keymaster_free_cert_chain.
Definição na linha 239 do arquivo keymaster2.h .
| keymaster_error_t (* começar)(const struct keymaster2_device *dev, keymaster_purpose_t propósito, const keymaster_key_blob_t *key, const keymaster_key_param_set_t *in_params, keymaster_key_param_set_t *out_params, keymaster_operation_handle_t *operation_handle) |
Inicia uma operação criptográfica usando a chave especificada. Se tudo estiver bem, begin() retornará KM_ERROR_OK e criará um identificador de operação que deve ser passado para chamadas subsequentes para update() , finish() ou abort() .
É fundamental que cada chamada para Begin() seja emparelhada com uma chamada subsequente para Finish() ou abort() , para permitir que a implementação do keymaster limpe qualquer estado de operação interna. Deixar de fazer isso pode vazar espaço de estado interno ou outros recursos internos e pode eventualmente fazer com que Begin() retorne KM_ERROR_TOO_MANY_OPERATIONS quando ficar sem espaço para operações. Qualquer resultado diferente de KM_ERROR_OK de Begin() , update() ou Finish() aborta implicitamente a operação, caso em que abort() não precisa ser chamado (e retornará KM_ERROR_INVALID_OPERATION_HANDLE se chamado).
- Parâmetros
[em] desenvolvedor A estrutura do dispositivo keymaster. [em] propósito A finalidade da operação, KM_PURPOSE_ENCRYPT, KM_PURPOSE_DECRYPT, KM_PURPOSE_SIGN ou KM_PURPOSE_VERIFY. Observe que para os modos AEAD, a criptografia e a descriptografia implicam assinatura e verificação, respectivamente, mas devem ser especificadas como KM_PURPOSE_ENCRYPT e KM_PURPOSE_DECRYPT. [em] chave A chave a ser usada para a operação. keydeve ter uma finalidade compatível compurposee todos os seus requisitos de uso devem ser satisfeitos, ou o start() retornará um código de erro apropriado.[em] in_params Parâmetros adicionais para a operação. Normalmente é usado para fornecer dados de autenticação, com KM_TAG_AUTH_TOKEN. Se KM_TAG_APPLICATION_ID ou KM_TAG_APPLICATION_DATA foram fornecidos durante a geração, eles deverão ser fornecidos aqui ou a operação falhará com KM_ERROR_INVALID_KEY_BLOB. Para operações que requerem um nonce ou IV, em chaves que foram geradas com KM_TAG_CALLER_NONCE, in_params pode conter uma tag KM_TAG_NONCE. [fora] out_params Parâmetros de saída. Usado para retornar dados adicionais da inicialização da operação, principalmente para retornar o IV ou nonce de operações que geram um IV ou nonce. O chamador assume a propriedade da matriz de parâmetros de saída e deve liberá-la com keymaster_free_param_set() . out_params pode ser definido como NULL se nenhum parâmetro de saída for esperado. Se out_params for NULL e parâmetros de saída forem gerados, Begin() retornará KM_ERROR_OUTPUT_PARAMETER_NULL. [fora] operação_handle O identificador de operação recém-criado que deve ser passado para update() , finish() ou abort() . Se Operation_Handle for NULL, Begin() retornará KM_ERROR_OUTPUT_PARAMETER_NULL.
Definição na linha 332 do arquivo keymaster2.h .
| estrutura hw_device_t comum |
Métodos comuns do dispositivo keymaster. Este deve ser o primeiro membro de keymaster_device, pois os usuários desta estrutura lançarão um ponteiro hw_device_t para keymaster_device em contextos onde é conhecido que hw_device_t faz referência a um keymaster_device.
Definição na linha 35 do arquivo keymaster2.h .
| keymaster_error_t (* configurar)(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params) |
Configura o keymaster. Este método deve ser 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 retornarão 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 retornarão KM_ERROR_OK, mas não farão 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 outros métodos continuarão retornando KM_ERROR_KEYMASTER_NOT_CONFIGURED.
Definição na linha 58 do arquivo keymaster2.h .
| contexto vazio* |
Definição na linha 37 do arquivo keymaster2.h .
| keymaster_error_t (* delete_all_keys)(const estrutura keymaster2_device *dev) |
Exclui todas as chaves do armazenamento de chaves de hardware. Usado quando o keystore é completamente redefinido. Depois de chamar esta função, será impossível usar quaisquer blobs de chaves gerados ou importados anteriormente para qualquer operação.
Esta função é opcional e deve ser definida como NULL se não for implementada.
- Parâmetros
[em] desenvolvedor A estrutura do dispositivo keymaster.
Definição na linha 288 do arquivo keymaster2.h .
| keymaster_error_t (* delete_key)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key) |
Exclui a chave, ou par de chaves, associada ao blob de chaves. Após chamar esta função será impossível utilizar a chave para quaisquer outras operações. Pode ser aplicado a chaves de raízes de confiança estrangeiras (chaves não utilizáveis na raiz de confiança atual).
Esta função é opcional e deve ser definida como NULL se não for implementada.
- Parâmetros
[em] desenvolvedor A estrutura do dispositivo keymaster. [em] chave A chave a ser excluída.
Definição na linha 276 do arquivo keymaster2.h .
| keymaster_error_t (* export_key)(const struct keymaster2_device *dev, keymaster_key_format_t export_format, const keymaster_key_blob_t *key_to_export, const keymaster_blob_t *client_id, const keymaster_blob_t *app_data, keymaster_blob_t *export_data) |
Exporta uma chave pública ou simétrica, retornando uma matriz de bytes no formato especificado.
Observe que a exportação de chave simétrica só será permitida se a chave tiver sido criada com KM_TAG_EXPORTABLE e somente se todos os requisitos para uso da chave (por exemplo, autenticação) forem atendidos.
- Parâmetros
[em] desenvolvedor A estrutura do dispositivo keymaster. [em] formato_exportação O formato a ser usado para exportar a chave. [em] chave_para_exportar A chave para exportar. [em] ID do Cliente Blob de ID do cliente, que deve corresponder ao blob fornecido em KM_TAG_APPLICATION_ID durante a geração da chave (se houver). [em] dados do aplicativo Blob de dados do aplicativo, que deve corresponder ao blob fornecido em KM_TAG_APPLICATION_DATA durante a geração da chave (se houver). [fora] exportar dados O material chave exportado. O chamador assume a propriedade.
Definição na linha 213 do arquivo keymaster2.h .
| keymaster_error_t (* terminar)(const struct keymaster2_device *dev, keymaster_operation_handle_t operation_handle, const keymaster_key_param_set_t *in_params, const keymaster_blob_t *input, const keymaster_blob_t *signature, keymaster_key_param_set_t *out_params, keymaster_blob_t *output) |
Finaliza uma operação criptográfica iniciada com start() e invalida operation_handle .
- Parâmetros
[em] desenvolvedor A estrutura do dispositivo keymaster. [em] operação_handle O identificador de operação retornado por Begin() . Este identificador será invalidado. [em] in_params Parâmetros adicionais para a operação. Para modos AEAD, isso é usado para especificar KM_TAG_ADDITIONAL_DATA, mas somente se nenhum dado de entrada tiver sido fornecido para update() . [em] entrada Dados a serem processados, conforme parâmetros estabelecidos na chamada de begin() . finish() deve consumir todos os dados fornecidos ou retornar KM_ERROR_INVALID_INPUT_LENGTH. [em] assinatura A assinatura a ser verificada se o propósito especificado na chamada Begin() for KM_PURPOSE_VERIFY. [fora] saída Os dados de saída, se houver. O chamador assume a propriedade do buffer alocado.
Se a operação que está sendo concluída for uma verificação de assinatura ou uma descriptografia e verificação no modo AEAD falhar, então finish() retornará KM_ERROR_VERIFICATION_FAILED.
Definição na linha 405 do arquivo keymaster2.h .
| sinalizadores uint32_t |
Consulte os sinalizadores definidos para keymaster0_devices::flags em keymaster_common.h . Usado apenas para compatibilidade com versões anteriores; Os dispositivos de hardware keymaster2 devem definir isso como zero.
Definição na linha 43 do arquivo keymaster2.h .
| keymaster_error_t (* generate_key)(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params, keymaster_key_blob_t *key_blob, keymaster_key_characteristics_t *características) |
Gera uma chave, ou par de chaves, retornando um blob de chave e/ou uma descrição da chave.
Os parâmetros de geração de chave são definidos como pares de tag/valor keymaster, fornecidos em params . Veja keymaster_tag_t para a lista completa. Alguns valores que são sempre necessários para a geração de chaves úteis são:
- KM_TAG_ALGORITMO;
- KM_TAG_PURPOSE; e
- (KM_TAG_USER_SECURE_ID e KM_TAG_USER_AUTH_TYPE) ou KM_TAG_NO_AUTH_REQUIRED.
KM_TAG_AUTH_TIMEOUT geralmente deve ser especificado, a menos que KM_TAG_NO_AUTH_REQUIRED esteja presente, ou o usuário terá que se autenticar para cada uso.
KM_TAG_BLOCK_MODE, KM_TAG_PADDING, KM_TAG_MAC_LENGTH e KM_TAG_DIGEST devem ser especificados para algoritmos que os exigem.
As tags a seguir não podem ser especificadas; seus valores serão fornecidos pela implementação.
- KM_TAG_ORIGIN,
- KM_TAG_ROLLBACK_RESISTANT,
- KM_TAG_CREATION_DATETIME
- Parâmetros
[em] desenvolvedor A estrutura do dispositivo keymaster. [em] parâmetros Matriz de parâmetros de geração de chave [fora] key_blob retorna a chave gerada. key_blobnão deve ser NULO. O chamador assume a propriedade key_blob->key_material e deve free() .[fora] características retorna as características da chave que foi gerada, se não for NULL. Se não for NULL, o chamador assume a propriedade e deve desalocar com keymaster_free_characteristics() . Observe que KM_TAG_ROOT_OF_TRUST, KM_TAG_APPLICATION_ID e KM_TAG_APPLICATION_DATA nunca são retornados.
Definição na linha 112 do arquivo keymaster2.h .
| keymaster_error_t (* get_key_characteristics)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key_blob, const keymaster_blob_t *client_id, const keymaster_blob_t *app_data, keymaster_key_characteristics_t *características) |
Retorna as características da chave especificada ou KM_ERROR_INVALID_KEY_BLOB se key_blob for inválido (as implementações devem validar totalmente a integridade da chave). client_id e app_data devem ser o ID e os dados fornecidos quando a chave foi gerada ou importada, ou vazios se KM_TAG_APPLICATION_ID e/ou KM_TAG_APPLICATION_DATA não foram fornecidos durante a geração. Esses valores não estão incluídos nas características retornadas. O chamador assume a propriedade do objeto de características alocado, que deve ser desalocado com keymaster_free_characteristics() .
Observe que KM_TAG_APPLICATION_ID e KM_TAG_APPLICATION_DATA nunca são retornados.
- Parâmetros
[em] desenvolvedor A estrutura do dispositivo keymaster. [em] key_blob A chave para recuperar características de. [em] ID do Cliente Os dados do ID do cliente ou NULL se nenhum estiver associado. [em] ID_do_aplicativo Os dados do aplicativo ou NULL se nenhum estiver associado. [fora] características As principais características. Não deve ser nulo. O chamador assume a propriedade do conteúdo e deve desalocar com keymaster_free_characteristics() .
Definição na linha 139 do arquivo keymaster2.h .
| keymaster_error_t (* import_key)(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params, keymaster_key_format_t key_format, const keymaster_blob_t *key_data, keymaster_key_blob_t *key_blob, keymaster_key_characteristics_t *características) |
Importa uma chave ou par de chaves, retornando um blob de chave e/ou uma descrição da chave.
A maioria dos parâmetros de importação de chave são definidos como pares de tag/valor keymaster, fornecidos em "parâmetros". Veja keymaster_tag_t para a lista completa. Os valores sempre necessários para importação de chaves úteis são:
- KM_TAG_ALGORITMO;
- KM_TAG_PURPOSE; e
- (KM_TAG_USER_SECURE_ID e KM_TAG_USER_AUTH_TYPE) ou KM_TAG_NO_AUTH_REQUIRED.
KM_TAG_AUTH_TIMEOUT geralmente deve ser especificado. Se não for especificado, o usuário terá que se autenticar para cada uso.
As tags a seguir assumirão valores padrão se não forem especificadas:
- KM_TAG_KEY_SIZE terá como padrão o tamanho da chave fornecida.
- KM_TAG_RSA_PUBLIC_EXPONENT assumirá como padrão o valor da chave fornecida (para chaves RSA)
As tags a seguir não podem ser especificadas; seus valores serão fornecidos pela implementação.
- KM_TAG_ORIGIN,
- KM_TAG_ROLLBACK_RESISTANT,
- KM_TAG_CREATION_DATETIME
- Parâmetros
[em] desenvolvedor A estrutura do dispositivo keymaster. [em] parâmetros Parâmetros que definem a chave importada. [em] params_count O número de entradas em params.[em] formato_chave especifica o formato dos dados principais em key_data. [fora] key_blob Usado para retornar o blob de chave opaco. Deve ser diferente de NULL. O chamador assume a propriedade do key_material contido. [fora] características Usado para retornar as características da chave importada. Pode ser NULL, caso em que nenhuma característica será retornada. Se não for NULL, o chamador assume a propriedade do conteúdo e deve desalocar com keymaster_free_characteristics() . Observe que KM_TAG_APPLICATION_ID e KM_TAG_APPLICATION_DATA nunca são retornados.
Definição na linha 186 do arquivo keymaster2.h .
| keymaster_error_t (* atualização)(const struct keymaster2_device *dev, keymaster_operation_handle_t operation_handle, const keymaster_key_param_set_t *in_params, const keymaster_blob_t *input, size_t *input_consumed, keymaster_key_param_set_t *out_params, keymaster_blob_t *output) |
Fornece dados e possivelmente recebe resultados de uma operação criptográfica contínua iniciada com begin() .
Se Operation_handle for inválido, update() retornará KM_ERROR_INVALID_OPERATION_HANDLE.
update() pode não consumir todos os dados fornecidos no buffer de dados. update() retornará a quantidade consumida em *data_consumed. O chamador deverá fornecer os dados não consumidos em uma chamada subsequente.
- Parâmetros
[em] desenvolvedor A estrutura do dispositivo keymaster. [em] operação_handle O identificador de operação retornado por Begin() . [em] in_params Parâmetros adicionais para a operação. Para modos AEAD, isso é usado para especificar KM_TAG_ADDITIONAL_DATA. Observe que dados adicionais podem ser fornecidos em múltiplas chamadas para update() , mas somente até que os dados de entrada sejam fornecidos. [em] entrada Dados a serem processados, conforme parâmetros estabelecidos na chamada de begin() . Observe que update() pode ou não consumir todos os dados fornecidos. Consulte input_consumed.[fora] entrada_consumida Quantidade de dados consumidos por update() . Se for menor que o valor fornecido, o chamador deverá fornecer o restante em uma chamada subsequente para update() . [fora] out_params Parâmetros de saída. Usado para retornar dados adicionais da operação. O chamador assume a propriedade da matriz de parâmetros de saída e deve liberá-la com keymaster_free_param_set() . out_params pode ser definido como NULL se nenhum parâmetro de saída for esperado. Se out_params for NULL e parâmetros de saída forem gerados, Begin() retornará KM_ERROR_OUTPUT_PARAMETER_NULL. [fora] saída Os dados de saída, se houver. O chamador assume a propriedade do buffer alocado. a saída não deve ser NULL.
Observe que update() pode não fornecer nenhuma saída; nesse caso, output->data_length será zero e output->data pode ser NULL ou comprimento zero (portanto, o chamador deve sempre free()).
Definição na linha 376 do arquivo keymaster2.h .
| keymaster_error_t (* upgrade_key)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key_to_upgrade, const keymaster_key_param_set_t *upgrade_params, keymaster_key_blob_t *upgraded_key) |
Atualiza uma chave antiga. As chaves podem se tornar "antigas" de duas maneiras: o Keymaster pode ser atualizado para uma nova versão ou o sistema pode ser atualizado para invalidar a versão do sistema operacional e/ou o nível do patch. Em ambos os casos, as tentativas de usar uma chave antiga resultarão no retorno do keymaster KM_ERROR_KEY_REQUIRES_UPGRADE. Este método deve então ser chamado para atualizar a chave.
- Parâmetros
[em] desenvolvedor A estrutura do dispositivo keymaster. [em] chave_para_atualização A chave mestra a ser atualizada. [em] atualização_params Parâmetros necessários para concluir a atualização. Em particular, KM_TAG_APPLICATION_ID e KM_TAG_APPLICATION_DATA serão necessários se tiverem sido definidos para a chave. [fora] chave_atualizada O blob de chave atualizado.
Definição na linha 260 do arquivo keymaster2.h .
A documentação desta estrutura foi gerada a partir do seguinte arquivo:
- hardware/libhardware/include/hardware/ keymaster2.h