CryptSetKeyParam
[New
- Windows NT]
[New
- Windows 95, OEM Service Release 2]
The CryptSetKeyParam
function lets applications customize various aspects of a key s operations.
Generally,
this function is used to set session-specific parameters on symmetric keys.
Note that the base keying material is not accessible by this function.
The Microsoft
RSA Base Provider has no settable parameters on key exchange or signature keys.
However, custom providers may define parameters that can be set on these keys.
BOOL
CRYPTFUNC CryptSetKeyParam(
|
HCRYPTKEY hKey, |
|
|
DWORD dwParam, |
|
|
BYTE *pbData, |
|
|
DWORD dwFlags |
|
|
); |
|
Parameters
hKey
[in] A handle
to the key on which to set parameters.
dwParam
[in] The
parameter number. See the Remarks section for a list of valid parameters.
pbData
[in] The
parameter data buffer. Place the parameter data in this buffer before calling CryptSetKeyParam.
The form of this data will vary, depending on the parameter number.
dwFlags
[in] The flag
values. This parameter is reserved for future use and should always be zero.
Remarks
For all
session key types, the dwParam value can be set to one of the following
key parameter types;
|
Parameter |
Description |
|
KP_SALT |
The salt
value. The pbData buffer should contain a BYTE array specifying
a new salt value. This value is made part of the session key. The size of the
salt value will vary depending on the CSP being used so, before setting this
parameter, it should be read using CryptGetKeyParam in order to
determine its size. When it is
suspected that the base data used for derived keys is less than ideal, salt
values are often used to make the session keys more unique. This makes
dictionary attacks more difficult. When using
the Microsoft RSA Base Provider, this parameter defaults to zero. |
|
KP_PERMISSIONS |
The key
permissions flags. The pbData buffer should contain a DWORD
value specifying zero or more permission flags. Refer to the CryptGetKeyParam function for a
description of these flags. When using
the Microsoft RSA Base Provider, this parameter defaults to 0xFFFFFFFF. |
If a block
cipher session key is specified by hKey, the dwParam value can
also be set to one of the following parameter types.
|
Parameter |
Description |
|
KP_IV |
The
initialization vector. The pbData buffer should contain a BYTE
array specifying the initialization vector. This array should contain <block
length>/8 elements. For example, if the block length is 64 bits, the
initialization vector will consist of 8 bytes. When using
the Microsoft RSA Base Provider, this parameter defaults to zero. |
|
KP_PADDING |
The padding
mode. The pbData buffer should contain a DWORD value specifying
the padding method to be used by the cipher. Following are the padding modes
currently defined: PKCS5_PADDING
PKCS 5 (sec 6.2) padding
method. When using
the Microsoft RSA Base Provider, this parameter defaults to PKCS5_PADDING. |
|
KP_MODE |
The cipher
mode. The pbData buffer should contain a DWORD value specifying
the cipher mode to be used. Refer to the CryptGetKeyParam function for a list of the defined cipher modes. When using
the Microsoft RSA Base Provider, this parameter defaults to CRYPT_MODE_CBC. |
|
KP_MODE_BITS |
The number
of bits to feed back. The pbData buffer contains a DWORD value
indicating the number of bits that are processed per cycle when the OFB or
CFB cipher modes are used. When using
the Microsoft RSA Base Provider, this parameter defaults to 8. |
Return Values
If the
function succeeds, the return value is nonzero.
If the
function fails, the return value is zero. To retrieve extended error
information, use the GetLastError function.
The following
table lists the error codes most commonly returned by the GetLastError
function. The error codes prefaced by NTE are generated by the particular CSP
you are using.
|
Error |
Description |
|
ERROR_INVALID_HANDLE |
One of the
parameters specifies an invalid handle. |
|
ERROR_BUSY |
The CSP
context is currently being used by another process. |
|
ERROR_INVALID_PARAMETER |
One of the
parameters contains an invalid value. This is most often an illegal pointer. |
|
NTE_BAD_FLAGS |
The dwFlags
parameter is nonzero or the pbData buffer contains an invalid value. |
|
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. |
Example
#include <wincrypt.h>
HCRYPTPROV hProv = 0;
HCRYPTKEY hKey = 0;
DWORD dwMode;
BYTE pbData[16];
DWORD dwCount;
DWORD i;
// Get handle to user default provider.
if(!CryptAcquireContext(&hProv, NULL, NULL,
PROV_RSA_FULL, 0)) {
printf("Error %x during CryptAcquireContext!\n",
GetLastError());
goto done;
}
// Create 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 random initialization vector.
if(!CryptGenRandom(hProv, 8, pbData)) {
printf("Error %x during CryptGenRandom!\n", GetLastError());
goto done;
}
// Set initialization vector.
if(!CryptSetKeyParam(hKey, KP_IV, pbData, 0)) {
printf("Error %x during CryptGetKeyParam!\n", GetLastError());
goto done;
}
// Do something with 'hKey'.
...
done:
// Destroy session key.
if(hKey != 0) CryptDestroyKey(hKey);
// Release provider handle.
if(hProv != 0) CryptReleaseContext(hProv, 0);
See Also