CryptSetKeyParam 函数 （wincrypt.h）
Microsoft 基本加密提供程序 不允许为密钥交换或签名密钥设置值;但是，自定义提供程序可以定义可为其键设置的值。
语法
BOOL CryptSetKeyParam(
[in] HCRYPTKEY hKey,
[in] DWORD dwParam,
[in] const BYTE *pbData,
[in] DWORD dwFlags
);
参数
[in] hKey
要为其设置值的键的句柄。
[in] dwParam
下表包含可以使用的预定义值。
对于所有键类型，此参数可以包含以下值之一。
| 价值 | 意义 |
|---|---|
|
pbData 指向适当的 ALG_ID。 这在与 Microsoft 基本数字签名标准（DSS）、Diffie-Hellman 加密提供程序或兼容的 CSP 交换会话密钥时使用。 在与 CryptImportKey 函数达成一致后，通过设置其算法类型启用会话密钥以供使用。 |
|
pbData 是缓冲区的地址，该缓冲区包含已使用 可分辨编码规则（DER）编码的 X.509 证书。 证书中的公钥必须与相应的签名或交换密钥匹配。 |
|
pbData 指向指定零个或多个权限标志的 DWORD 值。 有关这些标志的说明，请参阅 CryptGetKeyParam。 |
|
pbData 指向 BYTE 数组，该数组指定要成为会话键的一部分的新 盐 值。 盐值的大小因使用的 CSP 而异。 设置此值之前，请通过调用 CryptGetKeyParam 函数来确定盐值的大小。 Salt 值用于使会话键更加独特，这使得字典攻击更加困难。 默认情况下，Microsoft基本加密提供程序的盐值为零。 |
|
pbData 指向包含盐的 CRYPT_INTEGER_BLOB 结构。 有关详细信息，请参阅 指定 Salt 值。 |
如果 数字签名标准（DSS）密钥是由 hKey 参数指定的，则 dwParam 值也可以设置为以下值之一。
| 价值 | 意义 |
|---|---|
|
pbData 指向 DSS 密钥 BLOB中的生成器 G。 数据采用 CRYPT_INTEGER_BLOB 结构的形式，其中 pbData 成员是值，cbData 成员是值的长度。 该值预期没有标头信息，并且 小端 窗体中。 |
|
pbData 指向 DSS 密钥 BLOB 的主要模数 P。 数据采用 CRYPT_INTEGER_BLOB 结构的形式。 pbData 成员是值，cbData 成员是值的长度。 该值预期没有标头信息，并且 小端 窗体中。 |
|
pbData 指向 DSS 密钥 BLOB 的主要 Q。 数据采用 CRYPT_INTEGER_BLOB 结构的形式，其中 pbData 成员是值，cbData 成员是值的长度。 该值预期没有标头信息，并且 小端 窗体中。 |
|
设置 P、Q 和 G 值后，可以对 CryptSetKeyParam 函数指定 dwParam 的KP_X值 ，并为 pbData 参数指定 NULL。 这会导致生成 X 值和 Y 值。 |
如果 Diffie-Hellman 算法 或 数字签名算法（DSA）密钥由 hKey指定，则 dwParam 值也可以设置为以下值之一。
| 价值 | 意义 |
|---|---|
|
设置导入 Diffie-Hellman 密钥的信息。 pbData 参数是包含要设置的关键信息的 CMS_DH_KEY_INFO 结构的地址。 |
|
设置 DSS 或 Diffie-Hellman 密钥的公共参数（P、Q、G 等）。 此密钥的密钥句柄必须处于 PREGEN 状态，并使用 CRYPT_PREGEN 标志生成。 pbData 参数必须是指向 DATA_BLOB 结构的指针，其中此结构中的数据是DHPUBKEY_VER3或DSSPUBKEY_VER3 BLOB。 该函数将此 CRYPT_INTEGER_BLOB 结构中的公共参数复制到密钥句柄。 进行此调用后，KP_X参数值应与 CryptSetKeyParam 一起使用，以创建实际的私钥。 KP_PUB_PARAMS参数用作一个调用，而不是使用参数值KP_P、KP_Q和KP_G多个调用。 |
如果 块密码会话密钥 由 hKey 参数指定，则 dwParam 值也可以设置为以下值之一。
| 价值 | 意义 |
|---|---|
|
此值类型只能与 RC2 密钥一起使用，并且由于在 Windows 2000 之前的Microsoft增强加密提供程序中实现 CryptSetKeyParam 函数而添加。 在之前的实现中，增强提供程序中的 RC2 键强度为 128 位，但用于将密钥扩展到密钥表中的有效密钥长度仅为 40 位。 这会将算法的强度降低到 40 位。 为了保持向后兼容性，以前的实现将保持不变。 但是，通过在 CryptSetKeyParam 调用中使用KP_EFFECTIVE_KEYLEN，可以将有效密钥长度设置为大于 40 位。 有效密钥长度在 pbData 参数中传递，作为指向具有有效密钥长度值的 DWORD 值的指针。 Microsoft基本加密提供程序上的最小有效密钥长度为 1，最大值为 40。 在Microsoft增强型加密提供程序中，最小值为 1,024， 最大值为 1,024。 在加密或解密密钥之前，必须设置密钥长度。 |
|
设置允许的最高 传输层安全性 （TLS） 版本。 此属性仅适用于 SSL 和 TLS 密钥。 pbData 参数是包含支持的最高 TLS 版本号的 DWORD 变量的地址。 |
|
pbData 指向指定初始化向量的 BYTE 数组。 此数组必须包含 BlockLength/8 元素。 例如，如果块长度为 64 位，则初始化向量由 8 个字节组成。
默认情况下，Microsoft基本加密提供程序的初始化向量设置为零。 |
|
设置 数据加密标准（DES）密钥的密钥值。 pbData 参数是包含密钥的缓冲区的地址。 此缓冲区的长度必须与密钥长度相同。 此属性仅适用于 DES 键。 |
|
设置填充模式。 pbData 参数是指向 DWORD 值的指针，该值接收用于标识 密码使用的 填充 方法的数字标识符。 这可以是以下值之一。 |
|
pbData 指向 DWORD 值，该值指定要使用的 密码 模式。 有关定义的密码模式的列表，请参阅 CryptGetKeyParam。 默认情况下，密码模式设置为Microsoft基本加密提供程序CRYPT_MODE_CBC。 |
|
pbData 指向 DWORD 值，该值指示使用 输出反馈（OFB）或 密码反馈（CFB）密码模式时，每个周期处理的位数。 默认情况下，每个周期处理的位数设置为 8，Microsoft基本加密提供程序。 |
如果在 hKey 参数中指定了 RSA 键，则 dwParam 参数值可以是以下值。
| 价值 | 意义 |
|---|---|
|
为密钥设置最佳非对称加密填充（OAEP）（PKCS #1 版本 2）参数。 pbData 参数是包含 OAEP 标签的 CRYPT_DATA_BLOB 结构的地址。 此属性仅适用于 RSA 密钥。 |
请注意，不使用以下值：
- KP_ADMIN_PIN
- KP_CMS_KEY_INFO
- KP_INFO
- KP_KEYEXCHANGE_PIN
- KP_PRECOMP_MD5
- KP_PRECOMP_SHA
- KP_PREHASH
- KP_PUB_EX_LEN
- KP_PUB_EX_VAL
- KP_RA
- KP_RB
- KP_ROUNDS
- KP_RP
- KP_SIGNATURE_PIN
- KP_Y
[in] pbData
指向在调用 cryptSetKeyParam 之前要设置的值初始化的缓冲区的指针。 此数据的形式因 dwParam的值而异。
[in] dwFlags
仅在 dwParam KP_ALGID时才使用。 dwFlags 参数用于传入已启用密钥的标志值。 dwFlags 参数可以保存值，如密钥大小和其他标志值，在使用 CryptGenKey生成相同类型的键时允许的值。 有关允许的标志值的信息，请参阅 CryptGenKey。
返回值
如果函数成功，则返回值为非零（TRUE）。
如果函数失败，则返回值为零（FALSE）。 有关扩展错误信息，请调用 GetLastError。
“NTE”开头的错误代码由正在使用的特定 CSP 生成。 下面是一些可能的错误代码。
| 返回代码 | 描述 |
|---|---|
|
CSP 上下文当前正由另一个 进程使用。 |
|
其中一个参数指定无效的句柄。 |
|
其中一个参数包含无效的值。 这通常是无效的指针。 |
|
dwFlags 参数为非零，或者 pbData 缓冲区包含无效的值。 |
|
dwParam 参数指定未知参数。 |
|
找不到创建 hKey 密钥时指定的 CSP 上下文。 |
|
函数以某种意外的方式失败。 |
|
某些 CSP 具有硬编码的 P、Q 和 G 值。 如果是这种情况，则使用 KP_P、KP_Q 和 KP_G dwParam 的值会导致此错误。 |
言论
如果在 PREGEN Diffie-Hellman 或 DSS 密钥上设置了 KP_Q、KP_P 或 KP_X 参数，则密钥长度必须与使用
例子
有关使用此函数的示例，请参阅 示例 C 程序：复制会话密钥。 有关使用此函数的更多代码，请参阅 示例 C 程序：设置和获取会话密钥参数。
要求
| 要求 | 价值 |
|---|---|
| 最低支持的客户端 | Windows XP [仅限桌面应用] |
| 支持的最低服务器 | Windows Server 2003 [仅限桌面应用] |
| 目标平台 | 窗户 |
| 标头 | wincrypt.h |
| 库 | Advapi32.lib |
| DLL | Advapi32.dll |
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈