Función CryptRetrieveObjectByUrlA (wincrypt.h)
La función CryptRetrieveObjectByUrl recupera el objeto de infraestructura de clave pública (PKI) de 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 esquemas siguientes:
- ldap (protocolo ligero de acceso a directorios)
- HTTP
- https (lista de revocación de certificados (CRL) o protocolo de estado de certificado en línea (OCSP) solo recuperaciones)
- 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 datos blobs. 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 único objeto, ppvObject es la dirección de un puntero de estructura de 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 de |
|
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 de 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 de |
|
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 de CTL_CONTEXT que recibe el contexto. Cuando este contexto ya no sea necesario, debe liberarlo pasando el puntero de estructura Si se recuperan varios objetos, ppvObject es la dirección de una variable de 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 de |
|
ppvObject es la dirección de una variable de 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 de |
|
|
|
ppvObject es la dirección de un puntero a una estructura de CRYPT_BLOB_ARRAY. |
[in] dwRetrievalFlags
Determina si se debe 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 caché de direcciones URL. No use la conexión para recuperar la dirección URL. |
|
No almacena los bits codificados recuperados en la 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?opcionalAdditionalHTTPHeaders 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 la última barra diagonal (/) y los delimitadores de signo de interrogación (?). La cadena, que está delimitada por una barra diagonal (/), contiene una dirección URL sin escape (es decir, una dirección URL de texto sin caracteres de escape o secuencias de escape) y los datos de Base64 descodificados en formato binario antes de pasarse al WinHttpSendRequest función como el parámetro lpOptional. La cadena delimitada por un signo de interrogación (?) se pasa a la función winHttpSendRe quest 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 de atributo de cada objeto LDAP. El principio de cada BLOB devuelto contiene la siguiente cadena ANSI: "índice de entrada endecimal \0nombre de 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 golpear el cable 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 ha omitido 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 valor de 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 NULL y pvVerify apunta al contexto del certificado del firmante. |
|
Esta marca no está implementada. No lo use. |
|
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 es 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 usa.
[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 o índice del certificado del firmante si dwRetrievalFlags es CRYPT_VERIFY_CONTEXT_SIGNATURE.
[in] pAuxInfo
Puntero opcional a una estructura de CRYPT_RETRIEVE_AUX_INFO. Si no NULL y si se establece el cbSize miembro de la estructura, este parámetro devuelve la hora de la última recuperación correcta de cables.
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).
Observaciones
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 tal y como se define en 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 el
El segundo modelo de proveedor es el modelo de proveedor de contexto que permite crear creadores instalables de los identificadores de contexto (objetos) en función de 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 ha protegido la seguridad de las recuperaciones "http:" y "ldap:". Esta función admite esquemas de direcciones URL "http:" y "ldap:" así como esquemas recién definidos.
Windows XP: no se admite "ftp:" 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 neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| cliente mínimo admitido | Windows XP [solo aplicaciones de escritorio] |
| servidor mínimo admitido | Windows Server 2003 [solo aplicaciones de escritorio] |
| de la plataforma de destino de |
Windows |
| encabezado de |
wincrypt.h |
| biblioteca de |
Cryptnet.lib |
| DLL de |
Cryptnet.dll |