Export (0) Print
Expand All

BCryptOpenAlgorithmProvider function

The BCryptOpenAlgorithmProvider function loads and initializes a CNG provider.

Syntax


NTSTATUS WINAPI BCryptOpenAlgorithmProvider(
  _Out_  BCRYPT_ALG_HANDLE *phAlgorithm,
  _In_   LPCWSTR pszAlgId,
  _In_   LPCWSTR pszImplementation,
  _In_   DWORD dwFlags
);

Parameters

phAlgorithm [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 [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 [in]

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.

Windows Server 2008 and Windows Vista:  CNG attempts to fall back to the Microsoft CNG provider.

The following are the predefined provider names.

ValueMeaning
MS_PRIMITIVE_PROVIDER
"Microsoft Primitive Provider"

Identifies the basic Microsoft CNG provider.

 

dwFlags [in]

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

ValueMeaning
BCRYPT_ALG_HANDLE_HMAC_FLAG

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.

BCRYPT_PROV_DISPATCH

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.

Windows Server 2008 and Windows Vista:  This flag is only supported by the Microsoft algorithm providers and only for hashing algorithms and symmetric key cryptographic algorithms.

BCRYPT_HASH_REUSABLE_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.

 

Return value

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

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

Return codeDescription
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_LEVEL IRQL.

To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). For more information, see WDK and Developer Tools.

Windows Server 2008 and Windows Vista:  To call this function in kernel mode, use Ksecdd.lib.

Requirements

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

Bcrypt.h

Library

Bcrypt.lib

DLL

Bcrypt.dll

See also

BCryptCloseAlgorithmProvider

 

 

Community Additions

ADD
Show:
© 2014 Microsoft