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.

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.

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

Weitere Informationen

CRYPT_KEY_PROV_INFO

CertSetCertificateContextProperty

CryptReleaseContext

Schlüsselgenerierung und Exchange-Funktionen