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:
- ldap (Lightweight Directory Access Protocol)
- http
- https (Nur Abrufe von Zertifikatssperrlisten (Certificate Revocation List, CRL) oder Onlinezertifikat-status-Protokoll (OCSP)
- file
[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 |
|---|---|
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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 |
|---|---|
|
Ü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. |
|
Dieser Wert wird nicht unterstützt. |
|
Ruft die codierten Bits nur aus dem URL-Cache ab. Verwenden Sie die Verbindung nicht, um die URL abzurufen. |
|
Speichert die abgerufenen codierten Bits nicht im URL-Cache. Wenn dieses Flag nicht festgelegt ist, wird die abgerufene URL zwischengespeichert. |
|
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.
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. |
|
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. |
|
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. |
|
Tritt ein Fehler auf, wenn der LDAP-Suchbereich nicht auf basis in der URL festgelegt ist. Verwenden Sie nur mit LDAP. |
|
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. |
|
Verhindert die automatische Authentifizierungsbehandlung. |
|
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. |
|
Verfolgt Offlinefehler und Verzögerungen nach, bevor bei nachfolgenden Abrufen die Leitung erreicht wird. Dieser Wert ist nur für den Drahtabruf vorgesehen. |
|
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. |
|
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. |
|
Markiert die URL als ausgenommen vom Leeren aus dem Cache. Weitere Informationen finden Sie unter STICKY_CACHE_ENTRY in INTERNET_CACHE_ENTRY_INFO. |
|
Ruft die Signaturüberprüfung für den erstellten Kontext ab. In diesem Fall muss pszObjectOid nicht NULL und pvVerify auf den Signaturzertifikatkontext zeigen. |
|
Dieses Flag ist nicht implementiert. Verwenden Sie sie nicht. |
|
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
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 |