共用方式為


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搭配HCRYPTPROVNull來呼叫。 對於 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變數中傳回的控制碼。 如果下列任一項成立,就會收到 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為HWNDCryptSetProvParam 呼叫 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

另請參閱

CRYPT_KEY_PROV_INFO

CertSetCertificateCoNtextProperty

CryptReleaseCoNtext

金鑰產生和 Exchange 函式