BCryptImportKeyPair function (bcrypt.h)

The BCryptImportKeyPair function imports a public/private key pair from a key BLOB. The BCryptImportKey function is used to import a symmetric key pair.

Syntax

NTSTATUS BCryptImportKeyPair(
  [in]      BCRYPT_ALG_HANDLE hAlgorithm,
  [in, out] BCRYPT_KEY_HANDLE hImportKey,
  [in]      LPCWSTR           pszBlobType,
  [out]     BCRYPT_KEY_HANDLE *phKey,
  [in]      PUCHAR            pbInput,
  [in]      ULONG             cbInput,
  [in]      ULONG             dwFlags
);

Parameters

[in] hAlgorithm

The handle of the algorithm provider to import the key. This handle is obtained by calling the BCryptOpenAlgorithmProvider function.

[in, out] hImportKey

This parameter is not currently used and should be NULL.

[in] pszBlobType

A null-terminated Unicode string that contains an identifier that specifies the type of BLOB that is contained in the pbInput buffer. This can be one of the following values.

Value Meaning
BCRYPT_DH_PRIVATE_BLOB
The BLOB is a Diffie-Hellman public/private key pair BLOB. The pbInput buffer must contain a BCRYPT_DH_KEY_BLOB structure immediately followed by the key data.
BCRYPT_DH_PUBLIC_BLOB
The BLOB is a Diffie-Hellman public key BLOB. The pbInput buffer must contain a BCRYPT_DH_KEY_BLOB structure immediately followed by the key data.
BCRYPT_DSA_PRIVATE_BLOB
The BLOB is a DSA public/private key pair BLOB. The pbInput buffer must contain a BCRYPT_DSA_KEY_BLOB or BCRYPT_DSA_KEY_BLOB_V2 structure immediately followed by the key data. BCRYPT_DSA_KEY_BLOB is used for key lengths from 512 to 1024 bits. BCRYPT_DSA_KEY_BLOB_V2 is used for key lengths that exceed 1024 bits but are less than or equal to 3072 bits.

Windows 8:  Support for BCRYPT_DSA_KEY_BLOB_V2 begins.

BCRYPT_DSA_PUBLIC_BLOB
The BLOB is a DSA public key BLOB. The pbInput buffer must contain a BCRYPT_DSA_KEY_BLOB or BCRYPT_DSA_KEY_BLOB_V2 structure immediately followed by the key data. BCRYPT_DSA_KEY_BLOB is used for key lengths from 512 to 1024 bits. BCRYPT_DSA_KEY_BLOB_V2 is used for key lengths that exceed 1024 bits but are less than or equal to 3072 bits.

Windows 8:  Support for BCRYPT_DSA_KEY_BLOB_V2 begins.

BCRYPT_ECCPRIVATE_BLOB
The BLOB is an elliptic curve cryptography (ECC) private key. The pbInput buffer must contain a BCRYPT_ECCKEY_BLOB structure immediately followed by the key data.
BCRYPT_ECCPUBLIC_BLOB
The BLOB is an ECC public key. The pbInput buffer must contain a BCRYPT_ECCKEY_BLOB structure immediately followed by the key data.
BCRYPT_PUBLIC_KEY_BLOB
The BLOB is a generic public key of any type. The type of key in this BLOB is determined by the Magic member of the BCRYPT_KEY_BLOB structure.
BCRYPT_PRIVATE_KEY_BLOB
The BLOB is a generic private key of any type. The private key does not necessarily contain the public key. The type of key in this BLOB is determined by the Magic member of the BCRYPT_KEY_BLOB structure.
BCRYPT_RSAPRIVATE_BLOB
The BLOB is an RSA public/private key pair BLOB. The pbInput buffer must contain a BCRYPT_RSAKEY_BLOB structure immediately followed by the key data.
BCRYPT_RSAPUBLIC_BLOB
The BLOB is an RSA public key BLOB. The pbInput buffer must contain a BCRYPT_RSAKEY_BLOB structure immediately followed by the key data.
LEGACY_DH_PUBLIC_BLOB
The BLOB is a Diffie-Hellman public key BLOB that was exported by using CryptoAPI. The Microsoft primitive provider does not support importing this BLOB type.
LEGACY_DH_PRIVATE_BLOB
The BLOB is a legacy Diffie-Hellman Version 3 Private Key BLOB that contains a Diffie-Hellman public/private key pair that was exported by using CryptoAPI.
LEGACY_DSA_PRIVATE_BLOB
The BLOB is a DSA public/private key pair BLOB that was exported by using CryptoAPI.
LEGACY_DSA_PUBLIC_BLOB
The BLOB is a DSA public key BLOB that was exported by using CryptoAPI. The Microsoft primitive provider does not support importing this BLOB type.
LEGACY_DSA_V2_PRIVATE_BLOB
The BLOB is a DSA version 2 private key in a form that can be imported by using CryptoAPI.
LEGACY_RSAPRIVATE_BLOB
The BLOB is an RSA public/private key pair BLOB that was exported by using CryptoAPI.
LEGACY_RSAPUBLIC_BLOB
The BLOB is an RSA public key BLOB that was exported by using CryptoAPI. The Microsoft primitive provider does not support importing this BLOB type.

[out] phKey

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

[in] pbInput

The address of a buffer that contains the key BLOB to import. The cbInput parameter contains the size of this buffer. The pszBlobType parameter specifies the type of key BLOB this buffer contains.

[in] cbInput

The size, in bytes, of the pbInput buffer.

[in] dwFlags

A set of flags that modify the behavior of this function. This can be zero or the following value.

Value Meaning
BCRYPT_NO_KEY_VALIDATION
Do not validate the public portion of the key pair.

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 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 algorithm provider specified by the hAlgorithm parameter does not support the BLOB type specified by the pszBlobType parameter.

Remarks

Depending on what processor modes a provider supports, BCryptImportKeyPair can be called either from user mode or kernel mode. Kernel mode callers can execute either at PASSIVE_LEVEL IRQL 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 BCryptImportKeyPair function must refer to nonpaged (or locked) memory.

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.

Requirements

Requirement Value
Minimum supported client Windows Vista [desktop apps | UWP apps]
Minimum supported server Windows Server 2008 [desktop apps | UWP apps]
Target Platform Windows
Header bcrypt.h
Library Bcrypt.lib
DLL Bcrypt.dll

See also

BCryptDestroyKey

BCryptExportKey

BCryptImportKey