CryptExportKey

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function exports cryptographic keys from of a cryptographic service provider (CSP) in a secure manner.

The caller passes to the CryptImportKey function a handle to the key to be exported and gets a key binary large object (BLOB). This key BLOB can be sent over a nonsecure transport or stored in a nonsecure storage location. The key BLOB is useless until the intended recipient uses the CryptImportKey function, which imports the key into the recipient's CSP.

Syntax

BOOL CRYPTFUNC CryptExportKey( 
  HCRYPTKEY hKey, 
  HCRYPTKEY hExpKey, 
  DWORD dwBlobType, 
  DWORD dwFlags, 
  BYTE* pbData, 
  DWORD* pdwbDataLen
);

Parameters

• hKey
  [in] HCRYPTKEY handle to the key to be exported.

• hExpKey
  [in] Handle to a cryptographic key belonging to the destination user. This key encrypts the key data within the key BLOB. This ensures that only the destination user will be able to use of the key BLOB.

  Most often, this will be the key exchange public key of the destination user. However, certain protocols in some CSPs require that a session key belonging to the destination user be used for this purpose. Neither the Microsoft Base Cryptographic Provider nor the Microsoft Enhanced Cryptographic Provider currently support this.

  If the key BLOB type specified by dwBlobType is PUBLICKEYBLOB, then this parameter is unused and must be set to zero.

  If the key BLOB type specifies PRIVATEKEYBLOB in dwBlobType, this is typically a handle to a session key that is used to encrypt the key BLOB. Some CSPs allow this parameter to be zero, in which case the application should encrypt the private key BLOB manually to protect it.

  To determine how Microsoft cryptographic service providers use to this parameter, see the programmer's guide topics under Cryptography.

• dwBlobType
  [in] Specifies the type of key BLOB to be exported. The following table shows the possible values for this parameter.

  Constant	Description
  SIMPLEBLOB	Used to transport session keys.
  PLAINTEXTKEYBLOB	Used to export any key supported by the CSP in use. The key is exported in plaintext.
  PUBLICKEYBLOB	Used to transport public keys.
  PRIVATEKEYBLOB	Used to transport public/private key pairs.
  OPAQUEBLOB	Used to store session keys in a Schannel CSP. OPAQUEBLOBs are non-transferable and must be used within the CSP that generated the BLOB.
  SYMMETRICWRAPKEYBLOB	Used to export and import a symmetric key wrapped with another symmetric key. The actual wrapped key is in the format specified in the IETF SMIME X9.42 standard.

  For more information about exchanging cryptographic keys, see the programmer's guide topics under Cryptography.

• dwFlags
  [in] Bitmask of flags.

• pbData
  [out] Pointer to a buffer that receives the key BLOB.

  This parameter can be NULL when used to acquire the size of the buffer for memory allocation purposes.

• pdwbDataLen
  [in, out] On input, pointer to a DWORD value that specifies the size, in bytes, of the buffer pointed to by the pbData parameter. On output, the DWORD value contains the number of bytes stored in the buffer.

  When processing the data returned in the buffer, applications must use the actual size of the data returned. The actual size may be slightly smaller than the size of the buffer specified on input. On input, buffer sizes are usually specified large enough to ensure that the largest possible output data will fit in the buffer. On output, the variable pointed to by this parameter is updated to reflect the actual size of the data copied to the buffer.

Return Value

TRUE indicates success. FALSE indicates failure. To get extended error information, call the GetLastError function.

The following table shows the common values for the GetLastError function. The error values prefaced by NTE are generated by the particular CSP you are using.

Example Code

#include <wincrypt.h>
HCRYPTPROV hProv; // Handle to CSP
HCRYPTKEY hKey; // Handle to session key
HCRYPTKEY hXchgKey; // Handle to receiver's exchange public key
BYTE *pbKeyBlob = NULL;
DWORD dwBlobLen;
...
// Determine the size of the key BLOB and allocate memory.
if(!CryptExportKey(hKey, hXchgKey, SIMPLEBLOB, 0, NULL, &dwBlobLen)) {
 printf("Error %x computing BLOB length!\n", GetLastError());
 ...
}
if((pbKeyBlob = malloc(dwBlobLen)) == NULL) {
 printf("Out of memory!\n");
 ...
}
// Export the key into a simple key BLOB.
if(!CryptExportKey(hKey, hXchgKey, SIMPLEBLOB, 0, pbKeyBlob, &dwBlobLen)) {
 printf("Error %x during CryptExportKey!\n", GetLastError());
 ...
}

Requirements

See Also

Reference

CryptImportKey