BCryptGenerateKeyPair

The BCryptGenerateKeyPair function creates an empty public/private key pair. After you create a key by using this function, you can use the BCryptSetProperty function to set its properties; however, the key cannot be used until the BCryptFinalizeKeyPair function is called.

Syntax

NTSTATUS BCryptGenerateKeyPair(
         BCRYPT_ALG_HANDLE hAlgorithm,
         BCRYPT_KEY_HANDLE *phKey,
         ULONG dwLength,
         ULONG dwFlags
)

Parameters

hAlgorithm
Type: BCRYPT_ALG_HANDLE

[in, out]

Handle of an algorithm provider that supports signing, asymmetric encryption, or key agreement. This handle must have been created by using the BCryptOpenAlgorithmProvider function.

phKey
Type: BCRYPT_KEY_HANDLE *

[out] A pointer to a BCRYPT_KEY_HANDLE that receives the handle of the key. This handle is used in subsequent functions that require a key, such as BCryptEncrypt. This handle must be released when it is no longer needed by passing it to the BCryptDestroyKey function.

dwLength
Type: ULONG

[in] The length, in bits, of the key. Algorithm providers have different key size restrictions for each standard asymmetric algorithm.

dwFlags
Type: ULONG

[in] A set of flags that modify the behavior of this function. No flags are currently defined, so this parameter should be zero.

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_INVALID_HANDLE	The algorithm handle in the hAlgorithm parameter is not valid.
STATUS_INVALID_PARAMETER	One or more parameters are not valid.
STATUS_NOT_SUPPORTED	The specified provider does not support asymmetric key encryption.

Remarks

Depending on what processor modes a provider supports, BCryptGenerateKeyPair can be called either from user mode or kernel mode. Kernel mode callers can execute either at PASSIVE_LEVELIRQL or DISPATCH_LEVEL IRQL. If the current IRQL level is DISPATCH_LEVEL, the handle provided in the hAlgorithm parameter must have been opened by using the BCRYPT_PROV_DISPATCH flag, and any pointers passed to the BCryptGenerateKeyPair function must refer to nonpaged (or locked) memory.

Requirements

Header: Declared in bcrypt.h.

Library: Use bcrypt.lib.