다음을 통해 공유

CryptGetKeyParam (Windows Embedded CE 6.0)

  • 아티클

1/6/2010

This function lets applications retrieve data that governs the operations of a key. In the Microsoft cryptographic service providers (CSPs), the base symmetric keying material is not obtainable by this or any other function.

Syntax

BOOL CRYPTFUNC CryptGetKeyParam( 
  HCRYPTKEY hKey,
  DWORD dwParam, 
  BYTE* pbData, 
  DWORD* pdwDataLen, 
  DWORD dwFlags
);

Parameters

  • hKey
    [in] HCRYPTKEY handle to the key to query.

  • dwParam
    [in] Specifies the key parameter type. The following table shows the available key types.

    Key type Description pbData content

    KP_IV

    Initialization vector

    BYTE array indicating the current initialization vector. This array contains block_length/8 elements. For example, if the block length is sixty-four bits, the initialization vector consists of eight bytes.

    KP_SALT

    Salt value

    BYTE array indicating the current salt value. 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_PADDING

    Padding mode

    DWORD value indicating the padding method used by the cipher. The padding method currently defined is PKCS5_PADDING — PKCS 5 (sec 6.2).

    KP_MODE

    Cipher mode

    DWORD value indicating the mode of the cipher. For a list of valid cipher modes, refer to the table in the Remarks section.

    KP_MODE_BITS

    Number of bits to feed back

    DWORD value indicating the number of bits that are processed per cycle when the OFB or CFB cipher modes are used.

    KP_PERMISSIONS

    Key permissions

    DWORD value with zero or more bit permission flags set. For a description of each of these flags, refer to the permission flag table at the end of this Remarks section.

    KP_ALGID

    Key algorithm

    ALG_ID identifier for the algorithm specified when the key was created. Note that when key specifications AT_KEYEXCHANGE and AT_SIGNATURE are used, algorithm identifiers that are used to generate the key depend on the provider used. As a result, the values returned from CryptGetKeyParam for these key specifications when the KP_ALGID value is specified depend on the provider used. To determine the algorithm identifier that the different providers use for the key specifications AT_KEYEXCHANGE and AT_SIGNATURE, see ALG_ID.

    KP_BLOCKLEN

    Session key or public/private key pair specified by hKey

    DWORD value indicating the block length. For stream ciphers, this value is always zero.

    If session key is specified by hKey, the pbData contains the key cipher's block length, in bits.

    If a public/private key pair is specified by hKey, pbData contains a BLOB with the key pair's encryption granularity, in bits.

    KP_KEYLEN

    DWORD value, in bits, used to get the actual length of the key

    This value can be used to get the length of any key type. Microsoft 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 enumerating algorithms with the dwParam value of CryptGetProvParam 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 ALG_ID CALG_CYLINK_MEK 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_EX

    Salt value

    The CRYPT_DATA_BLOB that specifies the variable size salt value.

    KP_P

    hKey specifies a DSS key

    Prime modulus P from the DSS key BLOB. The length of the data is returned in the pdwDataLen parameter.

    KP_G

    hKey specifies a DSS key

    Prime Q from the DSS key BLOB. The length of the data is returned in the pdwDataLen parameter.

    KP_Q

    hKey specifies a DSS key

    Generator G from the key BLOB. The length of the data is returned in the pdwDataLen parameter.

    KP_EFFECTIVE_KEYLEN

    hKey specifies block cipher session key

    DWORD value equal to the effective key length.

    KP_Z

    DH secret agreement value.

    Retrieves 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 IPSEC_FLAG_CHECK.

    KP_CERTIFICATE

    Certificate

    A buffer containing the DER-encoded X.509 certificate. The public key in the certificate must match the corresponding signature or exchange key.

    KP_KEYEXCHANGE_PIN

    Password to unlock a smart card

    A null-terminated ASCII string that sets the password used to enable the private key for the key exchange.

    KP_SIGNATURE_PIN

    Password to unlock a smart card

    A null-terminated ASCII string that sets the password used to enable the signature private key.
  • pbData
    [out] Pointer to a buffer that receives the parameter data. The function returns the specified data in this buffer. The form of this data varies depending on the parameter number. This parameter can be NULL to set the size of this buffer for memory allocation purposes.

  • pdwDataLen
    [in, out] On input, pointer to a DWORD value specifying the size, in bytes, of the buffer pointed to by the pbData parameter. On output, the function returns the DWORD value containing the number of bytes stored in the buffer.

    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 usually specified large enough to ensure that the largest possible output data will fit 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] Reserved for future use and must be set to zero.

Return Value

TRUE indicates success. FALSE indicates failure. To get extended error information, call the GetLastError function.

The following table shows the common values for the GetLastError function. The error values prefaced by NTE are generated by the particular CSP you are using.

Value Description

ERROR_INVALID_HANDLE

One of the parameters specifies an invalid handle.

ERROR_INVALID_PARAMETER

One of the parameters contains an invalid value. This is most often an illegal pointer.

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, into 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 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 be found.

Remarks

The following table shows the common values for the KP_MODE parameter. These cipher modes are discussed in the topics under Cryptography.

Cipher mode Description

CRYPT_MODE_ECB

Electronic codebook

CRYPT_MODE_CBC

Cipher block chaining

CRYPT_MODE_OFB

Output feedback mode

The following table shows the flags in the bit field when the KP_PERMISSIONS parameter is read. The Microsoft Base Cryptographic Provider ignores these permission flags. However, custom CSPs can use these flags to restrict operations on keys.

Permission flag Description

CRYPT_ENCRYPT

Allows encryption.

CRYPT_DECRYPT

Allows decryption.

CRYPT_EXPORT

Allows exporting of the key.

CRYPT_READ

Allows reading of the parameters.

CRYPT_WRITE

Allows setting of the parameters.

CRYPT_MAC

Allows using MACs with the key.

CRYPT_EXPORT_KEY

Allows using the key for exporting keys.

CRYPT_IMPORT_KEY

Allows using the key for importing keys.

IPSEC_FLAG_CHECK

Allows using the key for exporting keys for IPSec.

Example Code

#include <wincrypt.h>
HCRYPTPROV hProv = 0;
HCRYPTKEY hKey = 0;
DWORD dwMode;
BYTE pbData[16];
DWORD dwCount;
DWORD i;
// Get a handle to user default provider using CryptAcquireContext.
// For sample code, see <A HREF="wce50lrfcryptacquirecontext.htm">CryptAcquireContext</A>.
...
...
// Create a random block cipher session key.
if(!CryptGenKey(hProv, CALG_RC2, CRYPT_EXPORTABLE, &hKey)) {
 printf("Error %x during CryptGenKey!\n", GetLastError());
 goto done;
}
// Read the cipher mode.
dwCount = sizeof(DWORD);
if(!CryptGetKeyParam(hKey, KP_MODE, &dwMode, &dwCount, 0)) {
 printf("Error %x during CryptGetKeyParam!\n", GetLastError());
 goto done;
}
assert(dwCount==sizeof(BYTE));
// Print out the cipher mode.
printf("Default cipher mode: %d\n", dwMode);
// Read the initialization vector.
dwCount = 16;
if(!CryptGetKeyParam(hKey, KP_IV, pbData, &dwCount, 0)) {
 printf("Error %x during CryptGetKeyParam!\n", GetLastError());
 goto done;
}
// Print out the initialization vector.
printf("Default IV:");
for(i=0;i<dwCount;i++) printf("%2.2x ",pbData[i]);
printf("\n");
done:
// Destroy the session key.
if(hKey != 0) CryptDestroyKey(hKey);
// Free the provider handle.
if(hProv != 0) CryptReleaseContext(hProv, 0);

Requirements

Header wincrypt.h
Library coredll.lib
Windows Embedded CE Windows CE 2.10 and later

See Also

Reference

Cryptography Functions
CryptSetKeyParam
ALG_ID