The CryptDeriveKey function generates cryptographic keys derived from base data. This function guarantees that all keys generated from the same base data will be identical, provided the same CSP and algorithms are used. The base data can be a password or any other user data.
This function is the same as CryptGenKey, except that the generated session keys are derived from base data instead of being random. Another difference is that the CryptDeriveKey function cannot be used to generate public/private key pairs.
A handle to the session key is returned in phKey. This handle can then be used as needed with any of the other CryptoAPI functions that require key handles.
BOOL CRYPTFUNC CryptDeriveKey(
|
HCRYPTPROV hProv, | |
|
ALG_ID Algid, | |
|
HCRYPTHASH hBaseData, | |
|
DWORD dwFlags, | |
|
HCRYPTKEY *phKey | |
|
); |
The valid values for this parameter will vary, depending on the CSP that is
used. See the “Remarks” section for a list of possible algorithm identifiers.
To obtain this handle, an application must first create a hash object with CryptCreateHash
and then add the base data to the hash object with CryptHashData.
This process is described in detail in the section Hashes
and Digital Signatures.
If this flag is not set, then the session key will not be exportable. This means the key will only be available within the current session and only the application that created it will be able to use it.
This flag does not apply to public/private key pairs.
If this flag is set, then the key will be assigned a salt value based on the unused hash value bits. You can retrieve this salt value using the CryptGetKeyParam function with the dwParam parameter set to KP_SALT.
If this flag is not set, then the key will be given a salt value of zero.
When keys with nonzero salt values are exported (using CryptExportKey),
the salt value must also be obtained and kept with the key blob.
The Microsoft RSA Base Provider ignores this flag.
If this flag is set, a new session key is not generated. Instead, the key specified by phKey is modified. The precise behavior of this flag is dependent on the type of key being generated and on the particular CSP being used.
The Microsoft RSA Base Provider ignores this flag.
To generate a key for a symmetric encryption algorithm, use the Algid parameter to specify the algorithm. The algorithms available will most likely be different for each CSP. If you are using the Microsoft RSA Base Provider, use one of the following values to specify the algorithm:
When keys are generated for symmetric block ciphers, the key by default will be set up in cipher block chaining (CBC) mode with an initialization vector of zero. This cipher mode provides a good default method for bulk encrypting data. To change these parameters, use the CryptSetKeyParam function.
Once the CryptDeriveKey function has been called, no more data can be added to the hash object. The CryptDestroyHash function should be called at this point to destroy the hash object.
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To retrieve extended error information, use the GetLastError function.
The following table lists the error codes most commonly returned by the GetLastError function. The error codes prefaced by “NTE” are generated by the particular CSP you are using.
|
Error |
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 Algid parameter specifies an algorithm that this CSP does not support. |
|
NTE_BAD_FLAGS |
The dwFlags parameter contains an invalid value. |
|
NTE_BAD_HASH |
The hBaseData parameter does not contain a valid handle to a hash object. |
|
NTE_BAD_UID |
The hProv parameter does not contain a valid context handle. |
|
NTE_FAIL |
The function failed in some unexpected way. |
#include <wincrypt.h>
HCRYPTPROV hProv = 0;
HCRYPTKEY hKey = 0;
HCRYPTHASH hHash = 0;
CHAR szPassword[ ] = "apple-camshaft";
DWORD dwLength;
// Get handle to user default provider.
if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_FULL, 0)) {
printf("Error %x during CryptAcquireContext!\n", GetLastError());
goto done;
}
// Create hash object.
if(!CryptCreateHash(hProv, CALG_MD5, 0, 0, &hHash)) {
printf("Error %x during CryptCreateHash!\n", GetLastError());
goto done;
}
// Hash password string.
dwLength = strlen(szPassword);
if(!CryptHashData(hHash, (BYTE *)szPassword, dwLength, 0)) {
printf("Error %x during CryptHashData!\n", GetLastError());
goto done;
}
// Create block cipher session key based on hash of the password.
if(!CryptDeriveKey(hProv, CALG_RC2, hHash, CRYPT_EXPORTABLE, &hKey)) {
printf("Error %x during CryptDeriveKey!\n", GetLastError());
goto done;
}
// Use ‘hKey’ to do something.
...
done:
// Destroy hash object.
if(hHash != 0) CryptDestroyHash(hHash);
// Destroy session key.
if(hKey != 0) CryptDestroyKey(hKey);
// Release provider handle.
if(hProv != 0) CryptReleaseContext(hProv, 0);
CryptAcquireContext, CryptCreateHash, CryptDestroyHash, CryptDestroyKey, CryptExportKey, CryptGenKey, CryptGetKeyParam, CryptHashData, CryptSetKeyParam