Expand Minimize
EN
Este conteúdo não está disponível no seu idioma mas aqui tem a versão em inglês.

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.

ValueMeaning
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.

ValueMeaning
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.

ValueMeaning
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.

ValueMeaning
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.

ValueMeaning
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.

Return codeDescription
ERROR_INVALID_HANDLE

One of the parameters specifies a handle that is not valid.

ERROR_INVALID_PARAMETER

One of the parameters contains a value that is not valid. This is most often a pointer that is not valid.

ERROR_MORE_DATA

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.

NTE_BAD_FLAGS

The dwFlags parameter is nonzero.

NTE_BAD_KEY or NTE_NO_KEY

The key specified by the hKey parameter is not valid.

NTE_BAD_TYPE

The dwParam parameter specifies an unknown value number.

NTE_BAD_UID

The CSP context that was specified when the key was created cannot be found.

 

Examples

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

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Wincrypt.h

Library

Advapi32.lib

DLL

Advapi32.dll

See also

Key Generation and Exchange Functions
CryptSetKeyParam

 

 

Conteúdo da Comunidade

Adicionar
Mostrar:
© 2014 Microsoft