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變數中傳回的控制碼。 如果下列任一項成立，就會收到 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為HWND的CryptSetProvParam 呼叫 CryptSetProv，而 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 |
| 程式庫 | Crypt32.lib |
| Dll | Crypt32.dll |
另請參閱
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應