CryptExportKey (Windows CE 5.0)
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.
BOOL CRYPTFUNCCryptExportKey(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 Values
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
OS Versions: Windows CE 2.10 and later.
Header: Wincrypt.h.
Link Library: Coredll.lib.
See Also
Send Feedback on this topic to the authors