Export (0) Print
Expand All
Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

CryptGetKeyParam

Windows CE 3.0

This function lets applications retrieve data that governs the operations of a key. Note that in the Microsoft Cryptographic Service Providers, the base symmetric keying material is not obtainable by this or any other function.

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

Parameters

hKey
[in] Handle to the key on which to query parameters.
dwParam
[in] Specifies the parameter number. See the Remarks section for a list of valid parameters.
pbData
[out] Pointer to a buffer that receives the parameter data. The function will copy the specified parameter data to this buffer. The form of this data will vary, depending on the parameter number.

This parameter can be NULL to set the size of this information for memory allocation purposes.

pdwDataLen
[in/out] Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the pbData parameter. When the function returns, the variable pointed to by the pdwDataLen parameter contains the number of bytes stored in the buffer.
Note   When processing the data returned in the buffer, applications need to 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] Specifies a bitmask of flags. This parameter is reserved for future use and should always be zero.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. 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

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

KP_ALGID
Key algorithm. The pbData buffer will contain an ALG_ID value indicating the algorithm that was specified when the key was created. Note that when key specifications AT_KEYEXCHANGE and AT_SIGNATURE are specified for the Algid parameter, the algorithm identifiers that are used to generate the key depend on the provider used. As a result, for these key specifications the values returned from CryptGetKeyParam (when the KP_ALGID parameter is specified) depend on the provider used.
KP_BLOCKLEN
If a session key is specified by hKey, this parameter returns the block length, in bits, of the cipher. The pbData buffer will contain a DWORD value indicating the block length. For stream ciphers, this value will always be zero.

If a public/private key pair is specified by hKey, this parameter returns the key pair's 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 returned by this parameter is undefined.

KP_KEYLEN
Used to get the actual length of a key in bits, The length of the key is located in the DWORD pointed to by pbData. This parameter can be used to get the length of any key type.
KP_SALT
The salt value. The pbData buffer will contain a BYTE array indicating the current salt value. The size of the salt value will vary depending on the CSP and algorithm being used.

Salt values do not apply to public/private key pairs.

KP_PERMISSIONS
Key permissions. The pbData buffer will contain a DWORD value with zero or more permission flags set. Refer to the table at the end of this section for a description of each of these flags.

If a DSS key is specified by hKey, the dwParam value can also be set to one of the following parameter types.

KP_P
The pbData buffer will contain the prime modulus P from the DSS key BLOB. The length of the data is returned in the pdwDataLen parameter.
KP_Q
The pbData buffer will contain the prime Q from the DSS key BLOB. The length of the data is returned in the pdwDataLen parameter.
KP_G
The pbData buffer will contain the generator G from the DSS key BLOB. The length of the data is returned in the pdwDataLen parameter.

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

KP_EFFECTIVE_KEYLEN
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.
KP_IV
The initialization vector. The pbData buffer will contain a BYTE array indicating the current initialization vector. This array contains block_length/8 elements. For example, if the block length is 64 bits, the initialization vector will consist of eight bytes.
KP_PADDING
The padding mode. The pbData buffer will contain a DWORD value indicating the padding method used by the cipher. Following are the padding modes currently defined:

PKCS5_PADDING—PKCS 5 (sec 6.2) padding method.

KP_MODE
The cipher mode. The pbData buffer will contain a DWORD value indicating the mode of the cipher. Refer to the following table for a list of valid cipher modes.
KP_MODE_BITS
The number of bits to feed back. The pbData buffer will contain a DWORD value indicating the number of bits that are processed per cycle when the OFB or CFB cipher modes are used.

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

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

The following table lists the flags in the bit field that are obtained when the KP_PERMISSIONS parameter is read. These permission flags are ignored by the Microsoft Base Cryptographic Provider. However, custom CSPs can use these flags to restrict operations on keys.

Permission flag Description
CRYPT_ENCRYPT Allow encryption.
CRYPT_DECRYPT Allow decryption.
CRYPT_EXPORT Allow key to be exported.
CRYPT_READ Allow parameters to be read.
CRYPT_WRITE Allow parameters to be set.
CRYPT_MAC Allow MACs to be used with key.

Example

#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.
if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_FULL, 0)) {
 printf("Error %x during CryptAcquireContext!\n", GetLastError());
 goto done;
}

// 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);

// Release the provider handle.
if(hProv != 0) CryptReleaseContext(hProv, 0);
 

Requirements

Runs On Versions Defined in Include Link to
Windows CE OS 2.10 and later Wincrypt.h   Cryptapi.lib
Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

See Also

CryptSetKeyParam, ALG_ID


 Last updated on Tuesday, July 13, 2004

© 1992-2000 Microsoft Corporation. All rights reserved.

Show:
© 2014 Microsoft