CryptGetKeyParam

Overview

Group

Quick Info

Windows NT
Yes
Win95
OSR2
Win32s
No
Import Library
advapi32.lib
Header File
wincrypt.h
Unicode
WinNT
Platform Notes
None

[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);