CPExportKey

The CPExportKey function securely exports cryptographic keys from a CSP's key container.

BOOL CPExportKey(
  HCRYPTPROV hProv,      // in
  HCRYPTKEY hKey,        // in
  HCRYPTKEY hPubKey,     // in
  DWORD dwBlobType,      // in
  DWORD dwFlags,         // in
  BYTE *pbData,          // out
  DWORD *pdwDataLen      // in, out
);

Parameters

hProv

Handle to a particular key container within the CSP. This handle is obtained with a call to CPAcquireContext.

hKey

Handle of the key to be exported.

hPubKey

Handle of a cryptographic key belonging to the destination user. The exported key data within the created key BLOB is encrypted using this key. This ensures that only the destination user will be able to make use of the key BLOB.

Most often, this handle will be the handle of the key exchange public key of the destination user. Certain protocols, however, require that this handle be the handle of a session key belonging to the destination user.

If the key BLOB is a PUBLICKEYBLOB and is not to be encrypted, this parameter is not used and must be zero.

dwBlobType

Type of key BLOB to be exported. The following key BLOB types are defined.

BLOB type	Use
SIMPLEBLOB	To transport session keys.
PUBLICKEYBLOB	To transport public keys.
PRIVATEKEYBLOB	To transport public/private key pairs.
OPAQUEKEYBLOB	To store session keys in an Schannel CSP. The OPAQUEKEYBLOB type is non-transferable and must be used within the CSP that generated the BLOB.

Additional key BLOB types can be defined as needed.

dwFlags

The following values are defined. These values are only used in Schannel CSPs.

Flag value	Effect
CRYPT_DESTROYKEY	Destroys the original key in the OPAQUEKEYBLOB.
CRYPT_SSL2_ FALLBACK	Sets the first eight bytes of the RSA encryption block padding to 0x03 rather than to random data. This prevents version rollback attacks and is discussed in the SSL3 specification.

pbData

Pointer to a data buffer to return the key BLOB.
It is not an error if this parameter is NULL. If pbData is NULL, no parameter data is copied. Instead, the required buffer size (in bytes) is returned in pdwDataLen and a second call to the function with the correct number of bytes allocated for the pbData buffer is expected. For a detailed discussion and examples, see Retrieving Data of Unknown Length.

pdwDataLen

Address of a DWORD value to hold the length of the BLOB to be returned in the pbData buffer. Upon function entry, this DWORD value contains the number of bytes allocated for the pbData buffer. Upon exit, it must be set to the actual number of bytes of data needed for the pbData buffer.

If the buffer specified by pbData is not large enough to hold the key BLOB data, the ERROR_MORE_DATA error code is returned with the SetLastError function. In this case, the required buffer size must be returned in pdwDataLen.

If this function fails with any error code other than ERROR_MORE_DATA, zero is returned in this parameter.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using SetLastError.

Requirements

  Windows NT/2000: Requires Windows NT 4.0 or later.
  Windows 95/98: Requires Windows 95 OSR2 or later (or Windows 95 with Internet Explorer 3.02 or later).
  Header: Declared in Wincrypt.h.

See Also

CPImportKey, CryptExportKey