CryptRetrieveObjectByUrlW, fonction (wincrypt.h)
La fonction CryptRetrieveObjectByUrl récupère l’objet PKI (Public Key Infrastructure) à partir d’un emplacement spécifié par une URL.
Ces objets distants sont au format codé et sont récupérés dans un formulaire « context ».
Syntaxe
BOOL CryptRetrieveObjectByUrlW(
[in] LPCWSTR 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 :
- ldap (Lightweight Directory Access Protocol)
- http
- https (liste de révocation de certificats (CRL) ou protocole d’état de certificat en ligne (OCSP) récupérations uniquement)
- lime
[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 |
|---|---|
|
Récupérez une ou plusieurs 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. |
|
Récupérez un ou plusieurs certificats.
Si un objet unique 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. |
|
Récupérez une ou plusieurs listes de révocation de certificats (CRL).
Si un objet unique 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. |
|
Récupérer une ou plusieurs listes d’approbation de certificats (CTL).
Si un objet unique 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 listes de contrôle d’accès partagé. Lorsque ce magasin n’est plus nécessaire, vous devez le fermer en passant ce handle à la fonction CertCloseStore. |
|
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. |
|
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. |
|
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 filaire. Le formulaire dans lequel les objets sont retournés est déterminé par la valeur de pszObjectOid.
| Valeur | Signification |
|---|---|
|
Valide le contenu récupéré par une URL filaire 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. |
|
Cette valeur n’est pas prise en charge. |
|
Récupère les bits encodés du cache d’URL uniquement. N’utilisez pas le câble pour récupérer l’URL. |
|
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. |
|
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.
Lorsque cet indicateur est défini, la fonction CryptRetrieveObjectByUrl analyse l’URL à l’aide du dernier point oblique (/) et des délimiteurs de point d’interrogation ( ?). La chaîne, qui est délimitée par une barre oblique (/), contient une URL non échapée (autrement dit, une URL de texte brut sans caractères d’échappement ni séquences d’échappement) et des données en base64 décodées sous forme binaire avant d’être passées au WinHttpSendRequest fonction en tant que paramètre lpOptional. La chaîne délimitée par un point d’interrogation ( ?) est transmise à la fonction WinHttpSendRequest en tant que paramètre pwszHeaders. |
|
Effectue une recherche DNS A-Record uniquement sur la chaîne hôte fournie, ce qui empêche la génération de fausses requêtes DNS lors de la résolution des noms d’hôtes. Cet indicateur doit être utilisé lors du passage d’un nom d’hôte par opposition à un nom de domaine. |
|
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 : « index d’entréeendécimale \0 nom d’attribut\0 » Lorsque cet indicateur est défini, pszObjectOid doit être NULL afin qu’un objet BLOB soit retourné. Cet indicateur s’applique uniquement au schéma ldap. |
|
Échoue si l’étendue de recherche LDAP n’est pas définie sur la base dans l’URL. Utiliser uniquement avec LDAP. |
|
Signe numériquement tout le trafic LDAP vers et depuis un serveur à l’aide du protocole d’authentification Kerberos. Cette fonctionnalité fournit l’intégrité requise par certaines applications. |
|
Empêche la gestion automatique de l’authentification. |
|
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 est défini sur NULL. Si pAuxInfo n’est pas NULL, dwHttpStatusCode est défini sur HTTP_STATUS_NOT_MODIFIED. Sinon, ppvObject est mis à jour pour une récupération réussie. |
|
Effectue le suivi des défaillances hors connexion et des retards avant d’atteindre le fil lors des récupérations suivantes. Cette valeur est destinée à la récupération par câble uniquement. |
|
Active la récupération du cache proxy d’un objet. Si un cache proxy n’a pas été contourné explicitement, fProxyCacheRetrieval est défini sur TRUE dans pAuxInfo. Cette valeur s’applique uniquement aux récupérations d’URL HTTP. |
|
Récupère plusieurs objets s’ils sont disponibles. Tous les objets doivent être d’un type d’objet homogène, tel que déterminé par la valeur de |
|
Étiquette l’URL comme étant exemptée d’être vidée du cache. Pour plus d’informations, consultez STICKY_CACHE_ENTRY dans INTERNET_CACHE_ENTRY_INFO. |
|
Acquiert la vérification de signature sur le contexte créé. Dans ce cas, pszObjectOid ne doit pas être NULL et pvVerify pointe vers le contexte du certificat du signataire. |
|
Cet indicateur n’est pas implémenté. Ne l’utilisez pas. |
|
Récupère les bits encodés à partir du fil uniquement. N’utilise pas le cache d’URL. |
[in] dwTimeout
Spécifie le nombre maximal de millisecondes à attendre pour la récupération. Si la valeur 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. Il peut être NULL pour 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 CRYPT_RETRIEVE_AUX_INFO. Si ce n’est pas NULL et si le cbSize membre 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 de retour
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 égale à zéro (FALSE).
Remarques
Le gestionnaire de récupération d’objets distant expose deux modèles de fournisseur. Il s’agit du modèle de fournisseur de schémas 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émas 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) en fonction des bits encodés récupérés. Celles-ci sont distribuées en fonction de l’identificateur d’objet
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 : » ont été renforcées.
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 du réseau.
Note
L’en-tête wincrypt.h définit CryptRetrieveObjectByUrl comme 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.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows XP [applications de bureau uniquement] |
| serveur minimum pris en charge | Windows Server 2003 [applications de bureau uniquement] |
| plateforme cible | Windows |
| d’en-tête | wincrypt.h |
| bibliothèque | Cryptnet.lib |
| DLL | Cryptnet.dll |