CryptGetKeyParam

This function lets applications retrieve data that governs the operations of a key. Note that in the Microsoft Cryptographic Service Providers, the base symmetric keying material is not obtainable by this or any other function.

At a Glance

Syntax

BOOL CRYPTFUNC CryptGetKeyParam( HCRYPTKEY hKey,
DWORD dwParam, BYTE *pbData, DWORD *pdwDataLen,
DWORD dwFlags );

Parameters

hKey

[in] Handle to the key on which to query parameters.

dwParam

[in] Specifies the parameter number. See the "Remarks" section for a list of valid parameters.

pbData

[out] Pointer to a buffer that receives the parameter data. 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 to set the size of this information for memory allocation purposes.

pdwDataLen

[in/out] Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the pbData parameter. When the function returns, the variable pointed to by the pdwDataLen parameter contains the number of bytes stored in the buffer.

Note   When processing the data returned in the buffer, applications need to 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.

dwFlags

[in] Specifies a bitmask of flags. This parameter is reserved for future use and should always be zero.

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.

Remarks

For all key types, the dwParam value can be set to one of the following key parameter types.

KP_ALGID

Key algorithm. The pbData buffer will contain an ALG_ID value indicating the algorithm that was specified when the key was created. Note that when key specifications AT_KEYEXCHANGE and AT_SIGNATURE are specified for the Algid parameter, the algorithm identifiers that are used to generate the key depend on the provider used. As a result, for these key specifications the values returned from CryptGetKeyParam (when the KP_ALGID parameter is specified) depend on the provider used.

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 Base Cryptographic 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_KEYLEN

Used to get the actual length of a key in bits, The length of the key is located in the DWORD pointed to by pbData. This parameter can be used to get the length of any key type.

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.

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 DSS key is specified by hKey, the dwParam value can also be set to one of the following parameter types.

KP_P

The pbData buffer will contain the prime modulus P from the DSS key BLOB. The length of the data is returned in the pdwDataLen parameter.

KP_Q

The pbData buffer will contain the prime Q from the DSS key BLOB. The length of the data is returned in the pdwDataLen parameter.

KP_G

The pbData buffer will contain the generator G from the DSS key BLOB. The length of the data is returned in the pdwDataLen parameter.

If a block cipher session key is specified by hKey, the dwParam value can also be set to one of the following parameter types.

KP_EFFECTIVE_KEYLEN

Used to query the effective key length of an RC2 key. The value of the effective key length is returned as a DWORD pointed to by the pbData parameter.

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 eight 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 common values for the KP_MODE parameter. These cipher modes are discussed in Cryptography.

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 Base Cryptographic Provider. However, custom CSPs can use these flags to restrict operations on keys.

Example

#include <wincrypt.h>

HCRYPTPROV hProv = 0;
HCRYPTKEY hKey = 0;
DWORD dwMode;
BYTE pbData[16];
DWORD dwCount;
DWORD i;

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

// Create a 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 the cipher mode.
printf("Default cipher mode: %d\n", dwMode);

// Read the initialization vector.
dwCount = 16;
if(!CryptGetKeyParam(hKey, KP_IV, pbData, &dwCount, 0)) {
 printf("Error %x during CryptGetKeyParam!\n", GetLastError());
 goto done;
}
// Print out the initialization vector.
printf("Default IV:");
for(i=0;i<dwCount;i++) printf("%2.2x ",pbData[i]);
printf("\n");

done:

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

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

See Also

CryptSetKeyParam