CryptSetKeyParam function (wincrypt.h)
The Microsoft Base Cryptographic Provider does not permit setting values for key exchange or signature keys; however, custom providers can define values that can be set for its keys.
BOOL CryptSetKeyParam( [in] HCRYPTKEY hKey, [in] DWORD dwParam, [in] const BYTE *pbData, [in] DWORD dwFlags );
A handle to the key for which values are to be set.
The following tables contain predefined values that can be used.
For all key types, this parameter can contain one of the following values.
||pbData points to an appropriate ALG_ID. This is used when exchanging session keys with the Microsoft Base Digital Signature Standard (DSS), Diffie-Hellman Cryptographic Provider, or compatible CSPs. After a key is agreed upon with the CryptImportKey function, the session key is enabled for use by setting its algorithm type.|
||pbData is the address of a buffer that contains 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.|
||pbData points to a DWORD value that specifies zero or more permission flags. For a description of these flags, see CryptGetKeyParam.|
||pbData points to a BYTE array that specifies a new salt value to be made part of the session key. The size of the salt value varies depending on the CSP being used. Before setting this value, determine the size of the salt value by calling the CryptGetKeyParam function. Salt values are used to make the session keys more unique, which makes dictionary attacks more difficult. The salt value is zero by default for Microsoft Base Cryptographic Provider.|
||pbData points to a CRYPT_INTEGER_BLOB structure that contains the salt. For more information, see Specifying a Salt Value.|
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.
||pbData points to the generator G from the DSS key BLOB. The data is in the form of a CRYPT_INTEGER_BLOB structure, where the pbData member is the value, and the cbData member is the length of the value. The value is expected with no header information and in little-endian form.|
||pbData points to the prime modulus P of a DSS key BLOB. The data is in the form of a CRYPT_INTEGER_BLOB structure. The pbData member is the value, and the cbData member is the length of the value. The value is expected with no header information and in little-endian form.|
||pbData points to the prime Q of a DSS key BLOB. The data is in the form of a CRYPT_INTEGER_BLOB structure where the pbData member is the value, and the cbData member is the length of the value. The value is expected with no header information and in little-endian form.|
||After the P, Q, and G values have been set, a call that specifies the KP_X value for dwParam and NULL for the pbData parameter can be made to the CryptSetKeyParam function. This causes the X and Y values to be generated.|
||Sets the information for an imported Diffie-Hellman key. The pbData parameter is the address of a CMS_DH_KEY_INFO structure that contains the key information to be set.|
||Sets the public parameters (P, Q, G, and so on) of a DSS or Diffie-Hellman key. The key handle for this key must be in the PREGEN state, generated with the CRYPT_PREGEN flag. The pbData parameter must be a pointer to a DATA_BLOB structure where the data in this structure is a DHPUBKEY_VER3 or DSSPUBKEY_VER3 BLOB. The function copies the public parameters from this CRYPT_INTEGER_BLOB structure to the key handle. After this call is made, the KP_X parameter value should be used with CryptSetKeyParam to create the actual private key. The KP_PUB_PARAMS parameter is used as one call rather than multiple calls with the parameter values KP_P, KP_Q, and KP_G.|
||This value type can only be used with RC2 keys and has been added because of the implementation of the CryptSetKeyParam function in the Microsoft Enhanced Cryptographic Provider prior to Windows 2000. In the previous implementation, the RC2 keys in the Enhanced Provider were 128 bits in strength, but the effective key length used to expand keys into the key table was only 40 bits. This reduced the strength of the algorithm to 40 bits. To maintain backward compatibility, the previous implementation will remain as is. However, the effective key length can be set to be greater than 40 bits by using KP_EFFECTIVE_KEYLEN in the CryptSetKeyParam call. The effective key length is passed in the pbData parameter as a pointer to a DWORD value with the effective key length value. The minimum effective key length on the Microsoft Base Cryptographic Provider is one, and the maximum is 40. In the Microsoft Enhanced Cryptographic Provider, the minimum is one and the maximum is 1,024. The key length must be set prior to encrypting or decrypting with the key.|
||Sets the highest Transport Layer Security (TLS) version allowed. This property only applies to SSL and TLS keys. The pbData parameter is the address of a DWORD variable that contains the highest TLS version number supported.|
pbData points to a BYTE array that specifies the initialization vector. This array must contain BlockLength/8 elements. For example, if the block length is 64 bits, the initialization vector consists of 8 bytes.
The initialization vector is set to zero by default for the Microsoft Base Cryptographic Provider.
||Set the key value for a Data Encryption Standard (DES) key. The pbData parameter is the address of a buffer that contains the key. This buffer must be the same length as the key. This property only applies to DES keys.|
||Set 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.|
||pbData points to a DWORD value that specifies the cipher mode to be used. For a list of the defined cipher modes, see CryptGetKeyParam. The cipher mode is set to CRYPT_MODE_CBC by default for the Microsoft Base Cryptographic Provider.|
||pbData points to a DWORD value that indicates the number of bits processed per cycle when the Output Feedback (OFB) or Cipher Feedback (CFB) cipher mode is used. The number of bits processed per cycle is set to 8 by default for the Microsoft Base Cryptographic Provider.|
If an RSA key is specified in the hKey parameter, the dwParam parameter value can be the following value.
||Set the Optimal Asymmetric Encryption Padding (OAEP) (PKCS #1 version 2) parameters for the key. The pbData parameter is the address of a CRYPT_DATA_BLOB structure that contains the OAEP label. This property only applies to RSA keys.|
Note that the following values are not used:
A pointer to a buffer initialized with the value to be set before calling CryptSetKeyParam. The form of this data varies depending on the value of dwParam.
Used only when dwParam is KP_ALGID. The dwFlags parameter is used to pass in flag values for the enabled key. The dwFlags parameter can hold values such as the key size and the other flag values allowed when generating the same type of key with CryptGenKey. For information about allowable flag values, see CryptGenKey.
If the function succeeds, the return value is nonzero (TRUE).
If the function fails, the return value is zero (FALSE). For extended error information, call GetLastError.
The error codes prefaced by "NTE" are generated by the particular CSP being used. Some possible error codes follow.
||The CSP context is currently being used by another process.|
||One of the parameters specifies a handle that is not valid.|
||One of the parameters contains a value that is not valid. This is most often a pointer that is not valid.|
||The dwFlags parameter is nonzero, or the pbData buffer contains a value that is not valid.|
||The dwParam parameter specifies an unknown parameter.|
||The CSP context that was specified when the hKey key was created cannot be found.|
||The function failed in some unexpected way.|
||Some CSPs have hard-coded P, Q, and G values. If this is the case, then using KP_P, KP_Q, and KP_G for the value of dwParam causes this error.|
If the KP_Q, KP_P, or KP_X parameters are set on a PREGEN Diffie-Hellman or DSS key, the key lengths must be compatible with the key length set using the upper 16 bits of the dwFlags parameter when the key was created using CryptGenKey. If no key length was set in CryptGenKey, the default key length was used. This will create an error if a nondefault key length is used to set P, Q, or X.
For an example that uses this function, see Example C Program: Duplicating a Session Key. For more code that uses this function, see Example C Program: Setting and Getting Session Key Parameters .
|Minimum supported client||Windows XP [desktop apps only]|
|Minimum supported server||Windows Server 2003 [desktop apps only]|