CryptAcquireCertificatePrivateKey-Funktion (wincrypt.h)

Artikel
08/27/2023

Die CryptAcquireCertificatePrivateKey-Funktion ruft den privaten Schlüssel für ein Zertifikat ab. Diese Funktion wird verwendet, um Zugriff auf den privaten Schlüssel eines Benutzers zu erhalten, wenn das Zertifikat des Benutzers verfügbar ist, aber das Handle des Schlüsselcontainers des Benutzers nicht verfügbar ist. Diese Funktion kann nur vom Besitzer eines privaten Schlüssels und nicht von einem anderen Benutzer verwendet werden.

Wenn ein CSP-Handle und der Schlüsselcontainer mit dem privaten Schlüssel eines Benutzers verfügbar sind, sollte stattdessen die CryptGetUserKey-Funktion verwendet werden.

Syntax

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
);

Parameter

[in] pCert

Die Adresse einer CERT_CONTEXT Struktur, die den Zertifikatkontext enthält, für den ein privater Schlüssel abgerufen wird.

[in] dwFlags

Ein Satz von Flags, die das Verhalten dieser Funktion ändern. Dies kann null oder eine Kombination aus einem oder mehreren der folgenden Werte sein.

Wert	Bedeutung
CRYPT_ACQUIRE_CACHE_FLAG	Wenn ein Handle bereits abgerufen und zwischengespeichert wurde, wird das gleiche Handle zurückgegeben. Andernfalls wird mithilfe der CERT_KEY_CONTEXT_PROP_ID-Eigenschaft des Zertifikats ein neues Handle abgerufen und zwischengespeichert. Wenn dieses Flag festgelegt ist, empfängt der PfCallerFreeProvOrNCryptKey-ParameterFALSE , und die aufrufende Anwendung darf das Handle nicht freigeben. Das Handle wird freigegeben, wenn der Zertifikatkontext freigegeben wird. Sie müssen jedoch den Zertifikatkontext beibehalten, auf den vom pCert-Parameter verwiesen wird, solange der Schlüssel verwendet wird. Andernfalls schlagen Vorgänge fehl, die auf dem Schlüssel basieren.
CRYPT_ACQUIRE_COMPARE_KEY_FLAG	Der öffentliche Schlüssel im Zertifikat wird mit dem öffentlichen Schlüssel verglichen, der vom Kryptografiedienstanbieter (CSP ) zurückgegeben wird. Wenn die Schlüssel nicht übereinstimmen, schlägt der Erfassungsvorgang fehl, und der letzte Fehlercode wird auf NTE_BAD_PUBLIC_KEY festgelegt. Wenn ein zwischengespeichertes Handle zurückgegeben wird, wird kein Vergleich durchgeführt.
CRYPT_ACQUIRE_NO_HEALING	Diese Funktion versucht nicht, die eigenschaft CERT_KEY_PROV_INFO_PROP_ID im Zertifikatkontext neu zu erstellen, wenn diese Eigenschaft nicht abgerufen werden kann.
CRYPT_ACQUIRE_SILENT_FLAG	Der CSP sollte keine Benutzeroberfläche (UI) für diesen Kontext anzeigen. Wenn der CSP die Benutzeroberfläche anzeigen muss, um zu funktionieren, schlägt der Aufruf fehl, und der NTE_SILENT_CONTEXT Fehlercode wird als letzter Fehler festgelegt.
CRYPT_ACQUIRE_USE_PROV_INFO_FLAG	Verwendet die CERT_KEY_PROV_INFO_PROP_ID-Eigenschaft des Zertifikats, um zu bestimmen, ob zwischengespeichert werden soll. Weitere Informationen zur CERT_KEY_PROV_INFO_PROP_ID-Eigenschaft finden Sie unter CertSetCertificateContextProperty. Diese Funktion verwendet die Zwischenspeicherung nur, wenn während eines vorherigen Aufrufs der dwFlags-Member der CRYPT_KEY_PROV_INFO-StrukturCERT_SET_KEY_CONTEXT_PROP enthalten ist.
CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG	Jede benutzeroberfläche, die vom CSP oder KSP benötigt wird, ist ein untergeordnetes Element der HWND , die im parameter pvParameters angegeben wird. Bei einem CSP-Schlüssel bewirkt die Verwendung dieses Flags, dass die CryptSetProvParam-Funktion mit dem Flag PP_CLIENT_HWND verwendung dieses HWND mit NULL für HCRYPTPROV aufgerufen wird. Bei einem KSP-Schlüssel führt die Verwendung dieses Flags dazu, dass die NCryptSetProperty-Funktion mit dem NCRYPT_WINDOW_HANDLE_PROPERTY-Flag mithilfe des HWND aufgerufen wird. Verwenden Sie dieses Flag nicht mit CRYPT_ACQUIRE_SILENT_FLAG.

Die folgenden Flags bestimmen, welche Technologie zum Abrufen des Schlüssels verwendet wird. Wenn keines dieser Flags vorhanden ist, versucht diese Funktion nur, den Schlüssel mithilfe von CryptoAPI abzurufen.

Windows Server 2003 und Windows XP: Diese Flags werden nicht unterstützt.

Wert	Bedeutung
CRYPT_ACQUIRE_ALLOW_NCRYPT_KEY_FLAG	Diese Funktion versucht, den Schlüssel mithilfe von CryptoAPI abzurufen. Wenn dies fehlschlägt, versucht diese Funktion, den Schlüssel mithilfe der Kryptografie-API: Nächste Generation (CNG) abzurufen. Die Variable pdwKeySpec empfängt das flag CERT_NCRYPT_KEY_SPEC , wenn CNG zum Abrufen des Schlüssels verwendet wird.
CRYPT_ACQUIRE_ONLY_NCRYPT_KEY_FLAG	Diese Funktion versucht nur, den Schlüssel mithilfe von CNG abzurufen, und verwendet nicht CryptoAPI zum Abrufen des Schlüssels. Die Variable pdwKeySpec empfängt das flag CERT_NCRYPT_KEY_SPEC , wenn CNG zum Abrufen des Schlüssels verwendet wird.
CRYPT_ACQUIRE_PREFER_NCRYPT_KEY_FLAG	Diese Funktion versucht, den Schlüssel mithilfe von CNG abzurufen. Wenn dies fehlschlägt, versucht diese Funktion, den Schlüssel mithilfe von CryptoAPI abzurufen. Die Variable pdwKeySpec empfängt das flag CERT_NCRYPT_KEY_SPEC , wenn CNG zum Abrufen des Schlüssels verwendet wird. Hinweis CryptoAPI unterstützt die asymmetrischen Algorithmen CNG Diffie-Hellman oder DSA nicht. CryptoAPI unterstützt nur Diffie-Hellman und öffentliche DSA-Schlüssel über die Legacy-CSPs. Wenn dieses Flag für ein Zertifikat festgelegt ist, das einen öffentlichen Diffie-Hellman- oder DSA-Schlüssel enthält, ändert diese Funktion dieses Flag implizit in CRYPT_ACQUIRE_ALLOW_NCRYPT_KEY_FLAG , um zuerst cryptoAPI zum Abrufen des Schlüssels zu verwenden.

[in, optional] pvParameters

Wenn die CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG festgelegt ist, ist dies die Adresse eines HWND. Wenn der CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG nicht festgelegt ist, muss dieser Parameter NULL sein.

Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Dieser Parameter wurde pvReserved genannt und für die zukünftige Verwendung reserviert und muss NULL sein.

[out] phCryptProvOrNCryptKey

Die Adresse einer HCRYPTPROV_OR_NCRYPT_KEY_HANDLE Variablen, die das Handle des CryptoAPI-Anbieters oder des CNG-Schlüssels empfängt. Wenn die variable pdwKeySpec das flag CERT_NCRYPT_KEY_SPEC empfängt, handelt es sich um ein CNG-Schlüsselhandle vom Typ NCRYPT_KEY_HANDLE; Andernfalls handelt es sich um ein CryptoAPI-Anbieterhandle vom Typ HCRYPTPROV.

Weitere Informationen dazu, wann und wie Sie dieses Handle freigeben, finden Sie in der Beschreibung des pfCallerFreeProvOrNCryptKey-Parameters .

[out] pdwKeySpec

Die Adresse einer DWORD-Variablen , die zusätzliche Informationen zum Schlüssel empfängt. Dies kann einer der folgenden Werte sein.

Wert	Bedeutung
AT_KEYEXCHANGE	Das Schlüsselpaar ist ein Schlüsselaustauschpaar.
AT_SIGNATURE	Das Schlüsselpaar ist ein Signaturpaar.
CERT_NCRYPT_KEY_SPEC	Der Schlüssel ist ein CNG-Schlüssel. Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt.

[out] pfCallerFreeProvOrNCryptKey

Die Adresse einer BOOL-Variablen , die einen Wert empfängt, der angibt, ob der Aufrufer das in der variablen phCryptProvOrNCryptKey zurückgegebene Handle freigeben muss. Dies empfängt FALSE , wenn eine der folgenden Punkte zutrifft:

Der Erwerb oder Vergleich mit öffentlichen Schlüsseln schlägt fehl.
Der dwFlags-Parameter enthält das flag CRYPT_ACQUIRE_CACHE_FLAG .
Der dwFlags-Parameter enthält das flag CRYPT_ACQUIRE_USE_PROV_INFO_FLAG, die Zertifikatkontexteigenschaft wird mit der CRYPT_KEY_PROV_INFO-Struktur auf CERT_KEY_PROV_INFO_PROP_ID festgelegt, und der dwFlags-Member der CRYPT_KEY_PROV_INFO-Struktur ist auf CERT_SET_KEY_CONTEXT_PROP_ID festgelegt.

Wenn diese Variable FALSE empfängt, darf die aufrufende Anwendung das in der Variablen phCryptProvOrNCryptKey zurückgegebene Handle nicht freigeben. Das Handle wird bei der letzten freien Aktion des Zertifikatkontexts freigegeben.

Wenn diese Variable TRUE empfängt, ist der Aufrufer für die Freigabe des in der Variablen phCryptProvOrNCryptKey zurückgegebenen Handles verantwortlich. Wenn die PdwKeySpec-Variable den CERT_NCRYPT_KEY_SPEC Wert empfängt, muss das Handle freigegeben werden, indem es an die NCryptFreeObject-Funktion übergeben wird. Andernfalls wird das Handle freigegeben, indem es an die CryptReleaseContext-Funktion übergeben wird.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich null (TRUE).

Wenn die Funktion fehlschlägt, ist der Rückgabewert 0 (FALSE). Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten. Ein möglicher Fehlercode ist der folgende.

Rückgabecode	Beschreibung
NTE_BAD_PUBLIC_KEY	Der öffentliche Schlüssel im Zertifikat stimmt nicht mit dem öffentlichen Schlüssel überein, der vom CSP zurückgegeben wird. Dieser Fehlercode wird zurückgegeben, wenn die CRYPT_ACQUIRE_COMPARE_KEY_FLAG festgelegt ist und der öffentliche Schlüssel im Zertifikat nicht mit dem öffentlichen Schlüssel übereinstimmt, der vom Kryptografieanbieter zurückgegeben wird.
NTE_SILENT_CONTEXT	Der dwFlags-Parameter enthielt das flag CRYPT_ACQUIRE_SILENT_FLAG , und der CSP konnte einen Vorgang nicht fortsetzen, ohne eine Benutzeroberfläche anzuzeigen.

Hinweise

Wenn CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG festgelegt ist, muss der Aufrufer sicherstellen, dass der HWND gültig ist. Wenn der HWND nicht mehr gültig ist, sollte der Aufrufer für CSP CryptSetProvParam mit dem Flag PP_CLIENT_HWND mit NULL für den HWND und NULL für HCRYPTPROV aufrufen. Für KSP sollte der Aufrufer die NCRYPT_WINDOW_HANDLE_PROPERTY des ncrypt-Schlüssels auf NULL festlegen. Wenn CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG Flag für KSP festgelegt ist, wird die NCRYPT_WINDOW_HANDLE_PROPERTY für den Speicheranbieter und den Schlüssel festgelegt. Wenn bei beiden Aufrufen ein Fehler auftritt, schlägt die Funktion fehl. Wenn nur ein Fehler auftritt, ist die Funktion erfolgreich. Beachten Sie, dass das Festlegen von HWND auf NULLeffektiv HWND aus dem HCRYPTPROV- oder ncrypt-Schlüssel entfernt.

Beispiele

Ein Beispiel, das diese Funktion verwendet, finden Sie unter Beispiel C-Programm: Senden und Empfangen einer signierten und verschlüsselten Nachricht.

Anforderungen


Unterstützte Mindestversion (Client)	Windows XP [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	wincrypt.h
Bibliothek	Crypt32.lib
DLL	Crypt32.dll

Weitere Informationen

CRYPT_KEY_PROV_INFO

CertSetCertificateContextProperty

CryptReleaseContext

Schlüsselgenerierung und Exchange-Funktionen