CryptAcquireCertificatePrivateKey 函数 (wincrypt.h)

  • 项目

CryptAcquireCertificatePrivateKey 函数获取证书的私钥。 当用户的证书可用但用户密钥容器的句柄不可用时，此函数用于获取对用户 私钥 的访问权限。 此函数只能由私钥的所有者使用，而不能由任何其他用户使用。

如果 CSP 句柄和包含用户私钥的密钥容器可用，则应改用 CryptGetUserKey 函数。

语法

BOOL CryptAcquireCertificatePrivateKey(
  [in]           PCCERT_CONTEXT                  pCert,
  [in]           DWORD                           dwFlags,
  [in, optional] void                            *pvParameters,
  [out]          HCRYPTPROV_OR_NCRYPT_KEY_HANDLE *phCryptProvOrNCryptKey,
  [out]          DWORD                           *pdwKeySpec,
  [out]          BOOL                            *pfCallerFreeProvOrNCryptKey
);

参数

[in] pCert

包含要为其获取私钥的证书上下文的CERT_CONTEXT结构的地址。

[in] dwFlags

一组标志，用于修改此函数的行为。 这可以是零，也可以是以下一个或多个值的组合。

值 含义
CRYPT_ACQUIRE_CACHE_FLAG
 如果已获取并缓存句柄，则返回同一句柄。 否则，将使用证书的 CERT_KEY_CONTEXT_PROP_ID 属性获取和缓存新句柄。

设置此标志后， pfCallerFreeProvOrNCryptKey 参数接收 FALSE ，并且调用应用程序不得释放句柄。 释放证书上下文时释放句柄;但是，只要密钥正在使用，就必须保留 pCert 参数引用的证书上下文，否则依赖于密钥的操作将失败。
CRYPT_ACQUIRE_COMPARE_KEY_FLAG
 证书中的 公钥 与 加密服务提供商 (CSP) 返回的公钥进行比较。 如果密钥不匹配，则获取操作将失败，最后一个错误代码设置为 NTE_BAD_PUBLIC_KEY。 如果返回缓存的句柄，则不进行比较。
CRYPT_ACQUIRE_NO_HEALING
 如果无法检索此属性，则此函数不会尝试在证书上下文中重新创建 CERT_KEY_PROV_INFO_PROP_ID 属性。
CRYPT_ACQUIRE_SILENT_FLAG
 CSP 不应为此上下文显示任何用户界面 (UI) 。 如果 CSP 必须显示 UI 才能操作，则调用会失败， NTE_SILENT_CONTEXT 错误代码设置为最后一个错误。
CRYPT_ACQUIRE_USE_PROV_INFO_FLAG
 使用证书的 CERT_KEY_PROV_INFO_PROP_ID 属性确定是否应完成缓存。 有关 CERT_KEY_PROV_INFO_PROP_ID 属性的详细信息，请参阅 CertSetCertificateContextProperty。

仅当在上一次调用期间，CRYPT_KEY_PROV_INFO 结构的 dwFlags 成员包含CERT_SET_KEY_CONTEXT_PROP，则此函数才使用缓存。
CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG
 CSP 或 KSP 所需的任何 UI 都将是 pvParameters 参数中提供的 HWND 的子级。 对于 CSP 密钥，使用此标志将导致具有标志的 CryptSetProvParam 函数PP_CLIENT_HWND使用此 HWND 调用 HCRYPTPROV 的 NULL。 对于 KSP 密钥，使用此标志将导致使用 HWND 调用具有 NCRYPT_WINDOW_HANDLE_PROPERTY 标志的 NCryptSetProperty 函数。

请勿将此标志用于 CRYPT_ACQUIRE_SILENT_FLAG。
 

以下标志确定使用哪种技术获取密钥。 如果这些标志都不存在，则此函数将仅尝试使用 CryptoAPI 获取密钥。

Windows Server 2003 和 Windows XP： 不支持这些标志。

值 含义
CRYPT_ACQUIRE_ALLOW_NCRYPT_KEY_FLAG
 此函数将尝试使用 CryptoAPI 获取密钥。 如果失败，此函数将尝试使用加密 API 获取密钥：下一代 (CNG) 。

如果使用 CNG 获取密钥， 则 pdwKeySpec 变量接收 CERT_NCRYPT_KEY_SPEC 标志。
CRYPT_ACQUIRE_ONLY_NCRYPT_KEY_FLAG
此函数将仅尝试使用 CNG 获取密钥，而不使用 CryptoAPI 获取密钥。

如果使用 CNG 获取密钥， 则 pdwKeySpec 变量接收 CERT_NCRYPT_KEY_SPEC 标志。
CRYPT_ACQUIRE_PREFER_NCRYPT_KEY_FLAG
 此函数将尝试使用 CNG 获取密钥。 如果失败，此函数将尝试使用 CryptoAPI 获取密钥。

如果使用 CNG 获取密钥， 则 pdwKeySpec 变量接收 CERT_NCRYPT_KEY_SPEC 标志。

注意 CryptoAPI 不支持 CNG Diffie-Hellman 或 DSA 非对称算法。 CryptoAPI 仅支持通过旧版 CSP Diffie-Hellman 和 DSA 公钥。 如果为包含 Diffie-Hellman 或 DSA 公钥的证书设置了此标志，则此函数会将此标志隐式更改为 CRYPT_ACQUIRE_ALLOW_NCRYPT_KEY_FLAG ，以首次尝试使用 CryptoAPI 获取密钥。
 

[in, optional] pvParameters

如果设置了 CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG ，则这是 HWND 的地址。 如果未设置 CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG ，则此参数必须为 NULL。

Windows Server 2008 R2、Windows 7、Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP： 此参数名为 pvReserved 并保留供将来使用，必须为 NULL。

[out] phCryptProvOrNCryptKey

接收 CryptoAPI 提供程序或 CNG 密钥句柄的 HCRYPTPROV_OR_NCRYPT_KEY_HANDLE 变量的地址。 如果 pdwKeySpec 变量接收 CERT_NCRYPT_KEY_SPEC 标志，则这是 类型为 NCRYPT_KEY_HANDLE 的 CNG 键句柄;否则，这是 类型为 HCRYPTPROV 的 CryptoAPI 提供程序句柄。

有关何时以及如何释放此句柄的详细信息，请参阅 pfCallerFreeProvOrNCryptKey 参数的说明。

[out] pdwKeySpec

接收有关密钥的其他信息的 DWORD 变量的地址。 这可以是以下值之一。

值 含义
AT_KEYEXCHANGE
 密钥对是密钥交换对。
AT_SIGNATURE
 密钥对是签名对。
CERT_NCRYPT_KEY_SPEC
 密钥是 CNG 键。

Windows Server 2003 和 Windows XP： 不支持此值。

[out] pfCallerFreeProvOrNCryptKey

BOOL 变量的地址，该变量接收一个值，该值指示调用方是否必须释放 phCryptProvOrNCryptKey 变量中返回的句柄。 如果以下任一情况为 true，则会收到 FALSE ：

  • 公钥获取或比较失败。
  • dwFlags 参数包含 CRYPT_ACQUIRE_CACHE_FLAG 标志。
  • dwFlags 参数包含 CRYPT_ACQUIRE_USE_PROV_INFO_FLAG 标志，证书上下文属性设置为使用 CRYPT_KEY_PROV_INFO 结构CERT_KEY_PROV_INFO_PROP_ID，CRYPT_KEY_PROV_INFO 结构的 dwFlags 成员设置为 CERT_SET_KEY_CONTEXT_PROP_ID。
如果此变量收到 FALSE，则调用应用程序不得释放 phCryptProvOrNCryptKey 变量中返回的句柄。 将在 证书上下文的最后一个免费操作上释放句柄。

如果此变量收到 TRUE，则调用方负责释放 phCryptProvOrNCryptKey 变量中返回的句柄。 如果 pdwKeySpec 变量接收 CERT_NCRYPT_KEY_SPEC 值，则必须通过将句柄传递给 NCryptFreeObject 函数来释放它;否则，通过将句柄传递给 CryptReleaseContext 函数来释放该句柄。

返回值

如果函数成功，则返回值为非零 (TRUE) 。

如果函数失败，则返回值为零， (FALSE) 。 有关扩展的错误信息，请调用 GetLastError。 一个可能的错误代码如下。

返回代码 说明
NTE_BAD_PUBLIC_KEY
 证书中的公钥与 CSP 返回的公钥不匹配。 如果设置了CRYPT_ACQUIRE_COMPARE_KEY_FLAG，并且证书中的公钥与加密提供程序返回的公钥不匹配，则返回此错误代码。
NTE_SILENT_CONTEXT
 dwFlags 参数包含 CRYPT_ACQUIRE_SILENT_FLAG 标志，CSP 无法在不显示用户界面的情况下继续操作。

注解

设置 CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG 时，调用方必须确保 HWND 有效。 如果 HWND 不再有效，则对于 CSP，调用方应使用标志PP_CLIENT_HWND调用 CryptSetProvParam，HWND 为 NULL，HCRYPTPROV 为 NULL。 对于 KSP，调用方应将 ncrypt 密钥的NCRYPT_WINDOW_HANDLE_PROPERTY设置为 NULL。 为 KSP 设置 CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG 标志时，NCRYPT_WINDOW_HANDLE_PROPERTY在存储提供程序和密钥上设置。 如果两个调用都失败，则该函数将失败。 如果只有一个失败，则函数会成功。 请注意，将 HWND 设置为 NULL 会有效地从 HCRYPTPROV 或 ncrypt 键中删除 HWND 。

示例

有关使用此函数的示例，请参阅 示例 C 程序：发送和接收已签名和加密的消息。

要求

   
最低受支持的客户端 Windows XP [桌面应用 | UWP 应用]
最低受支持的服务器 Windows Server 2003 [桌面应用 | UWP 应用]
目标平台 Windows
标头 wincrypt.h
Library Crypt32.lib
DLL Crypt32.dll

另请参阅

CRYPT_KEY_PROV_INFO

CertSetCertificateContextProperty

CryptReleaseContext

密钥生成和交换函数