NCryptTranslateHandle-Funktion (ncrypt.h)

Artikel
03/04/2024

Die NCryptTranslateHandle-Funktion übersetzt ein CryptoAPI-Handle in ein CNG-Schlüsselhandle.

Syntax

SECURITY_STATUS NCryptTranslateHandle(
  [out, optional] NCRYPT_PROV_HANDLE *phProvider,
  [out]           NCRYPT_KEY_HANDLE  *phKey,
  [in]            HCRYPTPROV         hLegacyProv,
  [in, optional]  HCRYPTKEY          hLegacyKey,
  [in, optional]  DWORD              dwLegacyKeySpec,
  [in]            DWORD              dwFlags
);

Parameter

[out, optional] phProvider

Ein Zeiger auf eine NCRYPT_PROV_HANDLE Variable, die das Handle des CNG-Schlüsselspeicheranbieters empfängt, der den im parameter phKey platzierten CNG-Schlüssel besitzt. Dieser Parameter kann NULL sein, wenn dieses Handle nicht benötigt wird.

[out] phKey

Ein Zeiger auf eine NCRYPT_KEY_HANDLE Variable, die das CNG-Schlüsselhandle empfängt.

[in] hLegacyProv

Das Handle des CryptoAPI-Anbieters, der den zu übersetzenden Schlüssel enthält. Diese Funktion übersetzt den CryptoAPI-Schlüssel, der sich im Container in diesem Anbieter befindet.

[in, optional] hLegacyKey

Das Handle eines CryptoAPI-Schlüssels, der verwendet werden soll, um die Schlüsselspezifikation für den zurückgegebenen Schlüssel zu bestimmen. Dieser Parameter wird ignoriert, wenn der dwLegacyKeySpec-Parameter einen anderen Wert als Null enthält.

Wenn hLegacyKeyNULL und dwLegacyKeySpec null ist, versucht diese Funktion, die Schlüsselspezifikation aus dem hLegacyProv-Handle zu ermitteln.

[in, optional] dwLegacyKeySpec

Gibt die Schlüsselspezifikation für den Schlüssel an. Dies kann einer der folgenden Werte sein.

Wert	Bedeutung
0	Der Schlüssel ist keiner der folgenden Typen.
AT_KEYEXCHANGE 1	Der Schlüssel ist ein Schlüsselaustauschschlüssel.
AT_SIGNATURE 2	Der Schlüssel ist ein Signaturschlüssel.

Wenn hLegacyKeyNULL und dwLegacyKeySpec null ist, versucht diese Funktion, die Schlüsselspezifikation aus dem hLegacyProv-Handle zu ermitteln.

[in] dwFlags

Ein Satz von Flags, die das Verhalten dieser Funktion ändern. Für diese Funktion sind keine Flags definiert.

Rückgabewert

Gibt einen status Code zurück, der den Erfolg oder Fehler der Funktion angibt.

Mögliche Rückgabecodes sind u. a. die folgenden:

Rückgabecode	Beschreibung
ERROR_SUCCESS	Die Funktion war erfolgreich.
NTE_BAD_FLAGS	Der dwFlags-Parameter enthält einen ungültigen Wert.
NTE_INVALID_PARAMETER	Mindestens ein Parameter ist ungültig.
NTE_NO_MEMORY	Ein Speicherbelegungsfehler ist aufgetreten.

Hinweise

Dies ist eine Hilfsfunktion, die Anwendungen und Systemkomponenten, die derzeit die CryptoAPI verwenden, bei einem ordnungsgemäßen Übergang zur Verwendung von CNG unterstützen soll.

Diese Funktion ist nur erfolgreich, wenn ein CNG-Schlüsselspeicheranbieter mit einem Namen oder Alias registriert wird, der mit dem Namen des Kryptografiedienstanbieters (CSP ) identisch ist, auf den der hLegacyProv-Parameter verweist.

Diese Funktion führt die folgenden Schritte aus, um das CSP-Handle in ein CNG-Schlüsselhandle zu übersetzen:

Rufen Sie den Namen des CSP aus dem hLegacyProv-Handle ab.
Öffnen Sie den CNG-Anbieter, dessen Name oder Alias mit dem CSP-Namen identisch ist.
Rufen Sie den Namen des aktuellen Schlüsselcontainers im CSP ab.
Rufen Sie den CryptoAPI-Schlüssel ab, übersetzen Sie ihn in einen CNG-Schlüssel, und geben Sie ihn im parameter phKey zurück.

Ein Dienst darf diese Funktion nicht über seine StartService-Funktion aufrufen. Wenn ein Dienst diese Funktion über seine StartService-Funktion aufruft, kann ein Deadlock auftreten, und der Dienst reagiert möglicherweise nicht mehr.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	ncrypt.h
Bibliothek	Ncrypt.lib
DLL	Ncrypt.dll

Freigeben über