CryptGetKeyParam 函数 (wincrypt.h)

  • 项目
重要 此 API 已弃用。 新的和现有的软件应开始使用 加密下一代 API。 Microsoft 可能会在将来的版本中删除此 API。
 
CryptGetKeyParam 函数检索控制密钥操作的数据。 如果使用 Microsoft 加密服务提供程序 ，则此函数或任何其他函数无法获取基本对称密钥材料。

语法

BOOL CryptGetKeyParam(
  [in]      HCRYPTKEY hKey,
  [in]      DWORD     dwParam,
  [out]     BYTE      *pbData,
  [in, out] DWORD     *pdwDataLen,
  [in]      DWORD     dwFlags
);

参数

[in] hKey

正在查询的密钥的句柄。

[in] dwParam

指定要进行的查询的类型。

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

值 含义
KP_ALGID
 检索密钥算法。 pbData 参数是指向ALG_ID值的指针，该值接收创建密钥时指定的算法的标识符。

为 CryptGenKey 函数的 Algid 参数指定AT_KEYEXCHANGE或AT_SIGNATURE时，用于生成密钥的算法标识符取决于所使用的提供程序。 有关详细信息，请参阅 ALG_ID。
KP_BLOCKLEN
 如果会话密钥是由 hKey 参数指定的，请检索密钥密码的块长度。 pbData 参数是指向接收块长度（以位为单位）的 DWORD 值的指针。 对于 流密码，此值始终为零。

如果 hKey 指定了公钥/私钥对，请检索密钥对的加密粒度。 pbData 参数是指向接收加密粒度（以位为单位）的 DWORD 值的指针。 例如， Microsoft 基本加密提供程序 生成 512 位 RSA 密钥对，因此为这些密钥返回值 512。 如果 公钥算法 不支持 加密，则检索到的值未定义。
KP_CERTIFICATE
 pbData 是接收 X.509 证书的缓冲区的地址，该证书已使用 可辨别编码规则 (DER) 进行编码。 证书中的公钥必须与相应的签名或交换密钥匹配。
KP_GET_USE_COUNT
 不使用此值。
KP_KEYLEN
 检索密钥的实际长度。 pbData 参数是指向接收密钥长度（以位为单位）的 DWORD 值的指针。 KP_KEYLEN 可用于获取任何密钥类型的长度。 Microsoft 加密服务提供商 (CSP) CALG_DES返回密钥长度为 64 位，CALG_3DES_112返回 128 位，CALG_3DES返回 192 位。 这些长度不同于枚举将 CryptGetProvParam 函数的 dwParam 值设置为 PP_ENUMALGS 的算法时返回的长度。 此调用返回的长度是密钥的实际大小，包括密钥中包含的奇偶校验位。

支持 CALG_CYLINK_MEK的 Microsoft CSP ALG_ID返回该算法的 64 位。 CALG_CYLINK_MEK 是 40 位密钥，但具有奇偶校验和零键位，使密钥长度为 64 位。
KP_SALT
 检索键的 salt 值 。 pbData 参数是指向 BYTE 数组的指针，该数组以 little endian 形式接收 salt 值。 盐值的大小因使用的 CSP 和算法而异。 Salt 值不适用于 公钥/私钥对。
KP_PERMISSIONS
 检索密钥权限。 pbData 参数是指向接收密钥权限标志的 DWORD 值的指针。

当前定义了以下权限标识符。 键权限可以是零，也可以是以下一个或多个值的组合。

CRYPT_ARCHIVE
允许在密钥句柄的生存期内导出。 仅当已在密钥的内部权限字段中设置此权限时，才能设置此权限。 忽略清除此权限的尝试。
CRYPT_DECRYPT
允许解密。
CRYPT_ENCRYPT
允许加密。
CRYPT_EXPORT
允许导出密钥。
CRYPT_EXPORT_KEY
允许密钥用于导出密钥。
CRYPT_IMPORT_KEY
允许将密钥用于导入密钥。
CRYPT_MAC
允许消息 身份验证代码 (MAC) 与密钥一起使用。
CRYPT_READ
允许读取值。
CRYPT_WRITE
允许设置值。
 

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

值 含义
KP_P
 检索 DSS 键的模质数 P。 pbData 参数是指向以 little-endian 形式接收值的缓冲区的指针。 pdwDataLen 参数包含缓冲区的大小（以字节为单位）。
KP_Q
 检索 DSS 键的模质数 Q。 pbData 参数是指向以 little-endian 形式接收值的缓冲区的指针。 pdwDataLen 参数包含缓冲区的大小（以字节为单位）。
KP_G
 检索 DSS 密钥的生成器 G。 pbData 参数是指向以 little-endian 形式接收值的缓冲区的指针。 pdwDataLen 参数包含缓冲区的大小（以字节为单位）。
 

如果 块密码会话密钥 由 hKey 参数指定，则 dwParam 值也可以设置为以下值之一。

值 含义
KP_EFFECTIVE_KEYLEN
 检索 RC2 密钥的有效密钥长度。 pbData 参数是指向接收有效密钥长度的 DWORD 值的指针。
KP_IV
 检索键的初始化向量。 pbData 参数是指向接收初始化向量的 BYTE 数组的指针。 此数组的大小是块大小（以字节为单位）。 例如，如果块长度为 64 位，则初始化向量由 8 个字节组成。
KP_PADDING
 检索填充模式。 pbData 参数是指向 DWORD 值的指针，该值接收标识密码使用的填充方法的数字标识符。 这可以是以下值之一。
PKCS5_PADDING
指定 PKCS 5 (秒 6.2) 填充方法。
RANDOM_PADDING
填充使用随机数。 Microsoft 提供的 CSP 不支持此填充方法。
ZERO_PADDING
填充使用零。 Microsoft 提供的 CSP 不支持此填充方法。
KP_MODE
 检索 密码模式。 pbData 参数是指向接收密码模式标识符的 DWORD 值的指针。 有关密码模式的详细信息，请参阅 数据加密和解密。

当前定义了以下密码模式标识符。

CRYPT_MODE_CBC
密码模式为 密码块链接。
CRYPT_MODE_CFB
密码模式是 CFB) (密码反馈 。 Microsoft CSP 目前仅支持密码反馈模式下的 8 位反馈。
CRYPT_MODE_ECB
密码模式是 电子代码本。
CRYPT_MODE_OFB
密码模式为 输出反馈 (OFB) 。 Microsoft CSP 目前不支持输出反馈模式。
CRYPT_MODE_CTS
密码模式为 密码文本 窃取模式。
KP_MODE_BITS
 检索要反馈的位数。 pbData 参数是指向 DWORD 值的指针，该值接收在使用 OFB 或 CFB 密码模式时每个周期处理的位数。
 

如果 Diffie-Hellman 算法 或 数字签名算法 (DSA) 键由 hKey 指定，则 dwParam 值也可以设置为以下值。

值 含义
KP_VERIFY_PARAMS
 验证 Diffie-Hellman 算法或 DSA 密钥的参数。 不使用 pbData 参数， pdwDataLen 指向的值接收零。

如果键参数有效，则此函数返回非零值，否则返回零值。
KP_KEYVAL
 不使用此值。

Windows Vista、Windows Server 2003 和 Windows XP： 从 CALG_AGREEDKEY_ANY 类型的导入Diffie-Hellman 算法密钥中检索机密协议值。 pbData 参数是接收机密协议值的缓冲区的地址，采用 little endian 格式。 此缓冲区的长度必须与密钥的长度相同。 dwFlags 参数必须设置为 0xF42A19B6。 此属性只能由在本地系统帐户下运行的线程检索。此属性可用于上面列出的操作系统。 它可能在后续版本中变更或不可用。
 

如果证书是由 hKey 指定的，则 dwParam 值也可以设置为以下值。

值 含义
KP_CERTIFICATE
 包含 DER 编码的 X.509 证书的缓冲区。 不使用 pbData 参数， pdwDataLen 指向的值接收零。

如果键参数有效，则此函数返回非零值，否则返回零值。

[out] pbData

指向接收数据的缓冲区的指针。 此数据的形式取决于 dwParam 的值。

如果此缓冲区的大小未知，可以在运行时检索所需的大小，方法是为此参数传递 NULL 并将 pdwDataLen 指向的值设置为零。 此函数会将缓冲区的所需大小（以字节为单位）放在 pdwDataLen 指向的值中。 有关详细信息，请参阅 检索长度未知的数据。

[in, out] pdwDataLen

指向 DWORD 值的指针，该值在输入时包含 pbData 参数指向的缓冲区的大小（以字节为单位）。 函数返回时， DWORD 值包含缓冲区中存储的字节数。

注意 处理缓冲区中返回的数据时，应用程序必须使用返回的数据的实际大小。 实际大小可能略小于输入时指定的缓冲区的大小。 在输入时，缓冲区大小有时指定得足够大，以确保最大的输出数据适合缓冲区。 输出时，此参数指向的变量会更新，以反映复制到缓冲区的数据的实际大小。
 

[in] dwFlags

此参数保留供将来使用，必须设置为零。

返回值

如果函数成功，该函数将返回非零值。

如果函数失败，则返回零。 有关扩展的错误信息，请调用 GetLastError。

“NTE”开头的错误代码由使用的特定 CSP 生成。 一些可能的错误代码包括以下内容。

返回代码 说明
ERROR_INVALID_HANDLE
 其中一个参数指定无效的句柄。
ERROR_INVALID_PARAMETER
 其中一个参数包含无效的值。 这通常是无效的指针。
ERROR_MORE_DATA
 如果 pbData 参数指定的缓冲区不够大，无法容纳返回的数据，则函数将设置 ERROR_MORE_DATA 代码，并将所需的缓冲区大小（以字节为单位）存储在 pdwDataLen 指向的变量中。
NTE_BAD_FLAGS
 dwFlags 参数为非零。
NTE_BAD_KEY或NTE_NO_KEY
 由 hKey 参数指定的键无效。
NTE_BAD_TYPE
 dwParam 参数指定未知值数字。
NTE_BAD_UID
 找不到在创建密钥时指定的 CSP 上下文 。

要求

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

另请参阅

CryptSetKeyParam

密钥生成和交换函数