BCryptExportKey function

The BCryptExportKey function exports a key to a memory BLOB that can be persisted for later use.

Syntax


NTSTATUS WINAPI BCryptExportKey(
  _In_   BCRYPT_KEY_HANDLE hKey,
  _In_   BCRYPT_KEY_HANDLE hExportKey,
  _In_   LPCWSTR pszBlobType,
  _Out_  PUCHAR pbOutput,
  _In_   ULONG cbOutput,
  _Out_  ULONG *pcbResult,
  _In_   ULONG dwFlags
);

Parameters

hKey [in]

The handle of the key to export.

hExportKey [in]

The handle of the key with which to wrap the exported key. Use this parameter when exporting BLOBs of type BCRYPT_AES_WRAP_KEY_BLOB; otherwise, set it to NULL.

Note  The hExportKey handle must be supplied by the same provider that supplied the hKey handle, and hExportKey must be a handle to a symmetric key that can be used in the Advanced Encryption Standard (AES) key wrap algorithm. When the hKey handle is from the Microsoft provider, hExportKey must be an AES key handle.

Windows Server 2008 and Windows Vista:  This parameter is not used and should be set to NULL.

pszBlobType [in]

A null-terminated Unicode string that contains an identifier that specifies the type of BLOB to export. This can be one of the following values.

ValueMeaning
BCRYPT_AES_WRAP_KEY_BLOB

Export an AES key wrapped key. The hExportKey parameter must reference a valid BCRYPT_KEY_HANDLE pointer to the key encryption key, and the key represented by the hKey parameter must be a multiple of 8 bytes long.

Windows Server 2008 and Windows Vista:  This BLOB type is not supported.

BCRYPT_DH_PRIVATE_BLOB

Export a Diffie-Hellman public/private key pair. The pbOutput buffer receives a BCRYPT_DH_KEY_BLOB structure immediately followed by the key data.

BCRYPT_DH_PUBLIC_BLOB

Export a Diffie-Hellman public key. The pbOutput buffer receives a BCRYPT_DH_KEY_BLOB structure immediately followed by the key data.

BCRYPT_DSA_PRIVATE_BLOB

Export a DSA public/private key pair. The pbOutput buffer receives 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

Export a DSA public key. The pbOutput buffer receives 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

Export an elliptic curve cryptography (ECC) private key. The pbOutput buffer receives a BCRYPT_ECCKEY_BLOB structure immediately followed by the key data.

BCRYPT_ECCPUBLIC_BLOB

Export an ECC public key. The pbOutput buffer receives a BCRYPT_ECCKEY_BLOB structure immediately followed by the key data.

BCRYPT_KEY_DATA_BLOB

Export a symmetric key to a data BLOB. The pbOutput buffer receives a BCRYPT_KEY_DATA_BLOB_HEADER structure immediately followed by the key BLOB.

BCRYPT_OPAQUE_KEY_BLOB

Export a symmetric key in a format that is specific to a single cryptographic service provider (CSP). Opaque BLOBs are not transferable and must be imported by using the same CSP that generated the BLOB. Opaque BLOBs are only intended to be used for interprocess transfer of keys and are not suitable to be persisted and read across versions of a provider.

BCRYPT_PUBLIC_KEY_BLOB

Export 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

Export 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_RSAFULLPRIVATE_BLOB

Export a full RSA public/private key pair. The pbOutput buffer receives a BCRYPT_RSAKEY_BLOB structure immediately followed by the key data. This BLOB will include additional key material compared to the BCRYPT_RSAPRIVATE_BLOB type.

BCRYPT_RSAPRIVATE_BLOB

Export an RSA public/private key pair. The pbOutput buffer receives a BCRYPT_RSAKEY_BLOB structure immediately followed by the key data.

BCRYPT_RSAPUBLIC_BLOB

Export an RSA public key. The pbOutput buffer receives a BCRYPT_RSAKEY_BLOB structure immediately followed by the key data.

LEGACY_DH_PRIVATE_BLOB

Export a legacy Diffie-Hellman Version 3 Private Key BLOB that contains a Diffie-Hellman public/private key pair that can be imported by using CryptoAPI.

LEGACY_DH_PUBLIC_BLOB

Export a legacy Diffie-Hellman Version 3 Private Key BLOB that contains a Diffie-Hellman public key that can be imported by using CryptoAPI.

LEGACY_DSA_PRIVATE_BLOB

Export a DSA public/private key pair in a form that can be imported by using CryptoAPI.

LEGACY_DSA_PUBLIC_BLOB

Export a DSA public key in a form that can be imported by using CryptoAPI.

LEGACY_DSA_V2_PRIVATE_BLOB

Export a DSA version 2 private key in a form that can be imported by using CryptoAPI.

LEGACY_RSAPRIVATE_BLOB

Export an RSA public/private key pair in a form that can be imported by using CryptoAPI.

LEGACY_RSAPUBLIC_BLOB

Export an RSA public key in a form that can be imported by using CryptoAPI.

 

pbOutput [out]

The address of a buffer that receives the key BLOB. The cbOutput parameter contains the size of this buffer. If this parameter is NULL, this function will place the required size, in bytes, in the ULONG pointed to by the pcbResult parameter.

cbOutput [in]

Contains the size, in bytes, of the pbOutput buffer.

pcbResult [out]

A pointer to a ULONG that receives the number of bytes that were copied to the pbOutput buffer. If the pbOutput parameter is NULL, this function will place the required size, in bytes, in the ULONG pointed to by this parameter.

dwFlags [in]

A set of flags that modify the behavior of this function. No flags are defined for this function.

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_BUFFER_TOO_SMALL

The size specified by the cbOutput parameter is not large enough to hold the ciphertext.

STATUS_INVALID_HANDLE

The key handle in the hKey parameter is not valid.

STATUS_INVALID_PARAMETER

One or more parameters are not valid.

STATUS_NOT_SUPPORTED

The specified BLOB type is not supported by the provider.

 

Remarks

Depending on what processor modes a provider supports, BCryptExportKey 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 hKey parameter must be derived from an algorithm handle returned by a provider that was opened with the BCRYPT_PROV_DISPATCH flag, and any pointers passed to the BCryptExportKey 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). 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

BCryptImportKey
BCryptImportKeyPair

 

 

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.