Partager via


Fonction CryptRetrieveObjectByUrlA (wincrypt.h)

La fonction CryptRetrieveObjectByUrl récupère l’objet d’infrastructure à clé publique (PKI) à partir d’un emplacement spécifié par une URL.

Ces objets distants sont au format encodé et sont récupérés sous forme de « contexte ».

Syntaxe

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

Paramètres

[in] pszUrl

Adresse d’un objet PKI à récupérer. Les schémas suivants sont pris en charge :

[in] pszObjectOid

Adresse d’une chaîne ANSI terminée par null qui identifie le type d’objet à récupérer. Il peut s’agir de l’une des valeurs suivantes.

Valeur Signification
NULL
BLOB
Récupérer un ou plusieurs objets BLOB de données. Les bits encodés sont retournés dans un tableau de objets BLOB. ppvObject est l’adresse d’un pointeur de structure CRYPT_BLOB_ARRAY qui reçoit le tableau BLOB. Lorsque cette structure n’est plus nécessaire, vous devez la libérer en passant l’adresse de cette structure à la fonction CryptMemFree .
CONTEXT_OID_CERTIFICATE
certificat
Récupérez un ou plusieurs certificats.

Si un seul objet est récupéré, ppvObject est l’adresse d’un pointeur de structure CERT_CONTEXT qui reçoit le contexte. Lorsque ce contexte n’est plus nécessaire, vous devez le libérer en passant le pointeur de structure CERT_CONTEXT à la fonction CertFreeCertificateContext .

Si plusieurs objets sont récupérés, ppvObject est l’adresse d’une variable HCERTSTORE qui reçoit le handle d’un magasin qui contient les certificats. Lorsque ce magasin n’est plus nécessaire, vous devez le fermer en passant ce handle à la fonction CertCloseStore .

CONTEXT_OID_CRL
CRL
Récupérez une ou plusieurs listes de révocation de certificats (CRL).

Si un seul objet est récupéré, ppvObject est l’adresse d’un pointeur de structure CRL_CONTEXT qui reçoit le contexte. Lorsque ce contexte n’est plus nécessaire, vous devez le libérer en passant le pointeur de structure CRL_CONTEXT à la fonction CertFreeCRLContext .

Si plusieurs objets sont récupérés, ppvObject est l’adresse d’une variable HCERTSTORE qui reçoit le handle d’un magasin qui contient les listes de révocation de certificats. Lorsque ce magasin n’est plus nécessaire, vous devez le fermer en passant ce handle à la fonction CertCloseStore .

CONTEXT_OID_CTL
CTL
Récupérez une ou plusieurs listes d’approbation de certificats (CTL).

Si un seul objet est récupéré, ppvObject est l’adresse d’un pointeur de structure CTL_CONTEXT qui reçoit le contexte. Lorsque ce contexte n’est plus nécessaire, vous devez le libérer en passant le pointeur de structure CTL_CONTEXT à la fonction CertFreeCTLContext .

Si plusieurs objets sont récupérés, ppvObject est l’adresse d’une variable HCERTSTORE qui reçoit le handle d’un magasin qui contient les CTL. Lorsque ce magasin n’est plus nécessaire, vous devez le fermer en passant ce handle à la fonction CertCloseStore .

CONTEXT_OID_PKCS7
PKCS7
ppvObject est l’adresse d’une variable HCERTSTORE qui reçoit le handle d’un magasin qui contient les objets du message. Lorsque ce magasin n’est plus nécessaire, vous devez le fermer en passant ce handle à la fonction CertCloseStore .
CONTEXT_OID_CAPI2_ANY
La fonction détermine l’élément approprié
ppvObject est l’adresse d’une variable HCERTSTORE qui reçoit le handle d’un magasin qui contient les objets. Lorsque ce magasin n’est plus nécessaire, vous devez le fermer en passant ce handle à la fonction CertCloseStore .
CONTEXT_OID_OCSP_RESP
Réponse OCSP
ppvObject est l’adresse d’un pointeur vers une structure CRYPT_BLOB_ARRAY .

[in] dwRetrievalFlags

Détermine s’il faut utiliser l’URL mise en cache ou une URL récupérée à partir de l’URL de connexion. La forme dans laquelle les objets sont retournés est déterminée par la valeur de pszObjectOid.

Valeur Signification
CRYPT_AIA_RETRIEVAL
Valide le contenu récupéré par une URL de transmission avant d’écrire l’URL dans le cache.

Le fournisseur par défaut ne prend pas en charge le protocole HTTPS pour les récupérations AIA.

CRYPT_ASYNC_RETRIEVAL
Cette valeur n’est pas prise en charge.
CRYPT_CACHE_ONLY_RETRIEVAL
Récupère les bits encodés à partir du cache d’URL uniquement. N’utilisez pas le câble pour récupérer l’URL.
CRYPT_DONT_CACHE_RESULT
Ne stocke pas les bits encodés récupérés dans le cache d’URL. Si cet indicateur n’est pas défini, l’URL récupérée est mise en cache.
CRYPT_HTTP_POST_RETRIEVAL
Utilise la méthode POST au lieu de la méthode GET par défaut pour les récupérations HTTP.

Dans une URL POST, des données binaires et des chaînes d’en-tête supplémentaires sont ajoutées à l’URL de base au format suivant :

Baseurl/OptionalURLEscaped&Base64EncodedAdditionalData?OptionalAdditionalHTTPHeaders

L’exemple suivant montre les données binaires supplémentaires délimitées par la dernière barre oblique (/) et un en-tête Content-Type délimité par un point d’interrogation ( ?) ajouté à une URL de base.

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

Lorsque cet indicateur est défini, la fonction CryptRetrieveObjectByUrl analyse l’URL à l’aide des derniers délimiteurs de barre oblique (/) et de point d’interrogation ( ?). La chaîne, qui est délimitée par une barre oblique (/), contient une URL sans séquence d’échappement (c’est-à-dire une URL de texte brut sans caractères d’échappement ou séquences d’échappement) et des données en Base64 décodées au format binaire avant d’être passées à la fonction WinHttpSendRequest en tant que paramètre lpOptional . La chaîne délimitée par un point d’interrogation ( ?) est passée à la fonction WinHttpSendRequest en tant que paramètre pwszHeaders .

CRYPT_LDAP_AREC_EXCLUSIVE_RETRIEVAL
Effectue une recherche DNS A-Record-only sur la chaîne d’hôte fournie, empêchant la génération de fausses requêtes DNS lors de la résolution des noms d’hôte. Cet indicateur doit être utilisé lors du passage d’un nom d’hôte par opposition à un nom de domaine.
CRYPT_LDAP_INSERT_ENTRY_ATTRIBUTE
Récupère l’index d’entrée et le nom d’attribut pour chaque objet LDAP. Le début de chaque objet BLOB retourné contient la chaîne ANSI suivante :

« entry index in decimal\0attribute name\0 »

Lorsque cet indicateur est défini, pszObjectOid doit avoir la valeur NULL pour qu’un objet BLOB soit retourné. Cet indicateur s’applique uniquement au schéma ldap.

CRYPT_LDAP_SCOPE_BASE_ONLY_RETRIEVAL
Échoue si l’étendue de recherche LDAP n’est pas définie sur base dans l’URL. Utilisez uniquement avec LDAP.
CRYPT_LDAP_SIGN_RETRIEVAL
Signe numériquement tout le trafic LDAP à destination et en provenance d’un serveur à l’aide du protocole d’authentification Kerberos. Cette fonctionnalité fournit l’intégrité requise par certaines applications.
CRYPT_NO_AUTH_RETRIEVAL
Empêche la gestion automatique de l’authentification.
CRYPT_NOT_MODIFIED_RETRIEVAL
Active une récupération d’URL HTTP conditionnelle. Lorsque cet indicateur est défini, pour une récupération conditionnelle qui retourne HTTP_STATUS_NOT_MODIFIED, CryptRetrieveObjectByUrl retourne TRUE et ppvObject a la valeur NULL. Si pAuxInfo n’a pas la valeur NULL, dwHttpStatusCode est défini sur HTTP_STATUS_NOT_MODIFIED. Sinon, ppvObject est mis à jour pour une récupération réussie.
CRYPT_OFFLINE_CHECK_RETRIEVAL
Effectue le suivi des défaillances et des retards hors connexion avant d’atteindre le câble lors des récupérations ultérieures. Cette valeur est uniquement destinée à la récupération de câbles.
CRYPT_PROXY_CACHE_RETRIEVAL
Active la récupération du cache proxy d’un objet. Si un cache proxy n’a pas été explicitement contourné, fProxyCacheRetrieval a la valeur TRUE dans pAuxInfo. Cette valeur s’applique uniquement aux récupérations d’URL HTTP.
CRYPT_RETRIEVE_MULTIPLE_OBJECTS
Récupère plusieurs objets s’ils sont disponibles. Tous les objets doivent être d’un type d’objet homogène déterminé par la valeur de pszObjectOid, sauf si la valeur de l’identificateur d’objet (OID) est CONTEXT_OID_CAPI2_ANY.
CRYPT_STICKY_CACHE_RETRIEVAL
Étiquette l’URL comme étant exemptée de la vidage du cache. Pour plus d’informations, consultez STICKY_CACHE_ENTRY dans INTERNET_CACHE_ENTRY_INFO.
CRYPT_VERIFY_CONTEXT_SIGNATURE
Obtient la vérification de signature sur le contexte créé. Dans ce cas , pszObjectOid doit être non NULL et pvVerify pointe vers le contexte de certificat du signataire.
CRYPT_VERIFY_DATA_HASH
Cet indicateur n’est pas implémenté. Ne pas l'utiliser.
CRYPT_WIRE_ONLY_RETRIEVAL
Récupère les bits encodés du câble uniquement. N’utilise pas le cache d’URL.

[in] dwTimeout

Spécifie le nombre maximal de millisecondes à attendre pour la récupération. Si une valeur de zéro est spécifiée, cette fonction n’expire pas. Ce paramètre n’est pas utilisé si le schéma d’URL est file:///.

[out] ppvObject

Adresse d’un pointeur vers l’objet retourné. Le type de retour peut être l’un des types pris en charge indiqués dans pszObjectOid.

[in] hAsyncRetrieve

Ce paramètre est réservé et doit être défini sur NULL.

[in, optional] pCredentials

Ce paramètre n'est pas utilisé.

[in, optional] pvVerify

Pointeur vers un objet de vérification. Cet objet est une fonction du paramètre dwRetrievalFlags . La valeur NULL peut indiquer que l’appelant n’est pas intéressé par l’obtention du contexte de certificat ou de l’index du signataire si dwRetrievalFlags est CRYPT_VERIFY_CONTEXT_SIGNATURE.

[in] pAuxInfo

Pointeur facultatif vers une structure de CRYPT_RETRIEVE_AUX_INFO . S’il n’est pas NULL et si le membre cbSize de la structure est défini, ce paramètre retourne l’heure de la dernière récupération de câble réussie.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro (TRUE).

Si la fonction échoue, la valeur de retour est zéro (FALSE).

Remarques

Le gestionnaire de récupération d’objets distants expose deux modèles de fournisseur. L’un est le modèle de fournisseur de schéma qui autorise les fournisseurs de protocole installables tels que définis par le schéma d’URL, c’est-à-dire ldap, http, ftp ou fichier. Le point d’entrée du fournisseur de schéma est identique à la fonction CryptRetrieveObjectByUrl ; toutefois, le *ppvObject retourné est toujours un tableau compté de bits encodés (un par objet récupéré).

Le deuxième modèle de fournisseur est le modèle de fournisseur de contexte qui permet aux créateurs installables des handles de contexte (objets) basés sur les bits encodés récupérés. Elles sont distribuées en fonction de l’identificateur d’objet (OID) spécifié dans l’appel à CryptRetrieveObjectByUrl.

Des objets PKI individuels tels que des certificats, des listes d’approbations, des listes de révocation, des messages PKCS #7 et plusieurs objets homogènes peuvent être récupérés. À compter de Windows Vista avec Service Pack 1 (SP1) et Windows Server 2008, la sécurité des récupérations « http : » et « ldap : » a été renforcée. Cette fonction prend en charge les schémas d’URL « http : » et « ldap : », ainsi que les schémas nouvellement définis.

Windows XP : « ftp : » n’est pas pris en charge pour la récupération réseau.

Note Par défaut, « file : » n’est pas pris en charge pour la récupération réseau.
 

Notes

L’en-tête wincrypt.h définit CryptRetrieveObjectByUrl comme un alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

   
Client minimal pris en charge Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge Windows Server 2003 [applications de bureau uniquement]
Plateforme cible Windows
En-tête wincrypt.h
Bibliothèque Cryptnet.lib
DLL Cryptnet.dll

Voir aussi

CryptGetObjectUrl