CryptImportKey

Article
06/30/2006

This function is used to transfer a cryptographic key from a key Binary Large Object (BLOB) to the cryptographic service provider (CSP).

BOOL WINAPI CryptImportKey( 
HCRYPTPROV hProv, 
BYTE *pbData, 
DWORD dwDataLen, 
HCRYPTKEY hPubKey,
DWORD dwFlags, 
HCRYPTKEY *phKey);

Parameters

hProv
[in] Handle to the application's CSP. An application obtains this handle by using the CryptAcquireContext function.
pbData
[in] Pointer to the buffer containing the key BLOB. This key BLOB was generated by the CryptExportKey function, either by this same application or by another application running on a different computer.

This key BLOB consists of a standard header followed by the encrypted key.
dwDataLen
[in] Specifies the length, in bytes, of the key BLOB.
hPubKey
[in] The meaning of this parameter differs, depending on the CSP type and the type of key BLOB being imported.

If a signed key BLOB is being imported, this key is used to validate the signature of the key BLOB. In this case, this parameter should contain a handle to the key exchange public key of the party that created the key BLOB.

If the key BLOB is encrypted with the key exchange key pair (for example, a SIMPLEBLOB), then this parameter may be the handle to the key exchange key.

If the key BLOB is encrypted with a session key (for example, an encrypted PRIVATEKEYBLOB), then this parameter should contain a handle to this session key.

If the key BLOB is not encrypted (for example, a PUBLICKEYBLOB), then this parameter is not used, and should be zero.

dwFlags
[in] Currently used only when a public/private key pair in the form of a PRIVATEKEYBLOB is imported into the CSP.

The following flag values are defined.

Value	Description
CRYPT_EXPORTABLE	The key being imported is eventually to be re-exported. If this flag is not used, then calls to CryptExportKey with the key handle fail.
CRYPT_NO_SALT.	Specifies that a no-salt value gets allocated for a 40-bit symmetric key.

phKey
[out] Address to which the function copies a handle to the key that was imported.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. 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.
NTE_BAD_ALGID	The simple key BLOB you are trying to import is not encrypted with the expected key exchange algorithm.
NTE_BAD_DATA	Either the algorithm that works with the public key you are trying to import is not supported by this CSP, or an attempt was made to import a session key that was encrypted with something other than one of YOUR public keys.
NTE_BAD_FLAGS	The dwFlags parameter specified is invalid.
NTE_BAD_TYPE	The key BLOB type is not supported by this CSP and is possibly invalid.
NTE_BAD_UID	The hProv parameter does not contain a valid context handle.
NTE_BAD_VER	The key BLOB's version number does not match the CSP version. This usually indicates that the CSP needs to be upgraded.

Example

#include <wincrypt.h>

FILE *hSourceFile = NULL;
HCRYPTPROV hProv = 0;
HCRYPTKEY hKey = 0;
BYTE *pbKeyBlob = NULL;
DWORD dwBlobLen;

// Open the file, getting the file handle 'hSourceFile'.
...

// Get a handle to the default provider.
if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_FULL, 0)) {
 printf("Error %x during CryptAcquireContext!\n", GetLastError());
 goto done;
}

// Read the key BLOB length from the file and allocate memory.
fread(&dwBlobLen, sizeof(DWORD), 1, hSourceFile);
pbKeyBlob = malloc(dwBlobLen);

// Read the key BLOB from the file.
fread(pbKeyBlob, 1, dwBlobLen, hSourceFile);

// Import the key BLOB into the CSP.
if(!CryptImportKey(hProv, pbKeyBlob, dwBlobLen, 0, 0, &hKey)) {
 printf("Error %x during CryptImportKey!\n", GetLastError());
 free(pbKeyBlob);
 goto done;
}

// Free memory.
free(pbKeyBlob);

// Use 'hKey' to perform cryptographic operations.
...

done:

// Destroy the session key.
if(hKey) CryptDestroyKey(hKey);

// Release the provider handle.
if(hProv) CryptReleaseContext(hProv, 0);

Requirements

Runs On	Versions	Defined in	Include	Link to
Windows CE OS	2.10 and later	Wincrypt.h		Cryptapi.lib

Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

Last updated on Tuesday, July 13, 2004

CryptImportKey

Additional resources