CryptGetKeyParam function

The CryptGetKeyParam function retrieves data that governs the operations of a key. If the Microsoft Cryptographic Service Provider is used, the base symmetric keying material is not obtainable by this or any other function.

Syntax

BOOL WINAPI CryptGetKeyParam(
  _In_    HCRYPTKEY hKey,
  _In_    DWORD     dwParam,
  _Out_   BYTE      *pbData,
  _Inout_ DWORD     *pdwDataLen,
  _In_    DWORD     dwFlags
);

Parameters

hKey [in]

The handle of the key being queried.

dwParam [in]

Specifies the type of query being made.

For all key types, this parameter can contain one of the following values.

Value	Meaning
KP_ALGID	Retrieve the key algorithm. The pbData parameter is a pointer to an ALG_ID value that receives the identifier of the algorithm that was specified when the key was created. When AT_KEYEXCHANGE or AT_SIGNATURE is specified for the Algid parameter of the CryptGenKey function, the algorithm identifiers that are used to generate the key depend on the provider used. For more information, see ALG_ID.
KP_BLOCKLEN	If a session key is specified by the hKey parameter, retrieve the block length of the key cipher. The pbData parameter is a pointer to a DWORD value that receives the block length, in bits. For stream ciphers, this value is always zero. If a public/private key pair is specified by hKey, retrieve the encryption granularity of the key pair. The pbData parameter is a pointer to a DWORD value that receives the 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 retrieved is undefined.
KP_CERTIFICATE	pbData is the address of a buffer that receives the X.509 certificate that has been encoded by using Distinguished Encoding Rules (DER). The public key in the certificate must match the corresponding signature or exchange key.
KP_GET_USE_COUNT	This value is not used.
KP_KEYLEN	Retrieve the actual length of the key. The pbData parameter is a pointer to a DWORD value that receives the key length, in bits. KP_KEYLEN can be used to get the length of any key type. Microsoft cryptographic service providers (CSPs) return a key length of 64 bits for CALG_DES, 128 bits for CALG_3DES_112, and 192 bits for CALG_3DES. These lengths are different from the lengths returned when you are enumerating algorithms with the dwParam value of the CryptGetProvParam function set to PP_ENUMALGS. The length returned by this call is the actual size of the key, including the parity bits included in the key. Microsoft CSPs that support the CALG_CYLINK_MEK ALG_ID return 64 bits for that algorithm. CALG_CYLINK_MEK is a 40-bit key but has parity and zeroed key bits to make the key length 64 bits.
KP_SALT	Retrieve the salt value of the key. The pbData parameter is a pointer to a BYTE array that receives the salt value in little-endian form. The size of the salt value varies depending on the CSP and algorithm being used. Salt values do not apply to public/private key pairs.
KP_PERMISSIONS	Retrieve the key permissions. The pbData parameter is a pointer to a DWORD value that receives the permission flags for the key. The following permission identifiers are currently defined. The key permissions can be zero or a combination of one or more of the following values. CRYPT_ARCHIVE Allow export during the lifetime of the handle of the key. This permission can be set only if it is already set in the internal permissions field of the key. Attempts to clear this permission are ignored. CRYPT_DECRYPT Allow decryption. CRYPT_ENCRYPT Allow encryption. CRYPT_EXPORT Allow the key to be exported. CRYPT_EXPORT_KEY Allow the key to be used for exporting keys. CRYPT_IMPORT_KEY Allow the key to be used for importing keys. CRYPT_MAC Allow Message Authentication Codes (MACs) to be used with key. CRYPT_READ Allow values to be read. CRYPT_WRITE Allow values to be set.

 

If a Digital Signature Standard (DSS) key is specified by the hKey parameter, the dwParam value can also be set to one of the following values.

Value	Meaning
KP_P	Retrieve the modulus prime number P of the DSS key. The pbData parameter is a pointer to a buffer that receives the value in little-endian form. The pdwDataLen parameter contains the size of the buffer, in bytes.
KP_Q	Retrieve the modulus prime number Q of the DSS key. The pbData parameter is a pointer to a buffer that receives the value in little-endian form. The pdwDataLen parameter contains the size of the buffer, in bytes.
KP_G	Retrieve the generator G of the DSS key. The pbData parameter is a pointer to a buffer that receives the value in little-endian form. The pdwDataLen parameter contains the size of the buffer, in bytes.

 

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

Value	Meaning
KP_EFFECTIVE_KEYLEN	Retrieve the effective key length of an RC2 key. The pbData parameter is a pointer to a DWORD value that receives the effective key length.
KP_IV	Retrieve the initialization vector of the key. The pbData parameter is a pointer to a BYTE array that receives the initialization vector. The size of this array is the block size, in bytes. For example, if the block length is 64 bits, the initialization vector consists of 8 bytes.
KP_PADDING	Retrieve the padding mode. The pbData parameter is a pointer to a DWORD value that receives a numeric identifier that identifies the padding method used by the cipher. This can be one of the following values. PKCS5_PADDING Specifies the PKCS 5 (sec 6.2) padding method. RANDOM_PADDING The padding uses random numbers. This padding method is not supported by the Microsoft supplied CSPs. ZERO_PADDING The padding uses zeros. This padding method is not supported by the Microsoft supplied CSPs.
KP_MODE	Retrieve the cipher mode. The pbData parameter is a pointer to a DWORD value that receives a cipher mode identifier. For more information about cipher modes, see Data Encryption and Decryption. The following cipher mode identifiers are currently defined. CRYPT_MODE_CBC The cipher mode is cipher block chaining. CRYPT_MODE_CFB The cipher mode is cipher feedback (CFB). Microsoft CSPs currently support only 8-bit feedback in cipher feedback mode. CRYPT_MODE_ECB The cipher mode is electronic codebook. CRYPT_MODE_OFB The cipher mode is Output Feedback (OFB). Microsoft CSPs currently do not support Output Feedback Mode. CRYPT_MODE_CTS The cipher mode is ciphertext stealing mode.
KP_MODE_BITS	Retrieve the number of bits to feed back. The pbData parameter is a pointer to a DWORD value that receives the number of bits that are processed per cycle when the OFB or CFB cipher modes are used.

 

If a Diffie-Hellman algorithm or Digital Signature Algorithm (DSA) key is specified by hKey, the dwParam value can also be set to the following value.

Value	Meaning
KP_VERIFY_PARAMS	Verifies the parameters of a Diffie-Hellman algorithm or DSA key. The pbData parameter is not used, and the value pointed to by pdwDataLen receives zero. This function returns a nonzero value if the key parameters are valid or zero otherwise.
KP_KEYVAL	This value is not used. Windows Vista, Windows Server 2003 and Windows XP:  Retrieve the secret agreement value from an imported Diffie-Hellman algorithm key of type CALG_AGREEDKEY_ANY. The pbData parameter is the address of a buffer that receives the secret agreement value, in little-endian format. This buffer must be the same length as the key. The dwFlags parameter must be set to 0xF42A19B6. This property can only be retrieved by a thread running under the local system account. This property is available for use in the operating systems listed above. It may be altered or unavailable in subsequent versions.

 

If a certificate is specified by hKey, the dwParam value can also be set to the following value.

Value	Meaning
KP_CERTIFICATE	A buffer that contains the DER-encoded X.509 certificate. The pbData parameter is not used, and the value pointed to by pdwDataLen receives zero. This function returns a nonzero value if the key parameters are valid or zero otherwise.

 

pbData [out]

A pointer to a buffer that receives the data. The form of this data depends on the value of dwParam.

If the size of this buffer is not known, the required size can be retrieved at run time by passing NULL for this parameter and setting the value pointed to by pdwDataLen to zero. This function will place the required size of the buffer, in bytes, in the value pointed to by pdwDataLen. For more information, see Retrieving Data of Unknown Length.

pdwDataLen [in, out]

A pointer to a DWORD value that, on entry, contains the size, in bytes, of the buffer pointed to by the pbData parameter. When the function returns, the DWORD value contains the number of bytes stored in the buffer.

Note  When processing the data returned in the buffer, applications must 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 sometimes specified large enough to ensure that the largest possible output data fits 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]

This parameter is reserved for future use and must be set to zero.

Return value

If the function succeeds, the function returns nonzero.

If the function fails, it returns zero. For extended error information, call GetLastError.

The error codes prefaced by "NTE" are generated by the particular CSP being used. Some possible error codes include the following.

Examples

For an example that uses the CryptGetKeyParam function, see Example C Program: Setting and Getting Session Key Parameters.

Requirements

See also

Key Generation and Exchange Functions

CryptSetKeyParam