CryptRetrieveObjectByUrlA-Funktion (wincrypt.h)

Artikel
11/20/2024

Die CryptRetrieveObjectByUrl--Funktion ruft das PKI-Objekt (Public Key Infrastructure) von einem Speicherort ab, der durch eine URL angegeben wird.

Diese Remoteobjekte befinden sich im codierten Format und werden in einem "Kontext"-Formular abgerufen.

Syntax

BOOL CryptRetrieveObjectByUrlA(
  [in]           LPCSTR                   pszUrl,
  [in]           LPCSTR                   pszObjectOid,
  [in]           DWORD                    dwRetrievalFlags,
  [in]           DWORD                    dwTimeout,
  [out]          LPVOID                   *ppvObject,
  [in]           HCRYPTASYNC              hAsyncRetrieve,
  [in, optional] PCRYPT_CREDENTIALS       pCredentials,
  [in, optional] LPVOID                   pvVerify,
  [in]           PCRYPT_RETRIEVE_AUX_INFO pAuxInfo
);

Parameter

[in] pszUrl

Die Adresse eines abzurufenden PKI-Objekts. Die folgenden Schemas werden unterstützt:

ldap (Lightweight Directory Access Protocol)
http
https (Zertifikatsperrliste (CRL) oder Onlinezertifikatstatusprotokoll (OCSP)-Abrufe)
Datei

[in] pszObjectOid

Die Adresse einer mit Null beendeten ANSI-Zeichenfolge, die den abzurufenden Objekttyp identifiziert. Dies kann einer der folgenden Werte sein:

Wert	Bedeutung
NULL- BLOB	Rufen Sie eine oder mehrere Daten BLOBsab. Die codierten Bits werden in einem Array von BLOBs zurückgegeben. ppvObject- ist die Adresse eines CRYPT_BLOB_ARRAY Strukturzeigers, der das BLOB-Array empfängt. Wenn diese Struktur nicht mehr benötigt wird, müssen Sie sie freigeben, indem Sie die Adresse dieser Struktur an die funktion CryptMemFree übergeben.
CONTEXT_OID_CERTIFICATE Zertifikat	Rufen Sie mindestens ein Zertifikat ab. Wenn ein einzelnes Objekt abgerufen wird, ist ppvObject- die Adresse eines CERT_CONTEXT Strukturzeigers, der den Kontext empfängt. Wenn dieser Kontext nicht mehr benötigt wird, müssen Sie ihn freigeben, indem Sie den CERT_CONTEXT Strukturzeiger an die CertFreeCertificateContext-funktion übergeben. Wenn mehrere Objekte abgerufen werden, ist ppvObject- die Adresse einer HCERTSTORE- Variablen, die das Handle eines Speichers empfängt, der die Zertifikate enthält. Wenn dieser Speicher nicht mehr benötigt wird, müssen Sie ihn schließen, indem Sie dieses Handle an die CertCloseStore--Funktion übergeben.
CONTEXT_OID_CRL ZERTIFIKATSPERRLISTE	Abrufen einer oder mehrerer Zertifikatsperrlisten (CRLs). Wenn ein einzelnes Objekt abgerufen wird, ist ppvObject- die Adresse eines CRL_CONTEXT Strukturzeigers, der den Kontext empfängt. Wenn dieser Kontext nicht mehr benötigt wird, müssen Sie ihn freigeben, indem Sie den CRL_CONTEXT Strukturzeiger an die CertFreeCRLContext Funktion übergeben. Wenn mehrere Objekte abgerufen werden, ist ppvObject- die Adresse einer HCERTSTORE- Variable, die das Handle eines Speichers empfängt, der die CRLs enthält. Wenn dieser Speicher nicht mehr benötigt wird, müssen Sie ihn schließen, indem Sie dieses Handle an die CertCloseStore--Funktion übergeben.
CONTEXT_OID_CTL CTL	Abrufen einer oder mehrerer Zertifikatvertrauenslisten (CTLs). Wenn ein einzelnes Objekt abgerufen wird, ist ppvObject- die Adresse eines CTL_CONTEXT Strukturzeigers, der den Kontext empfängt. Wenn dieser Kontext nicht mehr benötigt wird, müssen Sie ihn freigeben, indem Sie den CTL_CONTEXT Strukturzeiger an die CertFreeCTLContext--Funktion übergeben. Wenn mehrere Objekte abgerufen werden, ist ppvObject- die Adresse einer HCERTSTORE Variable, die das Handle eines Speichers empfängt, der die CTLs enthält. Wenn dieser Speicher nicht mehr benötigt wird, müssen Sie ihn schließen, indem Sie dieses Handle an die CertCloseStore--Funktion übergeben.
CONTEXT_OID_PKCS7 PKCS7	ppvObject- ist die Adresse einer HCERTSTORE- Variable, die das Handle eines Speichers empfängt, der die Objekte aus der Nachricht enthält. Wenn dieser Speicher nicht mehr benötigt wird, müssen Sie ihn schließen, indem Sie dieses Handle an die CertCloseStore--Funktion übergeben.
CONTEXT_OID_CAPI2_ANY Funktion bestimmt das entsprechende Element.	ppvObject- ist die Adresse einer HCERTSTORE- Variable, die das Handle eines Speichers empfängt, der die Objekte enthält. Wenn dieser Speicher nicht mehr benötigt wird, müssen Sie ihn schließen, indem Sie dieses Handle an die CertCloseStore--Funktion übergeben.
CONTEXT_OID_OCSP_RESP OCSP-Antwort	ppvObject- ist die Adresse eines Zeigers auf eine CRYPT_BLOB_ARRAY Struktur.

[in] dwRetrievalFlags

Bestimmt, ob die zwischengespeicherte URL oder eine von der Draht-URL abgerufene URL verwendet werden soll. Das Formular, in dem Objekte zurückgegeben werden, wird durch den Wert pszObjectOidbestimmt.

Wert	Bedeutung
CRYPT_AIA_RETRIEVAL	Überprüft den inhalt, der von einer Draht-URL abgerufen wurde, bevor die URL in den Cache geschrieben wird. Der Standardanbieter unterstützt das HTTPS-Protokoll für AIA-Abrufe nicht.
CRYPT_ASYNC_RETRIEVAL	Dieser Wert wird nicht unterstützt.
CRYPT_CACHE_ONLY_RETRIEVAL	Ruft nur die codierten Bits aus dem URL-Cache ab. Verwenden Sie die Verbindung nicht, um die URL abzurufen.
CRYPT_DONT_CACHE_RESULT	Speichert die abgerufenen codierten Bits nicht im URL-Cache. Wenn dieses Flag nicht festgelegt ist, wird die abgerufene URL zwischengespeichert.
CRYPT_HTTP_POST_RETRIEVAL	Verwendet die POST-Methode anstelle der STANDARD-GET-Methode für HTTP-Abrufe. In einer POST-URL werden zusätzliche Binäre Daten und Headerzeichenfolgen an die Basis-URL im folgenden Format angefügt: BaseURL/OptionalURLEscaped&Base64EncodedAdditionalData?OptionalAdditionalHTTPHeaders Das folgende Beispiel zeigt die zusätzlichen Binärdaten, die durch das letzte Schrägstrichzeichen (/) und einen Durch ein Fragezeichen (?) getrennten Inhaltstypheader, das an eine Basis-URL angefügt wird, getrennt sind. `http://ocsp.openvalidation.org/MEIwQDA%2BMDwwOjAJBgUrDgMCGgUABBQdKNEwjytjKBQADcgM61jfflNpyQQUv1NDgnjQnsOA5RtnygUA37lIg6UCAQI%3D?Content-Type: application/ocsp-request` Wenn dieses Flag festgelegt ist, analysiert die funktion CryptRetrieveObjectByUrl die URL mithilfe des letzten Schrägstrichs (/) und der Fragezeichentrennzeichen (?). Die Zeichenfolge, die durch ein Schrägstrich (/) getrennt ist, enthält eine unescaped URL (d. h. eine Nur-Text-URL ohne Escapezeichen oder Escapesequenzen) und Base64-Daten, die in binäre Form decodiert werden, bevor sie an die WinHttpSendRequest als lpOptional Parameter übergeben werden. Die durch ein Fragezeichen (?) getrennte Zeichenfolge wird an die WinHttpSendRequest- als pwszHeaders Parameter übergeben.
CRYPT_LDAP_AREC_EXCLUSIVE_RETRIEVAL	Führt die A-Record-only-DNS-Suche für die angegebene Hostzeichenfolge durch und verhindert die Generierung falscher DNS-Abfragen beim Auflösen von Hostnamen. Dieses Flag sollte beim Übergeben eines Hostnamens im Gegensatz zu einem Domänennamen verwendet werden.
CRYPT_LDAP_INSERT_ENTRY_ATTRIBUTE	Ruft den Eintragsindex und den Attributnamen für jedes LDAP-Objekt ab. Der Anfang jedes zurückgegebenen BLOB enthält die folgende ANSI-Zeichenfolge: "Eintragsindex in dezimaler\0Attributname\0" Wenn dieses Flag festgelegt ist, muss pszObjectOid-NULL- sein, damit ein BLOB zurückgegeben wird. Dieses Kennzeichen gilt nur für das LDAP-Schema.
CRYPT_LDAP_SCOPE_BASE_ONLY_RETRIEVAL	Schlägt fehl, wenn der LDAP-Suchbereich nicht auf die Basis in der URL festgelegt ist. Wird nur mit LDAP verwendet.
CRYPT_LDAP_SIGN_RETRIEVAL	Signiert den gesamten LDAP-Datenverkehr mithilfe des Kerberos-Authentifizierungsprotokolls digital an und von einem Server. Dieses Feature bietet Integrität, die von einigen Anwendungen benötigt wird.
CRYPT_NO_AUTH_RETRIEVAL	Hemmt die automatische Authentifizierungsbehandlung.
CRYPT_NOT_MODIFIED_RETRIEVAL	Aktiviert einen bedingten HTTP-URL-Abruf. Wenn dieses Flag festgelegt ist, wird für einen bedingten Abruf, der HTTP_STATUS_NOT_MODIFIEDzurückgibt, CryptRetrieveObjectByUrlTRUE und ppvObject- auf NULL-festgelegt ist. Wenn pAuxInfo- nicht NULL-ist, wird dwHttpStatusCode- auf HTTP_STATUS_NOT_MODIFIEDfestgelegt. Andernfalls wird ppvObject- für einen erfolgreichen Abruf aktualisiert.
CRYPT_OFFLINE_CHECK_RETRIEVAL	Verfolgt Offlinefehler und Verzögerungen nach, bevor er bei nachfolgenden Abrufen auf den Draht trifft. Dieser Wert ist nur für den Drahtabruf vorgesehen.
CRYPT_PROXY_CACHE_RETRIEVAL	Aktiviert den Proxycacheabruf eines Objekts. Wenn ein Proxycache nicht explizit umgangen wurde, wird fProxyCacheRetrieval auf TRUE- in pAuxInfo-festgelegt. Dieser Wert gilt nur für HTTP-URL-Abrufe.
CRYPT_RETRIEVE_MULTIPLE_OBJECTS	Ruft nach Verfügbarkeit mehrere Objekte ab. Alle Objekte müssen einen homogenen Objekttyp aufweisen, der durch den Wert von pszObjectOidbestimmt wird, es sei denn, der Objektbezeichner (OID)-Wert ist CONTEXT_OID_CAPI2_ANY.
CRYPT_STICKY_CACHE_RETRIEVAL	Markiert die URL als Ausnahme, dass sie aus dem Cache geleert wird. Weitere Informationen finden Sie unter STICKY_CACHE_ENTRY in INTERNET_CACHE_ENTRY_INFO.
CRYPT_VERIFY_CONTEXT_SIGNATURE	Erwirbt die Signaturüberprüfung für den erstellten Kontext. In diesem Fall muss pszObjectOid- nichtNULL- sein und pvVerify auf den Signiererzertifikatkontext verweist.
CRYPT_VERIFY_DATA_HASH	Dieses Flag ist nicht implementiert. Verwenden Sie sie nicht.
CRYPT_WIRE_ONLY_RETRIEVAL	Ruft nur die codierten Bits aus dem Draht ab. Verwendet nicht den URL-Cache.

[in] dwTimeout

Gibt die maximale Anzahl von Millisekunden an, die auf den Abruf warten sollen. Wenn ein Wert von Null angegeben wird, wird für diese Funktion kein Timeout ausgeführt. Dieser Parameter wird nicht verwendet, wenn das URL-Schema file:/// ist.

[out] ppvObject

Die Adresse eines Zeigers auf das zurückgegebene Objekt. Der Rückgabetyp kann einer der unterstützten Typen sein, die in pszObjectOidangezeigt werden.

[in] hAsyncRetrieve

Dieser Parameter ist reserviert und muss auf NULL-festgelegt werden.

[in, optional] pCredentials

Dieser Parameter wird nicht verwendet.

[in, optional] pvVerify

Ein Zeiger auf ein Überprüfungsobjekt. Dieses Objekt ist eine Funktion des dwRetrievalFlags-Parameters. Es kann NULL- sein, um anzugeben, dass der Aufrufer nicht daran interessiert ist, den Zertifikatkontext oder den Index des Signierers abzurufen, wenn dwRetrievalFlags CRYPT_VERIFY_CONTEXT_SIGNATURE ist.

[in] pAuxInfo

Ein optionaler Zeiger auf eine CRYPT_RETRIEVE_AUX_INFO Struktur. Wenn NULL- und wenn das cbSize Element der Struktur festgelegt ist, gibt dieser Parameter den Zeitpunkt des letzten erfolgreichen Drahtabrufs zurück.

Rückgabewert

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

Wenn die Funktion fehlschlägt, ist der Rückgabewert null (FALSE).

Bemerkungen

Der Remoteobjektabruf-Manager macht zwei Anbietermodelle verfügbar. Eines ist das Schemaanbietermodell, das installierbare Protokollanbieter gemäß der Definition des URL-Schemas, d. h. ldap, http, ftp oder datei, zulässt. Der Einstiegspunkt des Schemaanbieters ist identisch mit der CryptRetrieveObjectByUrl--Funktion; Das zurückgegebene *ppvObject ist jedoch immer ein gezähltes Array codierter Bits (eins pro abgerufenes Objekt).

Das zweite Anbietermodell ist das Kontextanbietermodell, das installierbare Ersteller der Kontexthandles (Objekte) basierend auf den abgerufenen codierten Bits ermöglicht. Diese werden basierend auf dem im Aufruf von CryptRetrieveObjectByUrlangegebenen Objektbezeichner (OID) verteilt.

Einzelne PKI-Objekte wie Zertifikate, Vertrauenslisten, Sperrlisten, PKCS #7-Nachrichten und mehrere homogene Objekte können abgerufen werden. Ab Windows Vista mit Service Pack 1 (SP1) und Windows Server 2008 wurden die Sicherheit von "http:" und "ldap:" abgerufen. Diese Funktion unterstützt "http:" und "ldap:"-URL-Schemas sowie neu definierte Schemas.

Windows XP: "ftp:" wird für den Netzwerkabruf nicht unterstützt.

Hinweis Standardmäßig wird "file:" für den Netzwerkabruf nicht unterstützt.

Anmerkung

Der wincrypt.h-Header definiert CryptRetrieveObjectByUrl als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows XP [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Nur Desktop-Apps]
Zielplattform-	Fenster
Header-	wincrypt.h
Library	Cryptnet.lib
DLL-	Cryptnet.dll

Siehe auch

CryptGetObjectUrl-

Freigeben über