Função BCryptOpenAlgorithmProvider (bcrypt.h)

Artigo
07/16/2024

A função BCryptOpenAlgorithmProvider carrega e inicializa um provedor de CNG.

Sintaxe

NTSTATUS BCryptOpenAlgorithmProvider(
  [out] BCRYPT_ALG_HANDLE *phAlgorithm,
  [in]  LPCWSTR           pszAlgId,
  [in]  LPCWSTR           pszImplementation,
  [in]  ULONG             dwFlags
);

Parâmetros

[out] phAlgorithm

Um ponteiro para uma variável BCRYPT_ALG_HANDLE que recebe o identificador do provedor CNG. Quando terminar de usar esse identificador, libere-o passando-o para a função BCryptCloseAlgorithmProvider .

[in] pszAlgId

Um ponteiro para uma cadeia de caracteres Unicode terminada em nulo que identifica o algoritmo de criptografia solicitado. Esse pode ser um dos identificadores de algoritmo CNG padrão ou o identificador de outro algoritmo registrado.

[in] pszImplementation

Um ponteiro para uma cadeia de caracteres Unicode terminada em nulo que identifica o provedor específico a ser carregado. Esse é o alias registrado do provedor primitivo criptográfico. Esse parâmetro é opcional e pode ser NULL se não for necessário. Se esse parâmetro for NULL, o provedor padrão do algoritmo especificado será carregado.

Observação Se o valor do parâmetro pszImplementation for NULL, o CNG tentará abrir cada provedor registrado, por ordem de prioridade, para o algoritmo especificado pelo parâmetro pszAlgId e retornará o identificador do primeiro provedor aberto com êxito. Durante o tempo de vida do identificador, todas as APIs criptográficas BCrypt*** usarão o provedor que foi aberto com êxito.

Windows Server 2008 e Windows Vista: CNG tenta fazer fallback para o provedor de CNG da Microsoft.

Veja a seguir os nomes de provedor predefinidos.

Valor	Significado
MS_PRIMITIVE_PROVIDER "Provedor Primitivo da Microsoft"	Identifica o provedor de CNG básico da Microsoft.
MS_PLATFORM_CRYPTO_PROVIDER L"Provedor de Criptografia da Plataforma Microsoft"	Identifica o provedor de armazenamento de chaves do TPM fornecido pela Microsoft.

[in] dwFlags

Sinalizadores que modificam o comportamento da função. Isso pode ser zero ou uma combinação de um ou mais dos valores a seguir.

Valor	Significado
BCRYPT_ALG_HANDLE_HMAC_FLAG	O provedor executará o algoritmo Hash-Based HMAC ( de Código de Autenticação de Mensagem) com o algoritmo de hash especificado. Esse sinalizador é usado apenas por provedores de algoritmo de hash.
BCRYPT_PROV_DISPATCH	Carrega o provedor no pool de memória nãopagado. Se esse sinalizador não estiver presente, o provedor será carregado no pool de memória paginado. Quando esse sinalizador é especificado, o identificador retornado não deve ser fechado antes que todos os objetos dependentes tenham sido liberados. Observação Esse sinalizador só tem suporte no modo kernel e permite que as operações subsequentes no provedor sejam processadas no nível de Expedição. Se o provedor não der suporte a ser chamado no nível de expedição, ele retornará um erro quando for aberto usando esse sinalizador. Windows Server 2008 e Windows Vista: Esse sinalizador só tem suporte dos provedores de algoritmos da Microsoft e somente para algoritmos de hash e chave simétrica algoritmos criptográficos.
BCRYPT_HASH_REUSABLE_FLAG	Cria um objeto de hash reutilizável. O objeto pode ser usado para uma nova operação de hash imediatamente após chamar BCryptFinishHash. Para obter mais informações, consulte Criando um hash comCNG. Windows Server 2008 R2, Windows 7, Windows Server 2008 e Windows Vista: Esse sinalizador não tem suporte.

Valor de retorno

Retorna um código de status que indica o êxito ou a falha da função.

Os códigos de retorno possíveis incluem, mas não se limitam a, o seguinte.

Código de retorno	Descrição
STATUS_SUCCESS	A função foi bem-sucedida.
STATUS_NOT_FOUND	Nenhum provedor foi encontrado para a ID de algoritmo especificada.
STATUS_INVALID_PARAMETER	Um ou mais parâmetros não são válidos.
STATUS_NO_MEMORY	Ocorreu uma falha de alocação de memória.

Observações

Devido ao número e tipo de operações que são necessárias para localizar, carregar e inicializar um provedor de algoritmos, a função BCryptOpenAlgorithmProvider é uma função relativamente intensiva. Por isso, recomendamos que você armazene em cache todos os identificadores do provedor de algoritmos que você usará mais de uma vez, em vez de abrir e fechar os provedores de algoritmos uma e outra vez.

BCryptOpenAlgorithmProvider pode ser chamado do modo de usuário ou do modo kernel. Os chamadores do modo kernel devem estar em execução em PASSIVE_LEVELIRQL.

Para chamar essa função no modo kernel, use Cng.lib, que faz parte do DDK (Driver Development Kit). Windows Server 2008 e Windows Vista: Para chamar essa função no modo kernel, use Ksecdd.lib.

A partir do Windows 10, o CNG não segue mais todas as atualizações da configuração de criptografia. Determinadas alterações, como adicionar um novo provedor padrão ou alterar a ordem de preferência dos provedores de algoritmo, podem exigir uma reinicialização. Por isso, você deve reinicializar antes de chamar BCryptOpenAlgorithmProvider com qualquer provedor recém-configurado.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows Vista [aplicativos da área de trabalho \| Aplicativos UWP]
servidor com suporte mínimo	Windows Server 2008 [aplicativos da área de trabalho \| Aplicativos UWP]
da Plataforma de Destino	Windows
cabeçalho	bcrypt.h
biblioteca	Bcrypt.lib
de DLL	Bcrypt.dll

Consulte também

BCryptCloseAlgorithmProvider

Compartilhar via