PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET Rückruffunktion (wincrypt.h)

Artikel
08/27/2023

Die PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET-Rückruffunktion ruft ein -Objekt ab. Sie müssen diese Funktion als Teil Ihres benutzerdefinierten Anbieters implementieren. Diese Funktion wird derzeit nur vom Sicherheitspaket Secure Channel (Schannel) aufgerufen.

Syntax

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET PfnCryptObjectLocatorProviderGet;

BOOL PfnCryptObjectLocatorProviderGet(
  [in, optional] LPVOID pPluginContext,
  [in, optional] PCRYPT_DATA_BLOB pIdentifier,
  [in]           DWORD dwNameType,
  [in]           PCERT_NAME_BLOB pNameBlob,
  [out]          PBYTE *ppbContent,
  [out]          DWORD *pcbContent,
  [out]          PCWSTR *ppwszPassword,
  [out]          PCRYPT_DATA_BLOB *ppIdentifier
)
{...}

Parameter

[in, optional] pPluginContext

Zeiger auf einen optionalen Puffer, der von diesem Anbieter definiert und von der funktion PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_INITIALIZE zurückgegeben wird. Der Puffer wird vom Aufrufer nicht geändert. Ihr Anbieter kann die Daten verwenden, um zu bestimmen, welche Aktionen ausgeführt werden sollen, oder um zusätzliche Informationen zu verwalten.

[in, optional] pIdentifier

Zeiger auf eine CRYPTOAPI_BLOB Struktur, die den Objektbezeichner enthält. Dieser Wert sollte beim ersten Aufruf dieser Funktion immer NULL sein.

[in] dwNameType

Das Namensformat des pNameBlob-Parameters . Mögliche Werte sind unten aufgeführt. Die Implementierung dieser Funktion muss in der Lage sein, CRYPT_OBJECT_LOCATOR_SPN_NAME_TYPE zu verarbeiten, die von Schannel übergeben wird.

CRYPT_OBJECT_LOCATOR_SPN_NAME_TYPE (1 (0x1))

CRYPT_OBJECT_LOCATOR_LAST_RESERVED_NAME_TYPE (32 (0x20))

CRYPT_OBJECT_LOCATOR_FIRST_RESERVED_USER_NAME_TYPE (33 (0x21))

CRYPT_OBJECT_LOCATOR_LAST_RESERVED_USER_NAME_TYPE (0x0000FFFF)

[in] pNameBlob

Zeiger auf eine CRYPTOAPI_BLOB Struktur, die den Namen enthält, den die aufrufende Anwendung verwendet, um das Objekt eindeutig zu identifizieren. Ihr Anbieter verwendet diesen Namen, um das angeforderte Objekt zu suchen. Schannel übermittelt derzeit einen DNS-Hostnamen (Domain Name System), der in UTF8 codiert ist, wobei IDN-Namen aus Punycode konvertiert wurden.

[out] ppbContent

Zeiger auf ein Bytearray, das das zurückzugebende Objekt enthält.

[out] pcbContent

Die Größe des Objekts in Bytes, auf das der ppbContent-Parameter verweist.

[out] ppwszPassword

Mit Null beendete Unicode-Zeichenfolge, die ggf. das Kennwort enthält, das zum Verschlüsseln des Objekts verwendet wird. Wenn es sich bei dem Objekt um eine PFX-Datei (Personal Information Exchange) handelt, wird in der Regel ein Kennwort verwendet, um die Verschlüsselung durchzuführen. Dieser Wert kann NULL sein, wenn kein Kennwort erforderlich ist.

[out] ppIdentifier

Adresse, die einen Zeiger auf einen optionalen Bezeichner empfängt, der bei nachfolgenden Aufrufen dieser Funktion und für Änderungsbenachrichtigungen verwendet werden kann. Weitere Informationen finden Sie in den Hinweisen. Wenn Ihr Anbieter diesen Wert auf NULL festlegt, verwendet Schannel intern den pNameBlob-Parameterwert .

Rückgabewert

Wenn die Funktion erfolgreich ist, geben Sie ungleich null (TRUE) zurück.

Wenn die Funktion fehlschlägt, geben Sie null (FALSE) zurück, und geben Sie einen entsprechenden Fehler in der SetLastError-Funktion an. Die meisten Fehler werden unverändert über Schannel übergeben, aber dieses Verhalten ist nicht garantiert. Einige Fehler können anderen Fehlern zugeordnet werden.

Wenn ein Objekt für einen bestimmten DNS-Namen (pNameBlob) oder bezeichner (pIdentifier) nicht zurückgegeben werden kann, geben Sie FALSE zurück, und geben Sie in der SetLastError-FunktionCRYPT_E_OBJECT_LOCATOR_OBJECT_NOT_FOUND an.

Hinweise

Die PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET Rückruffunktion wird derzeit nur vom Sicherheitspaket Secure Channel (Schannel) aufgerufen. Sie können ein Objekt zurückgeben, das eine der folgenden Komponenten kapselt:

Ein PFX-Bytearray (Personal Information Exchange)
Ein Zertifikatspeicher.
Ein generisches BLOB. Dies wird derzeit von Schannel nicht unterstützt.

Wenn diese Funktion zum ersten Mal aufgerufen wird, übermittelt Schannel einen DNS-Hostnamen im pNameBlob-Argument , um den Host anzugeben, für den das Objekt vorgesehen ist. Ihr Anbieter muss den Namen verarbeiten (Abgleichen von Wildcards, Erstellen eines Dateipfads usw.), um zu bestimmen, welches Objekt gefunden werden soll.

Da viele Hostnamen einem Objekt zugeordnet werden können, kann Ihr Anbieter den ppIdentifier-Parameter verwenden, um einen intern definierten Bezeichner zurückzugeben, der in nachfolgenden Aufrufen der Funktionen der Kryptografie-API (CAPI) an den Anbieter verwendet werden kann. Der Anbieter kann dann den Bezeichner verwenden, um das entsprechende Objekt zu finden.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 8 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2012 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	wincrypt.h

Weitere Informationen

CRYPT_OBJECT_LOCATOR_PROVIDER_TABLE

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_INITIALIZE

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_RELEASE

Share via