Export (0) Print
Expand All
0 out of 2 rated this helpful - Rate this topic

CryptSetKeyParam

Windows Mobile 6.5
A version of this page is also available for
4/8/2010

This function customizes various aspects of a key's operations. The values set by this function are not persisted to memory and are used only within a single session.

The Microsoft cryptographic service providers (CSPs) do not allow setting the values for key exchange or signature keys; however, custom providers may define parameters that can be set on these keys.


BOOL WINAPI CryptSetKeyParam( 
  HCRYPTKEY hKey, 
  DWORD dwParam, 
  BYTE* pbData, 
  DWORD dwFlags
);
hKey

[in] HCRYPTKEY handle to the key on which to set parameters.

dwParam

[in] Key parameter type.

The following table shows the available key types.

Key type Description pbData content

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, the algorithm identifiers that are used to generate the key depend on the provider. 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 parameter 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_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_EFFECTIVE_KEYLEN

hKey specifies block cipher session key

DWORD value equal to the effective key length.

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_IV

Initialization vector. The hkey parameter specifies a block cipher session key

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_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_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-four bits for that algorithm. CALG_CYLINK_MEK is a 64 key but has parity and zeroed key bits to make the key length 64 bits.

KP_MODE

hkey specifies a block cipher session key

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

KP_MODE_BITS

Number of bits to feed back; the hkey parameter specifies a block cipher session key

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

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_PADDING

Padding mode. The hkey parameter specifies a block cipher session key

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

KP_PERMISSIONS

Key permissions

DWORD value with zero or more bit permission flags set.

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_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_SALT_EX

Salt value

The CRYPT_DATA_BLOB that specifies the variable size salt value.

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.

KP_X

hKey specifies a DSS key

After the P, Q, and G values have been set, a call can be made to CryptSetKeyParam to specify the KP_X value for dwParam and NULL for the pbData parameter. This causes the X and Y values to be generated.

pbData

[in] Pointer to the data buffer. The value in this buffer must be set before calling the CryptSetKeyParam function. The form of this data varies depending on the parameter value.

dwFlags

[in] Reserved for future use and must be set to zero.

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_BUSY

The CSP context is currently being used by another process.

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.

NTE_BAD_DATA

Either the algorithm that works with the public key you are trying to import is not supported by this CSP, or an attempt was made to import a session key that was encrypted with something other than one of your public keys.

NTE_BAD_FLAGS

The dwFlags parameter is nonzero or the pbData buffer contains an invalid value.

NTE_BAD_KEY

The hKey parameter does not contain a valid handle to a key.

NTE_BAD_TYPE

The dwParam parameter specifies an unknown parameter.

NTE_BAD_UID

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

NTE_FAIL

The function failed in some unexpected way.

#include <wincrypt.h>
HCRYPTPROV hProv = 0;
HCRYPTKEY hKey = 0;
DWORD dwMode;
BYTE pbData[16];
DWORD dwCount;
DWORD i;
// Get a handle to the 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;
}
// Set the cipher mode.
dwMode = CRYPT_MODE_ECB;
if(!CryptSetKeyParam(hKey, KP_MODE, &dwMode, 0)) {
 printf("Error %x during CryptSetKeyParam!\n", GetLastError());
 goto done;
}
// Generate a random initialization vector.
if(!CryptGenRandom(hProv, 8, pbData)) {
 printf("Error %x during CryptGenRandom!\n", GetLastError());
 goto done;
}
// Set the initialization vector.
if(!CryptSetKeyParam(hKey, KP_IV, pbData, 0)) {
 printf("Error %x during CryptSetKeyParam!\n", GetLastError());
 goto done;
}
// Use 'hKey' to encrypt a message.
...
done:
// Destroy the session key.
if(hKey != 0) CryptDestroyKey(hKey);
// Free the provider handle.
if(hProv != 0) CryptReleaseContext(hProv, 0);
Headerwincrypt.h
Librarycoredll.lib
Windows Embedded CEWindows CE 2.10 and later
Windows MobileWindows Mobile Version 5.0 and later
Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.