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
一组标志，用于修改此函数的行为。 这可以是零，也可以是以下一个或多个值的组合。
| 值 | 含义 |
|---|---|
|
如果已获取并缓存句柄，则返回同一句柄。 否则，将使用证书的 CERT_KEY_CONTEXT_PROP_ID 属性获取和缓存新句柄。
设置此标志后， pfCallerFreeProvOrNCryptKey 参数接收 FALSE ，并且调用应用程序不得释放句柄。 释放证书上下文时释放句柄;但是，只要密钥正在使用，就必须保留 pCert 参数引用的证书上下文，否则依赖于密钥的操作将失败。 |
|
证书中的 公钥 与 加密服务提供商 (CSP) 返回的公钥进行比较。 如果密钥不匹配，则获取操作将失败，最后一个错误代码设置为 NTE_BAD_PUBLIC_KEY。 如果返回缓存的句柄，则不进行比较。 |
|
如果无法检索此属性，则此函数不会尝试在证书上下文中重新创建 CERT_KEY_PROV_INFO_PROP_ID 属性。 |
|
CSP 不应为此上下文显示任何用户界面 (UI) 。 如果 CSP 必须显示 UI 才能操作，则调用会失败， NTE_SILENT_CONTEXT 错误代码设置为最后一个错误。 |
|
使用证书的 CERT_KEY_PROV_INFO_PROP_ID 属性确定是否应完成缓存。 有关 CERT_KEY_PROV_INFO_PROP_ID 属性的详细信息，请参阅 CertSetCertificateContextProperty。
仅当在上一次调用期间，CRYPT_KEY_PROV_INFO 结构的 dwFlags 成员包含CERT_SET_KEY_CONTEXT_PROP，则此函数才使用缓存。 |
|
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： 不支持这些标志。
[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 变量的地址。 这可以是以下值之一。
| 值 | 含义 |
|---|---|
|
密钥对是密钥交换对。 |
|
密钥对是签名对。 |
|
密钥是 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。
如果此变量收到 TRUE，则调用方负责释放 phCryptProvOrNCryptKey 变量中返回的句柄。 如果 pdwKeySpec 变量接收 CERT_NCRYPT_KEY_SPEC 值，则必须通过将句柄传递给 NCryptFreeObject 函数来释放它;否则，通过将句柄传递给 CryptReleaseContext 函数来释放该句柄。
返回值
如果函数成功，则返回值为非零 (TRUE) 。
如果函数失败，则返回值为零， (FALSE) 。 有关扩展的错误信息，请调用 GetLastError。 一个可能的错误代码如下。
| 返回代码 | 说明 |
|---|---|
|
证书中的公钥与 CSP 返回的公钥不匹配。 如果设置了CRYPT_ACQUIRE_COMPARE_KEY_FLAG，并且证书中的公钥与加密提供程序返回的公钥不匹配，则返回此错误代码。 |
|
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 |