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 |
|---|---|
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
The BLOB is an ECC public key. The pbInput buffer must contain a BCRYPT_ECCKEY_BLOB structure immediately followed by the key data. |
|
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. |
|
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. |
|
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. |
|
The BLOB is an RSA public key BLOB. The pbInput buffer must contain a BCRYPT_RSAKEY_BLOB structure immediately followed by the key data. |
|
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. |
|
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. |
|
The BLOB is a DSA public/private key pair BLOB that was exported by using CryptoAPI. |
|
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. |
|
The BLOB is a DSA version 2 private key in a form that can be imported by using CryptoAPI. |
|
The BLOB is an RSA public/private key pair BLOB that was exported by using CryptoAPI. |
|
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 |
|---|---|
|
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 |
|---|---|
|
The function was successful. |
|
The algorithm handle in the hAlgorithm parameter is not valid. |
|
One or more parameters are not valid. |
|
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 |