[New - Windows NT]
[New - Windows 95, OEM Service Release 2]
The CryptGetKeyParam function lets applications retrieve data that governs of the operations of a key. Note that the base keying material is not obtainable by this function or any other function.
BOOL CRYPTFUNC CryptGetKeyParam(
| HCRYPTKEY hKey, | |
| DWORD dwParam, | |
| BYTE *pbData, | |
| DWORD *pdwDataLen, | |
| DWORD dwFlags | |
| ); |
Parameters
hKey
[in] A handle to the key on which to query parameters.
dwParam
[in] The parameter number. See the "Remarks" section for a list of valid parameters.
pbData
[out] The parameter data buffer. The function will copy the specified parameter data to this buffer. The form of this data will vary, depending on the parameter number.
This parameter can be NULL if all you are doing is determining the number of bytes required for the returned parameter data.
pdwDataLen
[in/out] The address of the parameter data length. Before calling this function, the caller should set this parameter to the length, in bytes, of the pbData buffer. Upon return, this address will contain the number of bytes of parameter data copied to the buffer.
If the buffer specified by pbData is not large enough to hold the data, the function returns the ERROR_MORE_DATA error code (through GetLastError) and stores the required buffer size, in bytes, into the variable pointed to by pdwDataLen.
If pbData is NULL, then no error is returned and the function stores the size of the data, in bytes, in the variable pointed to by pdwDataLen.
dwFlags
[in] The flag values. This parameter is reserved for future use and should always be zero.
Remarks
For all key types, the dwParam value can be set to one of the following key parameter types:
| Parameter | Description |
| KP_ALGID | Key algorithm. The pbData buffer will contain an ALG_ID value indicating that the algorithm was specified when the key was created. |
| KP_BLOCKLEN | If a session key is specified by hKey, this parameter returns the block length, in bits, of the cipher. The pbData buffer will contain a DWORD value indicating the block length. For stream ciphers, this value will always be zero.
If a public/private key pair is specified by hKey, this parameter returns the key pair's encryption granularity in bits. For example, the Microsoft RSA Base Provider generates 512-bit RSA key pairs, so a value of 512 is returned for these keys. If the public-key algorithm does not support encryption, the value returned by this parameter is undefined. |
| KP_SALT | The salt value. The pbData buffer will contain a BYTE array indicating the current salt value. The size of the salt value will vary depending on the CSP and algorithm being used. Before setting this parameter, it should be read using CryptGetKeyParam in order to determine the size.
Salt values do not apply to public/private key pairs. |
| KP_PERMISSIONS | Key permissions. The pbData buffer will contain a DWORD value with zero or more permission flags set. Refer to the table at the end of this section for a description of each of these flags. |
If a block cipher session key is specified by hKey, the dwParam value can also be set to one of the following parameter types.
| Parameter | Description |
| KP_IV | The initialization vector. The pbData buffer will contain a BYTE array indicating the current initialization vector. This array contains <block length>/8 elements. For example, if the block length is 64 bits, the initialization vector will consist of 8 bytes. |
| KP_PADDING | The padding mode. The pbData buffer will contain a DWORD value indicating the padding method used by the cipher. Following are the padding modes currently defined:
PKCS5_PADDING ¾ PKCS 5 (sec 6.2) padding method. |
| KP_MODE | The cipher mode. The pbData buffer will contain a DWORD value indicating the mode of the cipher. Refer to the following table for a list of valid cipher modes. |
| KP_MODE_BITS | The number of bits to feed back. The pbData buffer will contain a DWORD value indicating the number of bits that are processed per cycle when the OFB or CFB cipher modes are used. |
The following table lists the possible values for the KP_MODE parameter. These cipher modes are discussed in the section Encrypting and Decrypting Data.
| Cipher Mode | Description |
| CRYPT_MODE_ECB | Electronic codebook. |
| CRYPT_MODE_CBC | Cipher block chaining. |
| CRYPT_MODE_OFB | Output feedback mode. |
| CRYPT_MODE_CFB | Cipher feedback mode. |
The following table lists the flags in the bit field that are obtained when the KP_PERMISSIONS parameter is read. These permission flags are ignored by the Microsoft RSA Base Provider. However, custom CSPs can use these flags to restrict operations on keys.
| Permission Flag | Description |
| CRYPT_ENCRYPT | Allow encryption. |
| CRYPT_DECRYPT | Allow decryption. |
| CRYPT_EXPORT | Allow key to be exported. |
| CRYPT_READ | Allow parameters to be read. |
| CRYPT_WRITE | Allow parameters to be set. |
| CRYPT_MAC | Allow MACs to be used with key. |
Return Values
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_FLAGS | The dwFlags parameter is nonzero. |
| NTE_BAD_KEY or NTE_NO_KEY | The key specified by the hKey parameter is invalid. |
| NTE_BAD_TYPE | The dwParam parameter specifies an unknown parameter number. |
| NTE_BAD_UID | The CSP context that was specified when the key was created cannot be found. |
Example
#include <wincrypt.h>
HCRYPTPROV hProv = 0;
HCRYPTKEY hKey = 0;
DWORD dwMode;
BYTE pbData[16];
DWORD dwCount;
DWORD i;
// 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 random block cipher session key.
if(!CryptGenKey(hProv, CALG_RC2, CRYPT_EXPORTABLE, &hKey)) {
printf("Error %x during CryptGenKey!\n", GetLastError());
goto done;
}
// Read the cipher mode.
dwCount = sizeof(DWORD);
if(!CryptGetKeyParam(hKey, KP_MODE, &dwMode, &dwCount, 0)) {
printf("Error %x during CryptGetKeyParam!\n", GetLastError());
goto done;
}
assert(dwCount==sizeof(BYTE));
// Print out cipher mode.
printf("Default cipher mode:%d\n", dwMode);
// Read initialization vector.
dwCount = 16;
if(!CryptGetKeyParam(hKey, KP_IV, pbData, &dwCount, 0)) {
printf("Error %x during CryptGetKeyParam!\n", GetLastError());
goto done;
}
// Print out initialization vector.
printf("Default IV:");
for(i=0;i<dwCount;i++) printf("%2.2x ",pbData[i]);
printf("\n");
done:
// Destroy session key.
if(hKey != 0) CryptDestroyKey(hKey);
// Release provider handle.
if(hProv != 0) CryptReleaseContext(hProv, 0);
See Also