CryptGetKeyParam function (wincrypt.h)
Syntax
BOOL CryptGetKeyParam(
[in] HCRYPTKEY hKey,
[in] DWORD dwParam,
[out] BYTE *pbData,
[in, out] DWORD *pdwDataLen,
[in] DWORD dwFlags
);
Parameters
[in] hKey
The handle of the key being queried.
[in] dwParam
Specifies the type of query being made.
For all key types, this parameter can contain one of the following values.
| Value | Meaning |
|---|---|
|
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. |
|
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. |
|
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. |
|
This value is not used. |
|
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. |
|
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. |
|
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.
|
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.
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 |
|---|---|
|
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. |
|
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. |
|
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. |
|
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.
|
|
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 |
|---|---|
|
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. |
|
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.
[out] pbData
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.
[in, out] pdwDataLen
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.
[in] dwFlags
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.
| Return code | Description |
|---|---|
|
One of the parameters specifies a handle that is not valid. |
|
One of the parameters contains a value that is not valid. This is most often a pointer that is not valid. |
|
If the buffer specified by the pbData parameter is not large enough to hold the returned data, the function sets the ERROR_MORE_DATA code and stores the required buffer size, in bytes, in the variable pointed to by pdwDataLen. |
|
The dwFlags parameter is nonzero. |
|
The key specified by the hKey parameter is not valid. |
|
The dwParam parameter specifies an unknown value number. |
|
The CSP context that was specified when the key was created cannot be found. |
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP [desktop apps only] |
| Minimum supported server | Windows Server 2003 [desktop apps only] |
| Target Platform | Windows |
| Header | wincrypt.h |
| Library | Advapi32.lib |
| DLL | Advapi32.dll |