Función CryptRetrieveObjectByUrlA (wincrypt.h)
La función CryptRetrieveObjectByUrl recupera el objeto de infraestructura de clave pública (PKI) desde una ubicación especificada por una dirección URL.
Estos objetos remotos están en formato codificado y se recuperan en un formulario de "contexto".
Sintaxis
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
);
Parámetros
[in] pszUrl
Dirección de un objeto PKI que se va a recuperar. Se admiten los siguientes esquemas:
- ldap (Protocolo ligero de acceso a directorios)
- http
- https (solo recuperaciones de listas de revocación de certificados (CRL) o protocolo de estado de certificado en línea (OCSP)
- archivo
[in] pszObjectOid
Dirección de una cadena ANSI terminada en null que identifica el tipo de objeto que se va a recuperar. Puede ser uno de los siguientes valores.
| Valor | Significado |
|---|---|
|
Recupere uno o varios blobs de datos. Los bits codificados se devuelven en una matriz de BLOB. ppvObject es la dirección de un puntero de estructura CRYPT_BLOB_ARRAY que recibe la matriz BLOB. Cuando esta estructura ya no sea necesaria, debe liberarla pasando la dirección de esta estructura a la función CryptMemFree . |
|
Recupere uno o varios certificados.
Si se recupera un solo objeto, ppvObject es la dirección de un puntero de estructura CERT_CONTEXT que recibe el contexto. Cuando este contexto ya no sea necesario, debe liberarlo pasando el puntero de estructura CERT_CONTEXT a la función CertFreeCertificateContext . Si se recuperan varios objetos, ppvObject es la dirección de una variable HCERTSTORE que recibe el identificador de un almacén que contiene los certificados. Cuando este almacén ya no sea necesario, debe cerrarlo pasando este identificador a la función CertCloseStore . |
|
Recupere una o varias listas de revocación de certificados (CRL).
Si se recupera un solo objeto, ppvObject es la dirección de un puntero de estructura CRL_CONTEXT que recibe el contexto. Cuando este contexto ya no sea necesario, debe liberarlo pasando el puntero de estructura CRL_CONTEXT a la función CertFreeCRLContext . Si se recuperan varios objetos, ppvObject es la dirección de una variable HCERTSTORE que recibe el identificador de un almacén que contiene las CRL. Cuando este almacén ya no sea necesario, debe cerrarlo pasando este identificador a la función CertCloseStore . |
|
Recupere una o varias listas de confianza de certificados (CTL).
Si se recupera un solo objeto, ppvObject es la dirección de un puntero de estructura CTL_CONTEXT que recibe el contexto. Cuando este contexto ya no sea necesario, debe liberarlo pasando el puntero de estructura CTL_CONTEXT a la función CertFreeCTLContext . Si se recuperan varios objetos, ppvObject es la dirección de una variable HCERTSTORE que recibe el identificador de un almacén que contiene las CTL. Cuando este almacén ya no sea necesario, debe cerrarlo pasando este identificador a la función CertCloseStore . |
|
ppvObject es la dirección de una variable HCERTSTORE que recibe el identificador de un almacén que contiene los objetos del mensaje. Cuando este almacén ya no sea necesario, debe cerrarlo pasando este identificador a la función CertCloseStore . |
|
ppvObject es la dirección de una variable HCERTSTORE que recibe el identificador de un almacén que contiene los objetos . Cuando este almacén ya no sea necesario, debe cerrarlo pasando este identificador a la función CertCloseStore . |
|
ppvObject es la dirección de un puntero a una estructura de CRYPT_BLOB_ARRAY . |
[in] dwRetrievalFlags
Determina si se va a usar la dirección URL almacenada en caché o una dirección URL recuperada de la dirección URL de conexión. El formulario en el que se devuelven los objetos viene determinado por el valor de pszObjectOid.
| Valor | Significado |
|---|---|
|
Valida el contenido recuperado por una dirección URL de conexión antes de escribir la dirección URL en la memoria caché.
El proveedor predeterminado no admite el protocolo HTTPS para las recuperaciones de AIA. |
|
Este valor no se admite. |
|
Recupera los bits codificados solo de la memoria caché de direcciones URL. No use la conexión para recuperar la dirección URL. |
|
No almacena los bits codificados recuperados en la memoria caché de direcciones URL. Si no se establece esta marca, la dirección URL recuperada se almacena en caché. |
|
Usa el método POST en lugar del método GET predeterminado para las recuperaciones HTTP.
En una dirección URL POST, los datos binarios adicionales y las cadenas de encabezado se anexan a la dirección URL base con el formato siguiente: Baseurl/OptionalURLEscaped&Base64EncodedAdditionalData?OptionalAdditionalHTTPHeaders En el ejemplo siguiente se muestran los datos binarios adicionales delimitados por la última barra diagonal (/) y un encabezado Content-Type delimitado por un signo de interrogación (?) anexado a una dirección URL base.
Cuando se establece esta marca, la función CryptRetrieveObjectByUrl analiza la dirección URL mediante los delimitadores de la última barra diagonal (/) y signo de interrogación (?). La cadena, que está delimitada por una marca de barra diagonal (/), contiene una dirección URL sin escape (es decir, una dirección URL de texto sin formato sin caracteres de escape o secuencias de escape) y los datos base64 descodificados en formato binario antes de pasarse a la función WinHttpSendRequest como el parámetro lpOptional . La cadena delimitada por un signo de interrogación (?) se pasa a la función WinHttpSendRequest como parámetro pwszHeaders . |
|
Realiza una búsqueda DNS de solo registro en la cadena de host proporcionada, lo que impide la generación de consultas DNS falsas al resolver nombres de host. Esta marca se debe usar al pasar un nombre de host en lugar de un nombre de dominio. |
|
Recupera el índice de entrada y el nombre del atributo para cada objeto LDAP. El principio de cada BLOB devuelto contiene la siguiente cadena ANSI: "índice de entrada en decimal\0nombre del atributo\0" Cuando se establece esta marca, pszObjectOid debe ser NULL para que se devuelva un BLOB. Esta marca solo se aplica al esquema ldap. |
|
Se produce un error si el ámbito de búsqueda LDAP no está establecido en base en la dirección URL. Use solo con LDAP. |
|
Firma digitalmente todo el tráfico LDAP hacia y desde un servidor mediante el protocolo de autenticación Kerberos. Esta característica proporciona integridad requerida por algunas aplicaciones. |
|
Impide el control automático de la autenticación. |
|
Habilita una recuperación condicional de la dirección URL HTTP. Cuando se establece esta marca, para una recuperación condicional que devuelve HTTP_STATUS_NOT_MODIFIED, CryptRetrieveObjectByUrl devuelve TRUE y ppvObject se establece en NULL. Si pAuxInfo no es NULL, dwHttpStatusCode se establece en HTTP_STATUS_NOT_MODIFIED. De lo contrario, ppvObject se actualiza para una recuperación correcta. |
|
Realiza un seguimiento de los errores y retrasos sin conexión antes de alcanzar la conexión en las recuperaciones posteriores. Este valor es solo para la recuperación de cables. |
|
Habilita la recuperación de caché de proxy de un objeto. Si no se omite explícitamente una caché de proxy, fProxyCacheRetrieval se establece en TRUE en pAuxInfo. Este valor solo se aplica a las recuperaciones de direcciones URL HTTP. |
|
Recupera varios objetos si están disponibles. Todos los objetos deben ser de un tipo de objeto homogéneo determinado por el valor de pszObjectOid, a menos que el valor del identificador de objeto (OID) sea CONTEXT_OID_CAPI2_ANY. |
|
Etiqueta la dirección URL como exenta de vaciarse de la memoria caché. Para obtener más información, consulte STICKY_CACHE_ENTRY en INTERNET_CACHE_ENTRY_INFO. |
|
Adquiere la comprobación de firma en el contexto creado. En este caso , pszObjectOid debe ser distinto de NULL y pvVerify apunta al contexto del certificado del firmante. |
|
Esta marca no está implementada. No lo utilice. |
|
Recupera los bits codificados solo de la conexión. No usa la caché de direcciones URL. |
[in] dwTimeout
Especifica el número máximo de milisegundos que se van a esperar a la recuperación. Si se especifica un valor de cero, esta función no agota el tiempo de espera. Este parámetro no se usa si el esquema de dirección URL está file:///.
[out] ppvObject
Dirección de un puntero al objeto devuelto. El tipo de valor devuelto puede ser uno de los tipos admitidos que se muestran en pszObjectOid.
[in] hAsyncRetrieve
Este parámetro está reservado y debe establecerse en NULL.
[in, optional] pCredentials
Este parámetro no se utiliza.
[in, optional] pvVerify
Puntero a un objeto de comprobación. Este objeto es una función del parámetro dwRetrievalFlags . Puede ser NULL para indicar que el autor de la llamada no está interesado en obtener el contexto de certificado o el índice del firmante si dwRetrievalFlags está CRYPT_VERIFY_CONTEXT_SIGNATURE.
[in] pAuxInfo
Puntero opcional a una estructura CRYPT_RETRIEVE_AUX_INFO . Si no es NULL y si se establece el miembro cbSize de la estructura, este parámetro devuelve la hora de la última recuperación correcta de la conexión.
Valor devuelto
Si la función se ejecuta correctamente, el valor devuelto es distinto de cero (TRUE).
Si se produce un error en la función, el valor devuelto es cero (FALSE).
Comentarios
El administrador de recuperación de objetos remotos expone dos modelos de proveedor. Uno es el modelo de proveedor de esquemas que permite a los proveedores de protocolos instalables según lo definido por el esquema de dirección URL, es decir, ldap, http, ftp o archivo. El punto de entrada del proveedor de esquemas es el mismo que la función CryptRetrieveObjectByUrl ; sin embargo, el *ppvObject devuelto siempre es una matriz contada de bits codificados (uno por objeto recuperado).
El segundo modelo de proveedor es el modelo de proveedor de contexto que permite crear creadores instalables de los identificadores de contexto (objetos) basados en los bits codificados recuperados. Estos se envían en función del identificador de objeto (OID) especificado en la llamada a CryptRetrieveObjectByUrl.
Se pueden recuperar objetos PKI individuales, como certificados, listas de confianza, listas de revocación, mensajes PKCS #7 y varios objetos homogéneos. A partir de Windows Vista con Service Pack 1 (SP1) y Windows Server 2008, se han protegido la seguridad de las recuperaciones "http:" y "ldap:". Esta función admite esquemas de dirección URL "http:" y "ldap:", así como esquemas recién definidos.
Windows XP: "ftp:" no se admite para la recuperación de red.
Nota:
El encabezado wincrypt.h define CryptRetrieveObjectByUrl como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.
Requisitos
| Cliente mínimo compatible | Windows XP [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows Server 2003 [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | wincrypt.h |
| Library | Cryptnet.lib |
| Archivo DLL | Cryptnet.dll |
Consulte también
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de