Compartilhar via


Função BCryptOpenAlgorithmProvider (bcrypt.h)

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étricaalgoritmos 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