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 :
- ldap (Lightweight Directory Access Protocol)
- http
- https (récupérations de liste de révocation de certificats (CRL) ou de protocole OCSP (certificat status en ligne) uniquement)
- fichier
[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é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 . |
|
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 . |
|
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 . |
|
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 . |
|
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 de connexion. La forme dans laquelle les objets sont retournés est déterminée par la valeur de pszObjectOid.
| Valeur | Signification |
|---|---|
|
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. |
|
Cette valeur n’est pas prise en charge. |
|
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. |
|
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 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 . |
|
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. |
|
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. |
|
Échoue si l’étendue de recherche LDAP n’est pas définie sur base dans l’URL. Utilisez uniquement avec LDAP. |
|
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. |
|
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 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. |
|
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. |
|
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. |
|
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. |
|
É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. |
|
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. |
|
Cet indicateur n’est pas implémenté. Ne pas l'utiliser. |
|
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.
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 |