Funzione CryptRetrieveObjectByUrlA (wincrypt.h)
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 |
|---|---|
|
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 . |
|
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 . |
|
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 . |
|
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 . |
|
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 . |
|
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 . |
|
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 |
|---|---|
|
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. |
|
Questo valore non è supportato. |
|
Recupera i bit codificati solo dalla cache degli URL. Non usare la rete per recuperare l'URL. |
|
Non archivia i bit codificati recuperati nella cache degli URL. Se questo flag non è impostato, l'URL recuperato viene memorizzato nella cache. |
|
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.
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 . |
|
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. |
|
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. |
|
Ha esito negativo se l'ambito di ricerca LDAP non è impostato sulla base nell'URL. Usare solo con LDAP. |
|
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. |
|
Impedisce la gestione automatica dell'autenticazione. |
|
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. |
|
Tiene traccia di errori e ritardi offline prima di colpire il filo sui successivi recupero. Questo valore è solo per il recupero di fili. |
|
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. |
|
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. |
|
Contrassegna l'URL come esentato dalla cache. Per altre informazioni, vedere STICKY_CACHE_ENTRY in INTERNET_CACHE_ENTRY_INFO. |
|
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. |
|
Questo flag non viene implementato. Non usarlo. |
|
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
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 |