Share via

Função BCryptOpenAlgorithmProvider (bcrypt.h)

  • Artigo

A função BCryptOpenAlgorithmProvider carrega e inicializa um provedor 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 criptográfico 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 para o algoritmo especificado será carregado.

Nota Se o valor do parâmetro pszImplementation for NULL, o CNG tentará abrir cada provedor registrado, em 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: O CNG tenta fazer fallback para o provedor CNG da Microsoft.

Veja a seguir os nomes de provedor predefinidos.

Valor Significado
MS_PRIMITIVE_PROVIDER
"Provedor Primitivo da Microsoft"
 Identifica o provedor básico do Microsoft CNG.
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 HMAC ( Código de Autenticação de Mensagem Baseado em Hash ) 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.
Nota 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 aberto usando esse sinalizador.
 
Windows Server 2008 e Windows Vista: Esse sinalizador só tem suporte dos provedores de algoritmos da Microsoft e apenas para algoritmos de hash e algoritmos criptográficos de chave simétrica.
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 com CNG.

Windows Server 2008 R2, Windows 7, Windows Server 2008 e Windows Vista: Não há suporte para esse sinalizador.

Retornar valor

Retorna um código 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 dos parâmetros não são válidos.
STATUS_NO_MEMORY
 Ocorreu uma falha de alocação de memória.

Comentários

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 qualquer identificador de 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 no modo de usuário ou no modo kernel. Os chamadores do modo kernel devem estar em execução no 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.

Começando no 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
Cliente mínimo com suporte Windows Vista [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte Windows Server 2008 [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino Windows
Cabeçalho bcrypt.h
Biblioteca Bcrypt.lib
DLL Bcrypt.dll

Confira também

BCryptCloseAlgorithmProvider