BCryptOpenAlgorithmProvider

The BCryptOpenAlgorithmProvider function loads and initializes a CNG provider.

Syntax

NTSTATUS BCryptOpenAlgorithmProvider(
         BCRYPT_ALG_HANDLE *phAlgorithm,
         LPCWSTR pszAlgId,
         LPCWSTR pszImplementation,
         ULONG dwFlags
)

Parameters

phAlgorithm
Type: BCRYPT_ALG_HANDLE *

[out] A pointer to a BCRYPT_ALG_HANDLE variable that receives the CNG provider handle. When you have finished using this handle, release it by passing it to the BCryptCloseAlgorithmProvider function.

pszAlgId
Type: LPCWSTR

[in] A pointer to a null-terminated Unicode string that identifies the requested cryptographic algorithm. This can be one of the standard CNG Algorithm Identifiers or the identifier for another registered algorithm.

pszImplementation
Type: LPCWSTR

[in, optional]

A pointer to a null-terminated Unicode string that identifies the specific provider to load. This is the registered alias of the cryptographic primitive provider. This parameter is optional and can be NULL if it is not needed. If this parameter is NULL, the default provider for the specified algorithm will be loaded.

Note

If the pszImplementation parameter value is NULL, CNG attempts to open each registered provider, in order of priority, for the algorithm specified by the pszAlgId parameter and returns the handle of the first provider that is successfully opened. For the lifetime of the handle, any BCrypt*** cryptographic APIs will use the provider that was successfully opened.

Note

CNG attempts to fall back to the Microsoft CNG provider.

dwFlags
Type: ULONG

[in] Flags that modify the behavior of the function. This can be zero or a combination of one or more of the following values.

Return value

Type: NTSTATUS

Returns a status code that indicates the success or failure of the function.

Return codes

Possible return codes include, but are not limited to, the following.

Return code	Description
STATUS_SUCCESS	The function was successful.
STATUS_NOT_FOUND	No provider was found for the specified algorithm ID.
STATUS_INVALID_PARAMETER	One or more parameters are not valid.
STATUS_NO_MEMORY	A memory allocation failure occurred.

Remarks

Because of the number and type of operations that are required to find, load, and initialize an algorithm provider, the BCryptOpenAlgorithmProvider function is a relatively time intensive function. Because of this, we recommend that you cache any algorithm provider handles that you will use more than once, rather than opening and closing the algorithm providers over and over.

BCryptOpenAlgorithmProvider can be called either from user mode or kernel mode. Kernel mode callers must be executing at PASSIVE_LEVELIRQL.

Requirements

Header: Declared in bcrypt.h.

Library: Use bcrypt.lib.