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 值的大小。 Salt 值用于使会话键更加独特，这使得字典攻击更加困难。 Microsoft 基本加密提供程序的 salt 值默认为零。
KP_SALT_EX
 pbData 指向包含盐 的CRYPT_INTEGER_BLOB 结构。 有关详细信息，请参阅 指定 Salt 值。
 

如果 数字签名标准 (DSS) 键由 hKey 参数指定，则 dwParam 值也可以设置为以下值之一。

值 含义
KP_G
 pbData 从 DSS 密钥 BLOB 指向生成器 G。 数据采用 CRYPT_INTEGER_BLOB 结构的形式，其中 pbData 成员是值， cbData 成员是值的长度。 该值预期为无标头信息且采用 little-endian 形式。
KP_P
 pbData 指向 DSS 密钥 BLOB 的质模 P。 数据采用 CRYPT_INTEGER_BLOB 结构的形式。 pbData 成员是值，cbData 成员是值的长度。 该值预期为无标头信息且采用 little-endian 形式。
KP_Q
 pbData 指向 DSS 密钥 BLOB 的质 Q。 数据采用 CRYPT_INTEGER_BLOB 结构的形式，其中 pbData 成员是值， cbData 成员是值的长度。 该值预期为无标头信息且采用 little-endian 形式。
KP_X
 设置 P、Q 和 G 值后，可以对 CryptSetKeyParam 函数进行调用，该调用指定 pbData 参数的 dwParam 和 null 的KP_X值。 这会导致生成 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，最大值为 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) 密码模式时每个周期处理的位数。 默认情况下，Microsoft 基本加密提供程序的每个周期处理的位数设置为 8。
 

如果在 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

仅在KP_ALGID dwParam 时才使用。 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 值。 如果是这种情况，则对 dwParam 的值使用 KP_P、KP_Q 和 KP_G 会导致此错误。

注解

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

示例

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

要求

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

另请参阅

ALG_ID

CryptGenKey

CryptGetKeyParam

CryptImportKey

密钥生成和交换函数