CryptAcquireCertificatePrivateKey-Funktion (wincrypt.h)
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 |
|---|---|
|
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. |
|
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. |
|
Diese Funktion versucht nicht, die eigenschaft CERT_KEY_PROV_INFO_PROP_ID im Zertifikatkontext neu zu erstellen, wenn diese Eigenschaft nicht abgerufen werden kann. |
|
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. |
|
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. |
|
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.
[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.
[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 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 |
|---|---|
|
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. |
|
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 |