通过

CryptSetKeyParam 函数 （wincrypt.h）

  • 项目
重要 此 API 已弃用。 新的和现有的软件应开始使用 加密下一代 API。 Microsoft 可能会在将来的版本中删除此 API。
 
CryptSetKeyParam 函数自定义会话密钥操作的各个方面。 此函数设置的值不会保存到内存中，并且只能在单个会话中使用。

Microsoft 基本加密提供程序 不允许为密钥交换或签名密钥设置值;但是，自定义提供程序可以定义可为其键设置的值。

语法

BOOL CryptSetKeyParam(
  [in] HCRYPTKEY  hKey,
  [in] DWORD      dwParam,
  [in] const BYTE *pbData,
  [in] DWORD      dwFlags
);

参数

[in] hKey

要为其设置值的键的句柄。

[in] dwParam

下表包含可以使用的预定义值。

对于所有键类型，此参数可以包含以下值之一。

价值 意义
KP_ALGID
 pbData 指向适当的 ALG_ID。 这在与 Microsoft 基本数字签名标准（DSS）、Diffie-Hellman 加密提供程序或兼容的 CSP 交换会话密钥时使用。 在与 CryptImportKey 函数达成一致后，通过设置其算法类型启用会话密钥以供使用。
KP_CERTIFICATE
 pbData 是缓冲区的地址，该缓冲区包含已使用 可分辨编码规则（DER）编码的 X.509 证书。 证书中的公钥必须与相应的签名或交换密钥匹配。
KP_PERMISSIONS
 pbData 指向指定零个或多个权限标志的 DWORD 值。 有关这些标志的说明，请参阅 CryptGetKeyParam。
KP_SALT
 pbData 指向 BYTE 数组，该数组指定要成为会话键的一部分的新 盐 值。 盐值的大小因使用的 CSP 而异。 设置此值之前，请通过调用 CryptGetKeyParam 函数来确定盐值的大小。 Salt 值用于使会话键更加独特，这使得字典攻击更加困难。 默认情况下，Microsoft基本加密提供程序的盐值为零。
KP_SALT_EX
 pbData 指向包含盐的 CRYPT_INTEGER_BLOB 结构。 有关详细信息，请参阅 指定 Salt 值。
 

如果 数字签名标准（DSS）密钥是由 hKey 参数指定的，则 dwParam 值也可以设置为以下值之一。

价值 意义
KP_G
 pbData 指向 DSS 密钥 BLOB中的生成器 G。 数据采用 CRYPT_INTEGER_BLOB 结构的形式，其中 pbData 成员是值，cbData 成员是值的长度。 该值预期没有标头信息，并且 小端 窗体中。
KP_P
 pbData 指向 DSS 密钥 BLOB 的主要模数 P。 数据采用 CRYPT_INTEGER_BLOB 结构的形式。 pbData 成员是值，cbData 成员是值的长度。 该值预期没有标头信息，并且 小端 窗体中。
KP_Q
 pbData 指向 DSS 密钥 BLOB 的主要 Q。 数据采用 CRYPT_INTEGER_BLOB 结构的形式，其中 pbData 成员是值，cbData 成员是值的长度。 该值预期没有标头信息，并且 小端 窗体中。
KP_X
 设置 P、Q 和 G 值后，可以对 CryptSetKeyParam 函数指定 dwParam 的KP_X值 ，并为 pbData 参数指定 NULL。 这会导致生成 X 值和 Y 值。
 

如果 Diffie-Hellman 算法 或 数字签名算法（DSA）密钥由 hKey指定，则 dwParam 值也可以设置为以下值之一。

价值 意义
KP_CMS_DH_KEY_INFO
 设置导入 Diffie-Hellman 密钥的信息。 pbData 参数是包含要设置的关键信息的 CMS_DH_KEY_INFO 结构的地址。
KP_PUB_PARAMS
 设置 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 值也可以设置为以下值之一。

价值 意义
KP_EFFECTIVE_KEYLEN
 此值类型只能与 RC2 密钥一起使用，并且由于在 Windows 2000 之前的Microsoft增强加密提供程序中实现 CryptSetKeyParam 函数而添加。 在之前的实现中，增强提供程序中的 RC2 键强度为 128 位，但用于将密钥扩展到密钥表中的有效密钥长度仅为 40 位。 这会将算法的强度降低到 40 位。 为了保持向后兼容性，以前的实现将保持不变。 但是，通过在 CryptSetKeyParam 调用中使用KP_EFFECTIVE_KEYLEN，可以将有效密钥长度设置为大于 40 位。 有效密钥长度在 pbData 参数中传递，作为指向具有有效密钥长度值的 DWORD 值的指针。 Microsoft基本加密提供程序上的最小有效密钥长度为 1，最大值为 40。 在Microsoft增强型加密提供程序中，最小值为 1,024， 最大值为 1,024。 在加密或解密密钥之前，必须设置密钥长度。
KP_HIGHEST_VERSION
 设置允许的最高 传输层安全性 （TLS） 版本。 此属性仅适用于 SSL 和 TLS 密钥。 pbData 参数是包含支持的最高 TLS 版本号的 DWORD 变量的地址。
KP_IV
 pbData 指向指定初始化向量的 BYTE 数组。 此数组必须包含 BlockLength/8 元素。 例如，如果块长度为 64 位，则初始化向量由 8 个字节组成。

默认情况下，Microsoft基本加密提供程序的初始化向量设置为零。
KP_KEYVAL
 设置 数据加密标准（DES）密钥的密钥值。 pbData 参数是包含密钥的缓冲区的地址。 此缓冲区的长度必须与密钥长度相同。 此属性仅适用于 DES 键。
KP_PADDING
 设置填充模式。 pbData 参数是指向 DWORD 值的指针，该值接收用于标识 密码使用的 填充 方法的数字标识符。 这可以是以下值之一。
PKCS5_PADDING
指定 PKCS 5 （秒 6.2） 填充方法。
RANDOM_PADDING
填充使用随机数。 Microsoft提供的 CSP 不支持此填充方法。
ZERO_PADDING
填充使用零。 Microsoft提供的 CSP 不支持此填充方法。
KP_MODE
 pbData 指向 DWORD 值，该值指定要使用的 密码 模式。 有关定义的密码模式的列表，请参阅 CryptGetKeyParam。 默认情况下，密码模式设置为Microsoft基本加密提供程序CRYPT_MODE_CBC。
KP_MODE_BITS
 pbData 指向 DWORD 值，该值指示使用 输出反馈（OFB）或 密码反馈（CFB）密码模式时，每个周期处理的位数。 默认情况下，每个周期处理的位数设置为 8，Microsoft基本加密提供程序。
 

如果在 hKey 参数中指定了 RSA 键，则 dwParam 参数值可以是以下值。

价值 意义
KP_OAEP_PARAMS
 为密钥设置最佳非对称加密填充（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 生成。 下面是一些可能的错误代码。

返回代码 描述
ERROR_BUSY
 CSP 上下文当前正由另一个 进程使用。
ERROR_INVALID_HANDLE
 其中一个参数指定无效的句柄。
ERROR_INVALID_PARAMETER
 其中一个参数包含无效的值。 这通常是无效的指针。
NTE_BAD_FLAGS
 dwFlags 参数为非零，或者 pbData 缓冲区包含无效的值。
NTE_BAD_TYPE
 dwParam 参数指定未知参数。
NTE_BAD_UID
 找不到创建 hKey 密钥时指定的 CSP 上下文。
NTE_FAIL
 函数以某种意外的方式失败。
NTE_FIXEDPARAMETER
 某些 CSP 具有硬编码的 P、Q 和 G 值。 如果是这种情况，则使用 KP_P、KP_Q 和 KP_G dwParam 的值会导致此错误。

言论

如果在 PREGEN Diffie-Hellman 或 DSS 密钥上设置了 KP_Q、KP_P 或 KP_X 参数，则密钥长度必须与使用 CryptGenKey创建密钥时使用 dwFlags 参数的上限 16 位 密钥长度 兼容。 如果在 CryptGenKey中未设置密钥长度，则使用默认密钥长度。 如果使用非默认密钥长度来设置 P、Q 或 X，则会创建错误。

例子

有关使用此函数的示例，请参阅 示例 C 程序：复制会话密钥。 有关使用此函数的更多代码，请参阅 示例 C 程序：设置和获取会话密钥参数。

要求

要求 价值
最低支持的客户端 Windows XP [仅限桌面应用]
支持的最低服务器 Windows Server 2003 [仅限桌面应用]
目标平台 窗户
标头 wincrypt.h
库 Advapi32.lib
DLL Advapi32.dll

另请参阅

ALG_ID

CryptGenKey

CryptGetKeyParam

CryptImportKey

密钥生成和 Exchange 函数