CPGetKeyParam

The CPGetKeyParam function retrieves data that governs the operations of a key.

BOOL CPGetKeyParam(
  HCRYPTPROV hProv,       // in
  HCRYPTKEY hKey,         // in
  DWORD dwParam,          // in
  BYTE *pbData,           // out
  DWORD *pdwDataLen,      // in, out
  DWORD dwFlags           // in
);

Parameters

hProv

Handle to a particular key container within the CSP. This handle is obtained with a call to CPAcquireContext.

hKey

Handle to the key that is the target of the query.

dwParam

All key types can use any of the following key parameter types.

dwParam value	Key types	Copied to pdData	Returned pdwDataLen
KP_ALGID	all	The algorithm identifier (ALG_ID) used by this key object.	4
KP_BLOCKLEN	all	If hKey is a session key, a DWORD value indicating the block length in bits. If hKey is a public/private key pair, a DWORD value indicating the key pair's granularity. For RSA key pairs, this is the size of the modulus. If the public-key algorithm does not support encryption, the NTE_BAD_TYPE error code is returned.	4
KP_KEYLEN	all	The actual length of the key in bits. For more information, see Remarks.	4
KP_SALT	all session keys	A BYTE array containing the key's current salt value. This parameter does not apply to public/private key pairs. If hKey references a public/private key pair, the NTE_BAD_TYPE error code is returned.	Length of the BYTE array
KP_ PERMISSIONS	all	A DWORD value indicating the permission to be associated with the key. See Remarks for a table of permission flags.	4
KP_IV	block cipher keys	A BYTE array containing the key's current initialization vector (IV).	Length of the BYTE array
KP_PADDING	block cipher keys	A DWORD value indicating the padding method used. Currently, PKCS5_Padding is defined.	4
KP_MODE	block cipher keys	A DWORD value indicating the cipher mode used. See the table in Remarks for possible values.	4
KP_MODE_BITS	block cipher keys	A DWORD value indicating the feedback width in bits. This is used only with OFB and CFB cipher modes.	4
KP_EFFECTIVE_ KEYLEN	RC2	A DWORD value indicating the effective key length of an RC2 key.	4

More parameters can be added as needed. General-purpose parameters can be define in coordination with Microsoft to promote cross-vendor standardization and allow the new parameter numbers to be added to the standard Microsoft Win32® header files.

pbData

Pointer to a data buffer. The dwParam parameter specifies the type of data to be copied into this buffer.

It is not an error if this parameter is NULL. If pbData is NULL, no data is copied. Instead, the required buffer size (in bytes) is returned in pdwDataLen and a second call to the function with the correct number of bytes allocated for the pbData buffer is expected. See Retrieving Data of Unknown Length for a detailed discussion and examples.

pdwDataLen

Address of a DWORD to hold the byte length for the pbData buffer. Upon function entry, the DWORD contains the number of bytes allocated for the pbData buffer. Upon exit, it must be set to the actual number of bytes needed for the pbData buffer.

If the buffer specified by pbData is not large enough to hold the requested data, the ERROR_MORE_DATA error code is returned with the SetLastError function. In this case, the required buffer size must be returned in pdwDataLen.

If this function fails with any error code other than ERROR_MORE_DATA, zero is returned in this parameter.

dwFlags

No flags are currently defined.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using SetLastError.

Remarks

Microsoft CSPs return a key length of 64 bits for CALG_DES, 128 for CALG_3DES_112, and 192 for CALG_3DES. These lengths are different from the lengths returned when enumerating algorithms with CryptGetProvParam with dwParam set to PP_ENUMALGS. The length returned CPGetProvParam is the actual size of the key including parity bits.

Microsoft CSPs that support the ALG_ID of type CALG_CYLINK_MEK return 64 bits for that algorithm. CALG_CYLINK_MEK is a 40 bit key, but has parity bits and zeroed key bits to make the key length 64 bits.

The following table lists the permission flags that are currently defined.

The following table lists the cipher modes that are currently defined.

Requirements

  Windows NT/2000: Requires Windows NT 4.0 or later.
  Windows 95/98: Requires Windows 95 OSR2 or later (or Windows 95 with Internet Explorer 3.02 or later).
  Header: Declared in Wincrypt.h.

See Also

CPSetKeyParam, CryptGetKeyParam