Funzione CryptRetrieveObjectByUrlA (wincrypt.h)

Articolo
03/15/2023

La funzione CryptRetrieveObjectByUrl recupera l'oggetto PKI (Public Key Infrastructure) da una posizione specificata da un URL.

Questi oggetti remoti sono in formato codificato e vengono recuperati in un formato "contesto".

Sintassi

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
);

Parametri

[in] pszUrl

Indirizzo di un oggetto PKI da recuperare. Sono supportati gli schemi seguenti:

ldap (Lightweight Directory Access Protocol)
http
https (elenco di revoche di certificati (CRL) o solo recupero di certificati online (OCSP)
file

[in] pszObjectOid

Indirizzo di una stringa ANSI con terminazione Null che identifica il tipo di oggetto da recuperare. Può trattarsi di uno dei valori seguenti.

Valore	Significato
NULL BLOB	Recuperare uno o più BLOB di dati. I bit codificati vengono restituiti in una matrice di BLOB. ppvObject è l'indirizzo di un puntatore della struttura CRYPT_BLOB_ARRAY che riceve la matrice BLOB. Quando questa struttura non è più necessaria, è necessario liberarla passando l'indirizzo di questa struttura alla funzione CryptMemFree .
CONTEXT_OID_CERTIFICATE certificato	Recuperare uno o più certificati. Se viene recuperato un singolo oggetto, ppvObject è l'indirizzo di un puntatore alla struttura CERT_CONTEXT che riceve il contesto. Quando questo contesto non è più necessario, è necessario liberarlo passando il puntatore alla struttura CERT_CONTEXT alla funzione CertFreeCertificateContext . Se vengono recuperati più oggetti, ppvObject è l'indirizzo di una variabile HCERTSTORE che riceve l'handle di un archivio che contiene i certificati. Quando questo archivio non è più necessario, è necessario chiuderlo passando questo handle alla funzione CertCloseStore .
CONTEXT_OID_CRL CRL	Recuperare uno o più elenchi di revoche di certificati (CRL). Se viene recuperato un singolo oggetto, ppvObject è l'indirizzo di un puntatore alla struttura CRL_CONTEXT che riceve il contesto. Quando questo contesto non è più necessario, è necessario liberarlo passando il puntatore alla struttura CRL_CONTEXT alla funzione CertFreeCRLContext . Se vengono recuperati più oggetti, ppvObject è l'indirizzo di una variabile HCERTSTORE che riceve l'handle di un archivio che contiene i CRL. Quando questo archivio non è più necessario, è necessario chiuderlo passando questo handle alla funzione CertCloseStore .
CONTEXT_OID_CTL CTL	Recuperare uno o più elenchi di certificati attendibili (CRL). Se viene recuperato un singolo oggetto, ppvObject è l'indirizzo di un puntatore di struttura CTL_CONTEXT che riceve il contesto. Quando questo contesto non è più necessario, è necessario liberarlo passando il puntatore della struttura CTL_CONTEXT alla funzione CertFreeCTLContext . Se vengono recuperati più oggetti, ppvObject è l'indirizzo di una variabile HCERTSTORE che riceve l'handle di un archivio che contiene gli elenchi di scopi consentiti. Quando questo archivio non è più necessario, è necessario chiuderlo passando questo handle alla funzione CertCloseStore .
CONTEXT_OID_PKCS7 PKCS7	ppvObject è l'indirizzo di una variabile HCERTSTORE che riceve l'handle di un archivio che contiene gli oggetti dal messaggio. Quando questo archivio non è più necessario, è necessario chiuderlo passando questo handle alla funzione CertCloseStore .
CONTEXT_OID_CAPI2_ANY La funzione determinerà l'elemento appropriato	ppvObject è l'indirizzo di una variabile HCERTSTORE che riceve l'handle di un archivio che contiene gli oggetti . Quando questo archivio non è più necessario, è necessario chiuderlo passando questo handle alla funzione CertCloseStore .
CONTEXT_OID_OCSP_RESP Risposta OCSP	ppvObject è l'indirizzo di un puntatore a una struttura CRYPT_BLOB_ARRAY .

[in] dwRetrievalFlags

Determina se usare l'URL memorizzato nella cache o un URL recuperato dall'URL di collegamento. Il form in cui vengono restituiti gli oggetti è determinato dal valore di pszObjectOid.

Valore	Significato
CRYPT_AIA_RETRIEVAL	Convalida il contenuto recuperato da un URL di collegamento prima di scrivere l'URL nella cache. Il provider predefinito non supporta il protocollo HTTPS per i recupero AIA.
CRYPT_ASYNC_RETRIEVAL	Questo valore non è supportato.
CRYPT_CACHE_ONLY_RETRIEVAL	Recupera i bit codificati solo dalla cache degli URL. Non usare la rete per recuperare l'URL.
CRYPT_DONT_CACHE_RESULT	Non archivia i bit codificati recuperati nella cache degli URL. Se questo flag non è impostato, l'URL recuperato viene memorizzato nella cache.
CRYPT_HTTP_POST_RETRIEVAL	Usa il metodo POST anziché il metodo GET predefinito per i recupero HTTP. In un URL POST, i dati binari aggiuntivi e le stringhe di intestazione vengono aggiunti all'URL di base nel formato seguente: BaseURL/OptionalURLEscaped&Base64EncodedAdditionalData?OptionalAdditionalHTTPHeaders Nell'esempio seguente vengono illustrati i dati binari aggiuntivi delimitati dall'ultima barra (/) e un'intestazione Content-Type delimitata da un punto interrogativo (?) aggiunto a un URL di base. `http://ocsp.openvalidation.org/MEIwQDA%2BMDwwOjAJBgUrDgMCGgUABBQdKNEwjytjKBQADcgM61jfflNpyQQUv1NDgnjQnsOA5RtnygUA37lIg6UCAQI%3D?Content-Type: application/ocsp-request` Quando questo flag è impostato, la funzione CryptRetrieveObjectByUrl analizza l'URL usando i delimitatori dell'ultima barra (/) e il punto interrogativo (?). La stringa, delimitata da una barra (/), contiene un URL senza caratteri di escape (ovvero un URL di testo normale senza caratteri di escape o sequenze di escape) e i dati Base64 decodificati in formato binario prima di essere passati alla funzione WinHttpSendRequest come parametro lpOptional . La stringa delimitata da un punto interrogativo (?) viene passata alla funzione WinHttpSendRequest come parametro pwszHeaders .
CRYPT_LDAP_AREC_EXCLUSIVE_RETRIEVAL	Esegue la ricerca DNS solo record A nella stringa host fornita, impedendo la generazione di false query DNS durante la risoluzione dei nomi host. Questo flag deve essere usato quando si passa un nome host anziché un nome di dominio.
CRYPT_LDAP_INSERT_ENTRY_ATTRIBUTE	Recupera l'indice di voce e il nome dell'attributo per ogni oggetto LDAP. L'inizio di ogni BLOB restituito contiene la stringa ANSI seguente: "indice voce in decimal\0nome attributo\0" Quando questo flag è impostato, pszObjectOid deve essere NULL in modo che venga restituito un BLOB. Questo flag si applica solo allo schema ldap.
CRYPT_LDAP_SCOPE_BASE_ONLY_RETRIEVAL	Ha esito negativo se l'ambito di ricerca LDAP non è impostato sulla base nell'URL. Usare solo con LDAP.
CRYPT_LDAP_SIGN_RETRIEVAL	Firma digitalmente tutto il traffico LDAP da e verso un server usando il protocollo di autenticazione Kerberos. Questa funzionalità fornisce l'integrità richiesta da alcune applicazioni.
CRYPT_NO_AUTH_RETRIEVAL	Impedisce la gestione automatica dell'autenticazione.
CRYPT_NOT_MODIFIED_RETRIEVAL	Abilita il recupero di un URL HTTP condizionale. Quando questo flag è impostato, per un recupero condizionale che restituisce HTTP_STATUS_NOT_MODIFIED, CryptRetrieveObjectByUrl restituisce TRUE e ppvObject è impostato su NULL. Se pAuxInfo non è NULL, dwHttpStatusCode è impostato su HTTP_STATUS_NOT_MODIFIED. In caso contrario, ppvObject viene aggiornato per un recupero riuscito.
CRYPT_OFFLINE_CHECK_RETRIEVAL	Tiene traccia di errori e ritardi offline prima di colpire il filo sui successivi recupero. Questo valore è solo per il recupero di fili.
CRYPT_PROXY_CACHE_RETRIEVAL	Abilita il recupero della cache proxy di un oggetto. Se una cache proxy non è stata ignorata in modo esplicito, fProxyCacheRetrieval è impostata su TRUE in pAuxInfo. Questo valore si applica solo ai recupero dell'URL HTTP.
CRYPT_RETRIEVE_MULTIPLE_OBJECTS	Recupera più oggetti se disponibili. Tutti gli oggetti devono essere di un tipo di oggetto omogeneo, come determinato dal valore pszObjectOid, a meno che il valore dell'identificatore dell'oggetto (OID) non sia CONTEXT_OID_CAPI2_ANY.
CRYPT_STICKY_CACHE_RETRIEVAL	Contrassegna l'URL come esentato dalla cache. Per altre informazioni, vedere STICKY_CACHE_ENTRY in INTERNET_CACHE_ENTRY_INFO.
CRYPT_VERIFY_CONTEXT_SIGNATURE	Acquisisce la verifica della firma nel contesto creato. In questo caso pszObjectOid deve essere diverso da NULL e pvVerify punta al contesto del certificato di firma.
CRYPT_VERIFY_DATA_HASH	Questo flag non viene implementato. Non usarlo.
CRYPT_WIRE_ONLY_RETRIEVAL	Recupera i bit codificati solo dal filo. Non usa la cache DEGLI URL.

[in] dwTimeout

Specifica il numero massimo di millisecondi da attendere il recupero. Se viene specificato un valore pari a zero, questa funzione non timeout. Questo parametro non viene usato se lo schema URL è file:///.

[out] ppvObject

Indirizzo di un puntatore all'oggetto restituito. Il tipo restituito può essere uno dei tipi supportati visualizzati in pszObjectOid.

[in] hAsyncRetrieve

Questo parametro è riservato e deve essere impostato su NULL.

[in, optional] pCredentials

Questo parametro non viene usato.

[in, optional] pvVerify

Puntatore a un oggetto di verifica. Questo oggetto è una funzione del parametro dwRetrievalFlags . Può essere NULL per indicare che il chiamante non è interessato a ottenere il contesto del certificato o l'indice del firmatario se dwRetrievalFlags è CRYPT_VERIFY_CONTEXT_SIGNATURE.

[in] pAuxInfo

Puntatore facoltativo a una struttura CRYPT_RETRIEVE_AUX_INFO . Se non è NULL e se il membro cbSize della struttura è impostato, questo parametro restituisce l'ora dell'ultimo recupero del filo riuscito.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero (TRUE).

Se la funzione ha esito negativo, il valore restituito è zero (FALSE).

Commenti

Gestione recupero oggetti remoti espone due modelli di provider. Uno è il modello provider di schemi che consente i provider di protocolli installabili come definito dallo schema URL, ovvero ldap, http, ftp o file. Il punto di ingresso del provider di schemi è lo stesso della funzione CryptRetrieveObjectByUrl ; tuttavia, il valore *ppvObject restituito è sempre una matrice conteggiata di bit codificati (uno per oggetto recuperato).

Il secondo modello di provider è il modello del provider di contesto che consente di creare creatori installabili degli handle di contesto (oggetti) in base ai bit codificati recuperati. Questi vengono inviati in base all'identificatore dell'oggetto (OID) specificato nella chiamata a CryptRetrieveObjectByUrl.

Singoli oggetti PKI, ad esempio certificati, elenchi di attendibilità, elenchi di revoche, messaggi PKCS #7 e più oggetti omogenei possono essere recuperati. A partire da Windows Vista con Service Pack 1 (SP1) e Windows Server 2008, la sicurezza di "http:" e "ldap:" è stata avanzata. Questa funzione supporta schemi "http:" e "ldap:" URL, nonché schemi appena definiti.

Windows XP: "ftp:" non è supportato per il recupero di rete.

Nota Per impostazione predefinita, "file:" non è supportato per il recupero di rete.

Nota

L'intestazione wincrypt.h definisce CryptRetrieveObjectByUrl come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti


Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	wincrypt.h
Libreria	Cryptnet.lib
DLL	Cryptnet.dll

Vedi anche

CryptGetObjectUrl

Condividi tramite