CPGetKeyParam

The CPGetKeyParam function is used by applications to retrieve 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 (or "context") within the CSP. This handle is obtained via a call to CPAcquireContext.
hKey
Handle to the key on which to query parameters.
dwParam
Parameter number. See the "Remarks" section for the list of currently defined parameters.
pbData
Parameter data buffer. The function copies the specified parameter data to this buffer. The form of this data will vary, depending on the parameter number.

If this parameter is NULL, then no parameter data should be copied. Instead, the required buffer size (in bytes) should be returned in pdwDataLen. This is not an error.

pdwDataLen
Address of the parameter data length. Upon function entry, this contains the number of bytes in the pbData buffer. Upon exit, this must be set to the number of bytes of parameter data copied to the pbData buffer.

If the buffer specified by pbData is not large enough to hold the requested data, the ERROR_MORE_DATA error code should be returned via 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 should be returned in this parameter.

dwFlags
Flag values. No flags are currently defined.

Return Values

If the function succeeds, TRUE should be returned; otherwise, return FALSE. When FALSE is returned, the appropriate error code (see the following table) must be set via SetLastError.

Error Description
ERROR_MORE_DATA The pbData buffer is not large enough to hold the requested data.
NTE_BAD_FLAGS The dwFlags parameter is non-zero.
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 now be found.

Remarks

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

KP_ALGID
Key algorithm. An algorithm specifier (ALG_ID) indicating the algorithm used by this key object should be placed in the pbData buffer. A value of 4 should be returned in pdwDataLen.
KP_BLOCKLEN
If hKey references a session key, a DWORD value indicating the block length, in bits, of the cipher should be placed in the pbData buffer. For stream ciphers, this value will always be zero. A value of 4 should be returned in pdwDataLen.

If hKey references a public/private key pair, a DWORD value indicating the key pair's encryption granularity in bits should be placed in the pbData buffer. For RSA key pairs, this will be the size of the modulus. If the public-key algorithm does not support encryption, the NTE_BAD_TYPE error code should be returned.

KP_SALT
The salt value. A BYTE array containing the key's current salt value should be placed in the pbData buffer. The size of the salt value, in bytes, should be returned in pdwDataLen.

This parameter does not apply to public/private key pairs. If hKey references a public/private key pair, the NTE_BAD_TYPE error code should be returned.

KP_PERMISSIONS
Key permissions. A DWORD value containing the key's permission flags should be placed in the pbData buffer. A value of 4 should be returned in pdwDataLen. Refer to the following table for a description of each of these flags.

The following table lists the permission flags that are currently defined.
Permission flag Description
CRYPT_ENCRYPT Allows encryption
CRYPT_DECRYPT Allows decryption
CRYPT_EXPORT Allows key to be exported
CRYPT_READ Allows parameters to be read
CRYPT_WRITE Allows parameters to be set
CRYPT_MAC Allows MACs to be used with key

If the hKey parameter refers to a block cipher session key, the dwParam value may also be set to one of the following parameter types:

KP_IV
The initialization vector (IV). A BYTE array containing the key's current IV should be placed in the pbData buffer. The size of the IV, in bytes, should be returned in pdwDataLen.
KP_PADDING
The padding mode. A DWORD value containing the padding method used by the key's cipher should be placed in the pbData buffer. A value of 4 should be returned in pdwDataLen.

The following padding mode is currently defined:

PKCS5_PADDING—PKCS 5 (sec 6.2) padding method.

KP_MODE
The cipher mode. A DWORD value containing the mode of the cipher should be placed in the pbData buffer. A value of 4 should be returned in pdwDataLen.

The following table lists the cipher modes that are currently defined.
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

KP_MODE_BITS
The number of bits to feed back. A DWORD value containing the feedback width, in bits, should be placed in the pbData buffer. A value of 4 should be returned in pdwDataLen.

This parameter only applies when the OFB or CFB cipher modes are used.

KP_EFFECTIVE_KEYLEN
For a CSP to be compatible with the Microsoft base providers implementation of RC2, it should support KP_EFFECTIVE_KEYLEN. It is 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.

Additional parameters can be added as needed. If these are general-purpose in nature, rather than applying to a single provider type, you should define these in coordination with Microsoft. This will promote cross-vendor standardization, and allow the new parameter numbers to be added to the standard Microsoft Win32® header files.

See Also

CPSetKeyParam, CryptGetKeyParam