Share via

CryptExportKey (Compact 2013)

  • Article

3/28/2014

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.

Value

Description

ERROR_INVALID_HANDLE

One of the parameters specifies an invalid handle.

ERROR_INVALID_PARAMETER

One of the parameters contains an invalid value. This is most often an illegal pointer.

ERROR_MORE_DATA

If the buffer specified by the pbData parameter is not large enough to hold the returned data, the function sets the ERROR_MORE_DATA code, and stores the required buffer size, in bytes, into the variable pointed to by pdwbDataLen.

NTE_BAD_FLAGS

The dwFlags parameter is nonzero.

NTE_BAD_KEY

One or both of the keys specified by hKey and hExpKey are invalid.

NTE_BAD_KEY_STATE

You do not have permission to export the key. That is, when the hKey key was created, the CRYPT_EXPORTABLE flag was not specified.

NTE_BAD_PUBLIC_KEY

The key BLOB type specified by dwBlobType is PUBLICKEYBLOB, but hExpKey does not contain a public key handle.

NTE_BAD_TYPE

The dwBlobType parameter specifies an unknown BLOB type.

NTE_BAD_UID

The CSP context that was specified when the hKey key was created cannot be found.

NTE_NO_KEY

A session key is being exported and the hExpKey parameter does not specify a public key.

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

Header

wincrypt.h

Library

coredll.lib

See Also

Reference

Cryptography Functions
CryptImportKey