CryptGetKeyParam info  Overview  Group

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(

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:

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

The following table lists the possible values for the KP_MODE parameter. These cipher modes are discussed in the section Encrypting and Decrypting Data.

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.

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.

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

CryptSetKeyParam