Referência da 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 por esse método não é a única fonte de entropia usada, e a função de mistura precisa ser segura, ou seja, se o RNG for inicializado (de qualquer fonte) com dados que o invasor não pode prever (ou controlar), a saída do RNG não poderá ser distinguida de uma saída aleatória. Assim, se a entropia de qualquer fonte for boa, a saída será boa.

Parâmetros

[in]	dev	A estrutura do dispositivo do keymaster.
[in]	dados	Dados aleatórios a serem misturados.
[in]	data_length	Comprimento de data .

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

Gera uma cadeia de certificados X.509 assinada que atesta a presença de key_to_attest no keymaster (TODO(swillden): Descreva o conteúdo do certificado com mais detalhes). O certificado vai conter uma extensão com OID 1.3.6.1.4.1.11129.2.1.17 e o valor definido em <TODO:swillden – insert link here>, que contém a descrição da chave.

Parâmetros

[in]	dev	A estrutura do dispositivo do keymaster.
[in]	key_to_attest	A chave do keymaster para a qual o certificado de atestado será gerado.
[in]	attest_params	Parâmetros que definem como fazer o atestado. No momento, o único parâmetro é KM_TAG_ALGORITHM, que precisa ser KM_ALGORITHM_EC ou KM_ALGORITHM_RSA. Isso seleciona quais das chaves de atestado provisionadas serão usadas para assinar o certificado.
[out]	cert_chain	Uma matriz de certificados X.509 codificados em DER. O primeiro será o certificado para key_to_attest . As entradas restantes serão encadeadas de volta à raiz. O autor da chamada assume a propriedade e precisa 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() vai retornar KM_ERROR_OK e criar um identificador de operação que precisa ser transmitido para chamadas subsequentes para update() , finish() ou abort() .

É fundamental que cada chamada para begin() seja associada a uma chamada subsequente para finish() ou abort() , para permitir que a implementação do keymaster limpe qualquer estado de operação interno. Se isso não for feito, pode ocorrer um vazamento de espaço de estado interno ou outros recursos internos, e isso pode fazer com que begin() retorne KM_ERROR_TOO_MANY_OPERATIONS quando o espaço para operações acabar. Qualquer resultado diferente de KM_ERROR_OK de begin() , update() ou finish() aborta implicitamente a operação. Nesse caso, abort() não precisa ser chamado (e vai retornar KM_ERROR_INVALID_OPERATION_HANDLE se for chamado).

Parâmetros

[in]	dev	A estrutura do dispositivo do keymaster.
[in]	propósito	A finalidade da operação, uma de KM_PURPOSE_ENCRYPT, KM_PURPOSE_DECRYPT, KM_PURPOSE_SIGN ou KM_PURPOSE_VERIFY. Para os modos AEAD, a criptografia e a descriptografia implicam assinatura e verificação, respectivamente, mas precisam ser especificadas como KM_PURPOSE_ENCRYPT e KM_PURPOSE_DECRYPT.
[in]	chave	A chave a ser usada para a operação. key precisa ter uma finalidade compatível com purpose e todos os requisitos de uso precisam ser atendidos. Caso contrário, begin() vai retornar um código de erro adequado.
[in]	in_params	Parâmetros adicionais para a operação. Isso geralmente é 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 precisam ser fornecidos aqui. Caso contrário, a operação falhará com KM_ERROR_INVALID_KEY_BLOB. Para operações que exigem um valor de uso único ou IV, em chaves geradas com KM_TAG_CALLER_NONCE, in_params pode conter uma tag KM_TAG_NONCE.
[out]	out_params	Parâmetros de saída. Usado para retornar dados adicionais da inicialização da operação, principalmente para retornar o IV ou o valor de uso único de operações que geram um IV ou valor de uso único. O autor da chamada assume a propriedade da matriz de parâmetros de saída e precisa 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 os parâmetros de saída forem gerados, begin() vai retornar KM_ERROR_OUTPUT_PARAMETER_NULL.
[out]	operation_handle	O identificador de operação recém-criado que precisa ser transmitido para update() , finish() ou abort() . Se operation_handle for NULL, begin() vai retornar KM_ERROR_OUTPUT_PARAMETER_NULL.

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

Métodos comuns do dispositivo keymaster. Ele precisa ser o primeiro membro de keymaster_device, já que os usuários dessa estrutura vão transmitir um hw_device_t para o ponteiro keymaster_device em contextos em que se sabe que o hw_device_t faz referência a um keymaster_device.

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

Configura o keymaster. Esse método precisa ser chamado uma vez após a abertura do dispositivo e antes de ele ser usado. Ele é usado para fornecer KM_TAG_OS_VERSION e KM_TAG_OS_PATCHLEVEL ao keymaster. Até que esse método seja chamado, todos os outros métodos vão retornar KM_ERROR_KEYMASTER_NOT_CONFIGURED. Os valores fornecidos por esse método só são aceitos pelo keymaster uma vez por inicialização. As chamadas subsequentes vão retornar KM_ERROR_OK, mas não vão fazer nada.

Se a implementação do keymaster estiver em hardware seguro e a versão do SO e os valores do nível do 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 vai retornar KM_ERROR_INVALID_ARGUMENT, e todos os outros métodos vão continuar 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 essa função, será impossível usar blobs de chaves gerados ou importados anteriormente em qualquer operação.

Essa função é opcional e precisa ser definida como NULL se não for implementada.

Parâmetros

[in]

dev

A estrutura do dispositivo do keymaster.

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

Exclui a chave ou o par de chaves associado ao blob de chave. Depois de chamar essa função, será impossível usar a chave para 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).

Essa função é opcional e precisa ser definida como NULL se não for implementada.

Parâmetros

[in]	dev	A estrutura do dispositivo do keymaster.
[in]	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.

A exportação de chaves simétricas só é permitida se a chave foi criada com KM_TAG_EXPORTABLE e se todos os requisitos para uso de chaves (por exemplo, autenticação) forem atendidos.

Parâmetros

[in]	dev	A estrutura do dispositivo do keymaster.
[in]	export_format	O formato a ser usado para exportar a chave.
[in]	key_to_export	A chave a ser exportada.
[in]	client_id	Blob do ID do cliente, que precisa corresponder ao blob fornecido em KM_TAG_APPLICATION_ID durante a geração de chaves (se houver).
[in]	app_data	Blob de dados do aplicativo, que precisa corresponder ao blob fornecido em KM_TAG_APPLICATION_DATA durante a geração de chaves (se houver).
[out]	export_data	O material da chave exportado. O autor da chamada 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

[in]	dev	A estrutura do dispositivo do keymaster.
[in]	operation_handle	O identificador de operação retornado por begin() . Esse identificador será invalidado.
[in]	in_params	Parâmetros adicionais para a operação. Para modos AEAD, isso é usado para especificar KM_TAG_ADDITIONAL_DATA, mas apenas se nenhum dado de entrada tiver sido fornecido para update() .
[in]	input	Dados a serem processados, de acordo com os parâmetros estabelecidos na chamada para begin() . finish() precisa consumir todos os dados fornecidos ou retornar KM_ERROR_INVALID_INPUT_LENGTH.
[in]	assinatura	A assinatura a ser verificada se a finalidade especificada na chamada begin() foi KM_PURPOSE_VERIFY.
[out]	output	Os dados de saída, se houver. O autor da chamada assume a propriedade do buffer alocado.

Se a operação concluída for uma verificação de assinatura ou uma descriptografia no modo AEAD e a verificação falhar, finish() vai retornar KM_ERROR_VERIFICATION_FAILED.

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

Consulte as flags definidas para keymaster0_devices::flags em keymaster_common.h . Usado apenas para compatibilidade com versões anteriores. Os dispositivos de hardware keymaster2 precisam definir esse valor como zero.

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

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

Os parâmetros de geração de chaves são definidos como pares de chave/valor do keymaster, fornecidos em params . Consulte keymaster_tag_t para conferir a lista completa. Alguns valores que sempre são necessários para a 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.

O valor KM_TAG_AUTH_TIMEOUT geralmente precisa ser especificado, a menos que KM_TAG_NO_AUTH_REQUIRED esteja presente. Caso contrário, o usuário terá que fazer a autenticação para cada uso.

KM_TAG_BLOCK_MODE, KM_TAG_PADDING, KM_TAG_MAC_LENGTH e KM_TAG_DIGEST precisam ser especificados para algoritmos que os exigem.

As tags a seguir não podem ser especificadas. Os valores delas serão fornecidos pela implementação.

• KM_TAG_ORIGIN,
• KM_TAG_ROLLBACK_RESISTANT,
• KM_TAG_CREATION_DATETIME

Parâmetros

[in]	dev	A estrutura do dispositivo do keymaster.
[in]	params	Matriz do parâmetro de geração de chaves
[out]	key_blob	retorna a chave gerada. key_blob não pode ser nulo. O autor da chamada assume a propriedade key_blob->key_material e precisa fazer free() nela.
[out]	características	retorna as características da chave gerada, se não for NULL. Se não for NULL, o autor da chamada assume a propriedade e precisa ser desalocado com keymaster_free_characteristics() . 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 precisam validar totalmente a integridade da chave. client_id e app_data precisam 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 tiverem sido fornecidos durante a geração. Esses valores não são incluídos nas características retornadas. O autor da chamada assume a propriedade do objeto de características alocado, que precisa ser desalocado com keymaster_free_characteristics() .

KM_TAG_APPLICATION_ID e KM_TAG_APPLICATION_DATA nunca são retornados.

Parâmetros

[in]	dev	A estrutura do dispositivo do keymaster.
[in]	key_blob	A chave para extrair características.
[in]	client_id	Os dados do ID do cliente ou NULL se nenhum estiver associado.
[in]	app_id	Os dados do app ou NULL se nenhum estiver associado.
[out]	características	As principais características. Não pode ser nulo. O autor da chamada assume a propriedade do conteúdo e precisa desalocar com keymaster_free_characteristics() .

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

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

A maioria dos parâmetros de importação principais são definidos como pares de chave/valor do keymaster, fornecidos em "params". Consulte keymaster_tag_t para conferir a lista completa. Os valores sempre necessários para a 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.

Geralmente, é necessário especificar KM_TAG_AUTH_TIMEOUT. Se não for especificado, o usuário vai precisar fazer a autenticação para cada uso.

As tags a seguir vão receber valores padrão se não forem especificadas:

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

As tags a seguir não podem ser especificadas. Os valores delas serão fornecidos pela implementação.

• KM_TAG_ORIGIN,
• KM_TAG_ROLLBACK_RESISTANT,
• KM_TAG_CREATION_DATETIME

Parâmetros

[in]	dev	A estrutura do dispositivo do keymaster.
[in]	params	Parâmetros que definem a chave importada.
[in]	params_count	O número de entradas em params .
[in]	key_format	Especifica o formato dos dados da chave em key_data.
[out]	key_blob	Usado para retornar o blob de chave opaco. Precisa ser diferente de NULL. O autor da chamada assume a propriedade do key_material contido.
[out]	características	Usado para retornar as características da chave importada. Pode ser NULL. Nesse caso, nenhuma característica será retornada. Se não for NULL, o autor da chamada assume a propriedade do conteúdo e precisa ser desalocado com keymaster_free_characteristics() . KM_TAG_APPLICATION_ID e KM_TAG_APPLICATION_DATA nunca são retornados.

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

Fornece dados para uma operação criptográfica em andamento iniciada com begin() e possivelmente recebe a saída dela.

Se operation_handle for inválido, update() vai retornar KM_ERROR_INVALID_OPERATION_HANDLE.

update() pode não consumir todos os dados fornecidos no buffer de dados. update() vai retornar a quantidade consumida em *data_consumed. O autor da chamada precisa fornecer os dados não consumidos em uma chamada subsequente.

Parâmetros

[in]	dev	A estrutura do dispositivo do keymaster.
[in]	operation_handle	O identificador de operação retornado por begin() .
[in]	in_params	Parâmetros adicionais para a operação. Para modos AEAD, isso é usado para especificar KM_TAG_ADDITIONAL_DATA. Dados adicionais podem ser fornecidos em várias chamadas para update() , mas somente até que os dados de entrada sejam fornecidos.
[in]	input	Dados a serem processados, de acordo com os parâmetros estabelecidos na chamada para begin() . Observe que update() pode ou não consumir todos os dados fornecidos. Consulte input_consumed .
[out]	input_consumed	Quantidade de dados consumidos por update() . Se o valor for menor que o valor fornecido, o autor da chamada precisará fornecer o restante em uma chamada subsequente para update() .
[out]	out_params	Parâmetros de saída. Usado para retornar dados adicionais da operação. O autor da chamada assume a propriedade da matriz de parâmetros de saída e precisa 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 os parâmetros de saída forem gerados, begin() vai retornar KM_ERROR_OUTPUT_PARAMETER_NULL.
[out]	output	Os dados de saída, se houver. O autor da chamada assume a propriedade do buffer alocado. A saída não pode ser NULO.

update() pode não fornecer nenhuma saída. Nesse caso, output->data_length será zero, e output->data pode ser NULL ou ter comprimento zero. Portanto, o autor da chamada sempre precisa fazer free().

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

Faz upgrade de uma chave antiga. As chaves podem ficar "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 SO e/ou o nível do patch. Em qualquer caso, as tentativas de usar uma chave antiga farão com que o keymaster retorne KM_ERROR_KEY_REQUIRES_UPGRADE. Esse método precisa ser chamado para atualizar a chave.

Parâmetros

[in]	dev	A estrutura do dispositivo do keymaster.
[in]	key_to_upgrade	A chave do keymaster a ser atualizada.
[in]	upgrade_params	Parâmetros necessários para concluir o upgrade. Em particular, KM_TAG_APPLICATION_ID e KM_TAG_APPLICATION_DATA serão necessários se tiverem sido definidos para a chave.
[out]	upgraded_key	O blob de chave atualizado.

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