Freigeben über


CryptRetrieveObjectByUrlA-Funktion (wincrypt.h)

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

Diese Remoteobjekte haben ein codiertes Format und werden in einer Kontextform 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:

[in] pszObjectOid

Die Adresse einer NULL-beendeten ANSI-Zeichenfolge, die den Typ des abzurufenden Objekts identifiziert. Dies kann einer der folgenden Werte sein.

Wert Bedeutung
NULL
BLOB
Rufen Sie eine oder mehrere Daten-BLOBs ab. 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 CryptMemFree-Funktion ü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
CRL
Rufen Sie mindestens eine Zertifikatsperrliste (Certificate Revocation Lists , CRLs) ab.

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-Variablen , 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
Rufen Sie mindestens eine Zertifikatvertrauensliste (Certificate Trust Lists , CTLs) ab.

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-Variablen , 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-Variablen , 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
Die Funktion bestimmt das geeignete Element.
ppvObject ist die Adresse einer HCERTSTORE-Variablen , 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 URL verwendet werden soll, die von der Draht-URL abgerufen wird. Die Form, in der Objekte zurückgegeben werden, wird durch den Wert von pszObjectOid bestimmt.

Wert Bedeutung
CRYPT_AIA_RETRIEVAL
Überprüft den von einer Draht-URL abgerufenen Inhalt, 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 die codierten Bits nur 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 GET-Standardmethode für HTTP-Abrufe.

In einer POST-URL werden zusätzliche Binärdaten und Headerzeichenfolgen im folgenden Format an die Basis-URL angefügt:

BaseURL/OptionalURLEscaped&Base64EncodedAdditionalData?OptionalAdditionalHTTPHeaders

Das folgende Beispiel zeigt die zusätzlichen Binärdaten, die durch den letzten Schrägstrich (/) getrennt sind, und einen Durch ein Fragezeichen (?) getrennten Content-Type-Header, der an eine Basis-URL angefügt ist.

http://ocsp.openvalidation.org/MEIwQDA%2BMDwwOjAJBgUrDgMCGgUABBQdKNEwjytjKBQADcgM61jfflNpyQQUv1NDgnjQnsOA5RtnygUA37lIg6UCAQI%3D?Content-Type: application/ocsp-request

Wenn dieses Flag festgelegt ist, analysiert die CryptRetrieveObjectByUrl-Funktion die URL mithilfe der Trennzeichen des letzten Schrägstrichs (/) und des Fragezeichens (?). Die Zeichenfolge, die durch einen Schrägstrich (/) getrennt ist, enthält eine URL ohne Escapezeichen (d. h. eine Nur-Text-URL ohne Escapezeichen oder Escapesequenzen) und Base64-Daten, die in binäre Form decodiert werden, bevor sie als lpOptional-Parameter an die WinHttpSendRequest-Funktion übergeben werden. Die durch ein Fragezeichen (?) getrennte Zeichenfolge wird als pwszHeaders-Parameter an die WinHttpSendRequest-Funktion übergeben.

CRYPT_LDAP_AREC_EXCLUSIVE_RETRIEVAL
Führt eine reine A-Record-DNS-Suche für die angegebene Hostzeichenfolge aus, wodurch die Generierung falscher DNS-Abfragen beim Auflösen von Hostnamen verhindert wird. Dieses Flag sollte beim Übergeben eines Hostnamens anstelle eines Domänennamens 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 decimal\0attribut name\0"

Wenn dieses Flag festgelegt ist, muss pszObjectOidNULL sein, damit ein BLOB zurückgegeben wird. Dieses Flag gilt nur für das LDAP-Schema.

CRYPT_LDAP_SCOPE_BASE_ONLY_RETRIEVAL
Tritt ein Fehler auf, wenn der LDAP-Suchbereich nicht auf basis in der URL festgelegt ist. Verwenden Sie nur mit LDAP.
CRYPT_LDAP_SIGN_RETRIEVAL
Signiert den gesamten LDAP-Datenverkehr zu und von einem Server mithilfe des Kerberos-Authentifizierungsprotokolls digital. Dieses Feature stellt die für einige Anwendungen erforderliche Integrität bereit.
CRYPT_NO_AUTH_RETRIEVAL
Verhindert die automatische Authentifizierungsbehandlung.
CRYPT_NOT_MODIFIED_RETRIEVAL
Aktiviert einen bedingten HTTP-URL-Abruf. Wenn dieses Flag festgelegt ist, gibt CryptRetrieveObjectByUrl für einen bedingten Abruf, der HTTP_STATUS_NOT_MODIFIED zurückgibt, TRUE und ppvObject ist auf NULL festgelegt. Wenn pAuxInfo nicht NULL ist, ist dwHttpStatusCode auf HTTP_STATUS_NOT_MODIFIED festgelegt. Andernfalls wird ppvObject für einen erfolgreichen Abruf aktualisiert.
CRYPT_OFFLINE_CHECK_RETRIEVAL
Verfolgt Offlinefehler und Verzögerungen nach, bevor bei nachfolgenden Abrufen die Leitung erreicht wird. 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 in pAuxInfo auf TRUE festgelegt. Dieser Wert gilt nur für HTTP-URL-Abrufe.
CRYPT_RETRIEVE_MULTIPLE_OBJECTS
Ruft mehrere Objekte ab, sofern verfügbar. Alle Objekte müssen einen homogenen Objekttyp aufweisen, der durch den Wert von pszObjectOid bestimmt wird, es sei denn, der Wert des Objektbezeichners (Object Identifier, OID) ist CONTEXT_OID_CAPI2_ANY.
CRYPT_STICKY_CACHE_RETRIEVAL
Markiert die URL als ausgenommen vom Leeren aus dem Cache. Weitere Informationen finden Sie unter STICKY_CACHE_ENTRY in INTERNET_CACHE_ENTRY_INFO.
CRYPT_VERIFY_CONTEXT_SIGNATURE
Ruft die Signaturüberprüfung für den erstellten Kontext ab. In diesem Fall muss pszObjectOid nicht NULL und pvVerify auf den Signaturzertifikatkontext zeigen.
CRYPT_VERIFY_DATA_HASH
Dieses Flag ist nicht implementiert. Verwenden Sie sie nicht.
CRYPT_WIRE_ONLY_RETRIEVAL
Ruft nur die codierten Bits aus der Leitung ab. Verwendet nicht den URL-Cache.

[in] dwTimeout

Gibt die maximale Anzahl von Millisekunden an, die auf den Abruf gewartet werden sollen. Wenn ein Wert von 0 angegeben wird, tritt für diese Funktion kein Timeout auf. 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 pszObjectOid angezeigt 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 Index des Signierers abzurufen, wenn dwRetrievalFlags CRYPT_VERIFY_CONTEXT_SIGNATURE ist.

[in] pAuxInfo

Ein optionaler Zeiger auf eine CRYPT_RETRIEVE_AUX_INFO-Struktur . Wenn nicht NULL und 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 nonzero (TRUE).

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

Hinweise

Der Remoteobjektabruf-Manager macht zwei Anbietermodelle verfügbar. Eine ist das Schemaanbietermodell, das installierbare Protokollanbieter ermöglicht, wie durch das URL-Schema definiert, d. h. LDAP, HTTP, FTP oder Datei. Der Einstiegspunkt des Schemaanbieters ist mit der Funktion CryptRetrieveObjectByUrl identisch. Das zurückgegebene *ppvObject ist jedoch immer ein gezähltes Array von codierten Bits (eines pro abgerufenem 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 Objektbezeichner (Object Identifier, OID) im Aufruf von CryptRetrieveObjectByUrl ausgelöst.

Einzelne PKI-Objekte wie Zertifikate, Vertrauensstellungen, Sperrlisten, PKCS #7-Nachrichten und mehrere homogene Objekte können abgerufen werden. Ab Windows Vista mit Service Pack 1 (SP1) und Windows Server 2008 wurde die Sicherheit der Abrufe "http:" und "ldap:" verschärft. Diese Funktion unterstützt url-Schemas "http:" und "ldap:" 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.
 

Hinweis

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 nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

   
Unterstützte Mindestversion (Client) Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2003 [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile wincrypt.h
Bibliothek Cryptnet.lib
DLL Cryptnet.dll

Weitere Informationen

CryptGetObjectUrl