Referência de estrutura keymaster2_device

Aborta 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 .

Adiciona entropia ao RNG usado pelo keymaster. A entropia adicionada através deste método é garantida para não ser 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 qualquer dado 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, a saída será boa.

Parâmetros

[dentro]	desenvolvedor	A estrutura do dispositivo keymaster.
[dentro]	dados	Dados aleatórios a serem misturados.
[dentro]	data_length	Comprimento dos data .

Definição na linha 74 do arquivo keymaster2.h .

Gera uma cadeia de certificados X.509 assinada atestando a presença de key_to_attest no keymaster (TODO(swillden): Descrever 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 – inserir link aqui> que contém a descrição da chave.

Parâmetros

[dentro]	desenvolvedor	A estrutura do dispositivo keymaster.
[dentro]	key_to_attest	A chave mestra para a qual o certificado de atestado será gerado.
[dentro]	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 quais das chaves de atestado provisionadas serão usadas para assinar o certificado.
[Fora]	cert_chain	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 com keymaster_free_cert_chain.

Definição na linha 239 do arquivo keymaster2.h .

Inicia uma operação criptográfica usando a chave especificada. Se tudo estiver bem, begin() retornará KM_ERROR_OK e criará um handle 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. A falha em 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, neste caso abort() não precisa ser chamado (e retornará KM_ERROR_INVALID_OPERATION_HANDLE se chamado).

Parâmetros

[dentro]	desenvolvedor	A estrutura do dispositivo keymaster.
[dentro]	propósito	O objetivo da operação, um de KM_PURPOSE_ENCRYPT, KM_PURPOSE_DECRYPT, KM_PURPOSE_SIGN ou KM_PURPOSE_VERIFY. Observe que para os modos AEAD, criptografia e descriptografia implicam assinatura e verificação, respectivamente, mas devem ser especificadas como KM_PURPOSE_ENCRYPT e KM_PURPOSE_DECRYPT.
[dentro]	chave	A chave a ser usada para a operação. key deve ter um propósito compatível com o purpose e todos os seus requisitos de uso devem ser atendidos, ou begin() retornará um código de erro apropriado.
[dentro]	in_params	Parâmetros adicionais para a operação. Isso 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 devem ser fornecidos aqui ou a operação falhará com KM_ERROR_INVALID_KEY_BLOB. Para operações que exigem 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, notadamente para retornar o IV ou nonce de operações que geram um IV ou nonce. O chamador assume a propriedade do array de parâmetros de saída e deve liberá-lo 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 os parâmetros de saída forem gerados, begin() retornará KM_ERROR_OUTPUT_PARAMETER_NULL.
[Fora]	operação_handle	O manipulador 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 .

Métodos comuns do dispositivo keymaster. Este deve ser o primeiro membro de keymaster_device, pois os usuários dessa estrutura converterão um ponteiro hw_device_t para keymaster_device em contextos em que é conhecido que hw_device_t faz referência a um keymaster_device.

Definição na linha 35 do arquivo keymaster2.h .

Configura 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ó são aceitos pelo keymaster 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 SO e os valores de nível de patch fornecidos não corresponderem aos valores fornecidos ao hardware seguro pelo carregador de inicialização (ou se o carregador de inicialização não fornecer valores), esse 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 .

Definição na linha 37 do arquivo keymaster2.h .

Exclui todas as chaves no keystore de hardware. Usado quando o keystore é redefinido completamente. Depois de chamar esta função, será impossível usar quaisquer blobs de chave 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

[dentro]

desenvolvedor

A estrutura do dispositivo keymaster.

Definição na linha 288 do arquivo keymaster2.h .

Exclui a chave ou o par de chaves associado ao blob de chaves. Após chamar esta função será impossível utilizar a tecla para quaisquer outras operações. Pode ser aplicado a chaves de raízes estrangeiras de confiança (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

[dentro]	desenvolvedor	A estrutura do dispositivo keymaster.
[dentro]	chave	A chave a ser excluída.

Definição na linha 276 do arquivo keymaster2.h .

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 é permitida apenas se a chave foi criada com KM_TAG_EXPORTABLE e somente se todos os requisitos para uso de chave (por exemplo, autenticação) forem atendidos.

Parâmetros

[dentro]	desenvolvedor	A estrutura do dispositivo keymaster.
[dentro]	export_format	O formato a ser usado para exportar a chave.
[dentro]	key_to_export	A chave para exportar.
[dentro]	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).
[dentro]	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 de chave exportado. O chamador assume a propriedade.

Definição na linha 213 do arquivo keymaster2.h .

Finaliza uma operação criptográfica iniciada com begin() e invalida operation_handle .

Parâmetros

[dentro]	desenvolvedor	A estrutura do dispositivo keymaster.
[dentro]	operação_handle	O identificador de operação retornado por begin() . Este identificador será invalidado.
[dentro]	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 foi fornecido para update() .
[dentro]	entrada	Dados a serem processados, conforme os parâmetros estabelecidos na chamada para begin() . finish() deve consumir todos os dados fornecidos ou retornar KM_ERROR_INVALID_INPUT_LENGTH.
[dentro]	assinatura	A assinatura a ser verificada se o propósito especificado na chamada begin() foi KM_PURPOSE_VERIFY.
[Fora]	resultado	Os dados de saída, se houver. O chamador assume a propriedade do buffer alocado.

Se a operação que está sendo finalizada for uma verificação de assinatura ou uma descriptografia no modo AEAD e a verificação falhar, finish() retornará KM_ERROR_VERIFICATION_FAILED.

Definição na linha 405 do arquivo keymaster2.h .

Veja 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 .

Gera uma chave, ou par de chaves, retornando um blob de chaves e/ou uma descrição da chave.

Os parâmetros de geração de chave são definidos como pares de tag/valor do keymaster, fornecidos em params . Veja keymaster_tag_t para a lista completa. Alguns valores sempre necessários para geração de chaves úteis são:

• KM_TAG_ALGORITHM;
• 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 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 seguintes tags 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

[dentro]	desenvolvedor	A estrutura do dispositivo keymaster.
[dentro]	parâmetros	Array do parâmetro de geração de chaves
[Fora]	key_blob	retorna a chave gerada. key_blob não deve ser NULL. O chamador assume a propriedade key_blob->key_material e deve liberá-lo.
[Fora]	características	retorna as características da chave que foi gerada, caso não seja NULL. Se não 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 .

Retorna as características da chave especificada ou KM_ERROR_INVALID_KEY_BLOB se o 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 vazio 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

[dentro]	desenvolvedor	A estrutura do dispositivo keymaster.
[dentro]	key_blob	A chave para recuperar características de.
[dentro]	ID do Cliente	Os dados de ID do cliente ou NULL se nenhum associado.
[dentro]	app_id	Os dados do aplicativo ou NULL se nenhum 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 .

Importa uma chave, ou par de chaves, retornando um blob de chaves 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 do keymaster, fornecidos em "params". Veja keymaster_tag_t para a lista completa. Os valores sempre necessários para importação de chaves úteis são:

• KM_TAG_ALGORITHM;
• 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 seguintes tags terão valores padrão se não forem especificadas:

• KM_TAG_KEY_SIZE será o padrão para o tamanho da chave fornecida.
• KM_TAG_RSA_PUBLIC_EXPONENT assumirá como padrão o valor na chave fornecida (para chaves RSA)

As seguintes tags 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

[dentro]	desenvolvedor	A estrutura do dispositivo keymaster.
[dentro]	parâmetros	Parâmetros que definem a chave importada.
[dentro]	params_count	O número de entradas em params .
[dentro]	key_format	especifica o formato dos dados de chave em key_data.
[Fora]	key_blob	Usado para retornar o blob de chaves opaco. Deve ser não 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, neste caso 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 .

Fornece dados e possivelmente recebe saída 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 deve fornecer os dados não consumidos em uma chamada subsequente.

Parâmetros

[dentro]	desenvolvedor	A estrutura do dispositivo keymaster.
[dentro]	operação_handle	O identificador de operação retornado por begin() .
[dentro]	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 várias chamadas para update() , mas somente até que os dados de entrada sejam fornecidos.
[dentro]	entrada	Dados a serem processados, conforme os parâmetros estabelecidos na chamada para begin() . Observe que update() pode ou não consumir todos os dados fornecidos. Consulte input_consumed .
[Fora]	input_consumed	Quantidade de dados que foram consumidos por update() . Se for menor que o valor fornecido, o chamador deve 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 toma posse do array de parâmetros de saída e deve liberá-lo 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 os parâmetros de saída forem gerados, begin() retornará KM_ERROR_OUTPUT_PARAMETER_NULL.
[Fora]	resultado	Os dados de saída, se houver. O chamador assume a propriedade do buffer alocado. 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 zero-length (portanto, o chamador deve sempre liberá-lo).

Definição na linha 376 do arquivo keymaster2.h .

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 de patch. Em ambos os casos, as tentativas de usar uma chave antiga resultarão no keymaster retornando KM_ERROR_KEY_REQUIRES_UPGRADE. Este método deve então ser chamado para atualizar a chave.

Parâmetros

[dentro]	desenvolvedor	A estrutura do dispositivo keymaster.
[dentro]	key_to_upgrade	A chave mestra para atualizar.
[dentro]	upgrade_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 chaves atualizado.

Definição na linha 260 do arquivo keymaster2.h .