BCryptOpenAlgorithmProvider function (bcrypt.h)
The BCryptOpenAlgorithmProvider function loads and initializes a CNG provider.
NTSTATUS BCryptOpenAlgorithmProvider( [out] BCRYPT_ALG_HANDLE *phAlgorithm, [in] LPCWSTR pszAlgId, [in] LPCWSTR pszImplementation, [in] ULONG dwFlags );
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.
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.
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.
The following are the predefined provider names.
||Identifies the basic Microsoft CNG provider.|
||Identifies the TPM key storage provider that is provided by Microsoft.|
Flags that modify the behavior of the function. This can be zero or a combination of one or more of the following values.
||The provider will perform the Hash-Based Message Authentication Code (HMAC) algorithm with the specified hash algorithm. This flag is only used by hash algorithm providers.|
Loads the provider into the nonpaged memory pool. If this flag is not present, the provider is loaded into the paged memory pool. When this flag is specified, the handle returned must not be closed before all dependent objects have been freed.
Note This flag is only supported in kernel mode and allows subsequent operations on the provider to be processed at the Dispatch level. If the provider does not support being called at dispatch level, then it will return an error when opened using this flag.
Creates a reusable hashing object. The object can be used for a new hashing operation immediately after calling BCryptFinishHash. For more information, see Creating a Hash with CNG.
Windows Server 2008 R2, Windows 7, Windows Server 2008 and Windows Vista: This flag is not supported.
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.
||The function was successful.|
||No provider was found for the specified algorithm ID.|
||One or more parameters are not valid.|
||A memory allocation failure occurred.|
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_LEVEL IRQL.
To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). Windows Server 2008 and Windows Vista: To call this function in kernel mode, use Ksecdd.lib.
Starting in Windows 10, CNG no longer follows every update to the cryptography configuration. Certain changes, like adding a new default provider or changing the preference order of algorithm providers, may require a reboot. Because of this, you should reboot before calling BCryptOpenAlgorithmProvider with any newly configured provider.
|Minimum supported client||Windows Vista [desktop apps | UWP apps]|
|Minimum supported server||Windows Server 2008 [desktop apps | UWP apps]|