Función CertGetCertificateChain (wincrypt.h)
La función CertGetCertificateChain crea un contexto de cadena de certificados a partir de un certificado final y vuelve, si es posible, a un certificado raíz de confianza.
Sintaxis
BOOL CertGetCertificateChain(
[in, optional] HCERTCHAINENGINE hChainEngine,
[in] PCCERT_CONTEXT pCertContext,
[in, optional] LPFILETIME pTime,
[in] HCERTSTORE hAdditionalStore,
[in] PCERT_CHAIN_PARA pChainPara,
[in] DWORD dwFlags,
[in] LPVOID pvReserved,
[out] PCCERT_CHAIN_CONTEXT *ppChainContext
);
Parámetros
[in, optional] hChainEngine
Identificador del motor de cadena (espacio de nombres y caché) que se va a usar. Si hChainEngine es NULL, se usa el motor de cadena predeterminado, HCCE_CURRENT_USER. Este parámetro se puede establecer en HCCE_LOCAL_MACHINE.
[in] pCertContext
Puntero al CERT_CONTEXT del certificado final, el certificado para el que se está compilando una cadena. Este contexto de certificado será el elemento de índice cero de la primera cadena simple.
[in, optional] pTime
Puntero a una variable FILETIME que indica la hora para la que se va a validar la cadena. Tenga en cuenta que el tiempo no afecta a la lista de confianza, la revocación o la comprobación del almacén raíz. La hora actual del sistema se usa si se pasa NULL a este parámetro. La confianza en un certificado determinado que es una raíz de confianza se basa en el estado actual del almacén raíz y no en el estado del almacén raíz en un momento pasado por este parámetro. Para la revocación, una lista de revocación de certificados (CRL), en sí misma, debe ser válida en el momento actual. El valor de este parámetro se usa para determinar si se ha revocado un certificado enumerado en una CRL.
[in] hAdditionalStore
Identificador de cualquier almacén adicional para buscar certificados auxiliares y listas de confianza de certificados (CTL). Este parámetro puede ser NULL si no se va a buscar ningún almacén adicional.
[in] pChainPara
Puntero a una estructura de CERT_CHAIN_PARA que incluye parámetros de creación de cadenas.
[in] dwFlags
Marca los valores que indican el procesamiento especial. Este parámetro puede ser una combinación de una o varias de las marcas siguientes.
| Valor | Significado |
|---|---|
|
Cuando se establece esta marca, el certificado final se almacena en caché, lo que podría acelerar el proceso de creación de cadenas. De forma predeterminada, el certificado final no se almacena en caché y tendría que comprobarse cada vez que se compila una cadena para él. |
|
La comprobación de revocación solo tiene acceso a las direcciones URL almacenadas en caché. |
|
Esta marca se usa internamente durante la creación de cadenas para un certificado de firmante del protocolo de estado de certificado en línea (OCSP) para evitar comprobaciones de revocación cíclicas. Durante la creación de la cadena, si la respuesta OCSP está firmada por un firmante ocSP independiente, entonces, además de la compilación de la cadena original, hay una segunda cadena creada para el propio certificado del firmante ocSP. Esta marca se usa durante esta segunda compilación de cadena para impedir un certificado de firmante OCSP independiente recursivo. Si el certificado de firmante contiene la extensión szOID_PKIX_OCSP_NOCHECK , se omite la comprobación de revocación para el certificado del firmante hoja. Se permiten las comprobaciones OCSP y CRL.
Windows Server 2003 y Windows XP: Este valor no se admite. |
|
Usa solo direcciones URL almacenadas en caché en la creación de una cadena de certificados. Internet e intranet no se buscan objetos basados en direcciones URL.
Nota Esta marca no es aplicable a la comprobación de revocación. Establezca CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY para usar solo las direcciones URL almacenadas en caché para la comprobación de revocación. |
|
Por motivos de rendimiento, el segundo paso de la construcción de la cadena solo considera posibles rutas de acceso de cadena que tienen una calidad mayor o igual que la calidad más alta determinada durante el primer paso. El primer paso solo considera la firma válida, la cadena completa y las raíces de confianza para calcular la calidad de la cadena. Esta marca se puede establecer para deshabilitar esta optimización y considerar todas las posibles rutas de acceso de cadena durante el segundo paso. |
|
Esta marca no se admite. Los certificados del almacén "Mi" nunca se consideran para la confianza del mismo nivel. |
|
Los certificados de entidad final en el almacén "TrustedPeople" son de confianza sin realizar ninguna creación de cadena. Esta función no establece los bits de miembro CERT_TRUST_IS_PARTIAL_CHAIN o CERT_TRUST_IS_UNTRUSTED_ROOTdwErrorStatus del parámetro ppChainContext . Windows Server 2003 Windows XP : Esta marca no se admite. |
|
Si se establece esta marca, se indica que el autor de la llamada desea participar en comprobaciones de firma débiles.
Esta marca está disponible en la actualización de acumulación para cada sistema operativo a partir de Windows 7 y Windows Server 2008 R2. |
|
El valor predeterminado es devolver solo la ruta de acceso de la cadena de calidad más alta. Al establecer esta marca, se devolverán las cadenas de menor calidad. Estos se devuelven en los campos cLowerQualityChainContext y rgpLowerQualityChainContext del contexto de cadena. |
|
Al establecer esta marca, se impide la actualización automática de raíces de terceros del servidor web de Windows Update. |
|
Al establecer CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT y también se especifica un valor para el miembro dwUrlRetrievalTimeout de la estructura CERT_CHAIN_PARA , el valor especificado en dwUrlRetrievalTimeout representa el tiempo de espera acumulado en todas las recuperaciones de direcciones URL de revocación.
Si establece CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT pero no especifica un valor dwUrlRetrievalTimeout , el tiempo de espera acumulado máximo se establece, de forma predeterminada, en 20 segundos. Cada dirección URL probada expirará después de que se haya superado la mitad del saldo acumulado restante. Es decir, la primera dirección URL agota el tiempo de espera después de 10 segundos, el segundo después de 5 segundos, el tercero después de 2,5 segundos y así sucesivamente hasta que una dirección URL se realiza correctamente, 20 segundos o no hay más direcciones URL para probar. Si no establece CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT, a cada dirección URL de revocación de la cadena se le asigna un tiempo de espera máximo igual al valor especificado en dwUrlRetrievalTimeout. Si no especifica un valor para el miembro dwUrlRetrievalTimeout , a cada dirección URL de revocación se le asigna un tiempo de espera predeterminado máximo de 15 segundos. Si ninguna dirección URL se realiza correctamente, el valor máximo de tiempo de espera acumulado es de 15 segundos multiplicado por el número de direcciones URL de la cadena. Puede establecer los valores predeterminados mediante directiva de grupo. |
|
Cuando se establece esta marca, pTime se usa como tiempo de marca de tiempo para determinar si el certificado final era válido. La hora actual también se puede usar para determinar si el certificado final permanece válido. Todas las demás entidades de certificación (CA) y los certificados raíz de la cadena se comprueban con la hora actual y no con pTime. |
|
Al establecer esta marca, se desactivan explícitamente las recuperaciones de Acceso a la información de autoridad (AIA). |
También puede establecer las siguientes marcas de revocación, pero solo se puede establecer una marca de este grupo a la vez.
[in] pvReserved
Este parámetro está reservado y debe ser NULL.
[out] ppChainContext
Dirección de un puntero al contexto de cadena creado. Cuando haya terminado de usar el contexto de cadena, libere la cadena llamando a la función CertFreeCertificateChain .
Valor devuelto
Si la función se ejecuta correctamente, la función devuelve un valor distinto de cero (TRUE).
Si se produce un error en la función, devuelve cero (FALSE). Para obtener información de error extendida, llame a GetLastError.
Comentarios
Cuando una aplicación solicita una cadena de certificados, la estructura devuelta se forma de un CERT_CHAIN_CONTEXT. Este contexto contiene una matriz de estructuras de CERT_SIMPLE_CHAIN donde cada cadena simple pasa de un certificado final a un certificado autofirmado. El contexto de la cadena conecta cadenas simples a través de listas de confianza. Cada cadena simple contiene la cadena de certificados, información de confianza resumida sobre la cadena e información de confianza sobre cada elemento de certificado de la cadena.
Los siguientes comentarios se aplican a la comprobación de firmas seguras:
- Puede habilitar la comprobación de firmas seguras para esta función estableciendo el miembro pStrongSignPara de la estructura CERT_CHAIN_PARA a la que apunta el parámetro pChainPara .
- Si se encuentra un certificado sin una firma segura en la cadena, los errores de CERT_TRUST_HAS_WEAK_SIGNATURE y CERT_TRUST_IS_NOT_SIGNATURE_VALID se establecen en el campo dwErrorStatus de la estructura CERT_TRUST_STATUS . El parámetro ppChainContext apunta a una estructura de CERT_CHAIN_CONTEXT que, a su vez, apunta a la estructura CERT_TRUST_STATUS .
- Si la cadena tiene una firma segura, se comprueba la clave pública del certificado final para determinar si cumple los requisitos mínimos de longitud de clave pública para una firma segura. Si no se cumple la condición, el CERT_TRUST_HAS_WEAK_SIGNATURE y los errores de CERT_TRUST_IS_NOT_SIGNATURE_VALID se establecen en el campo dwErrorStatus de la estructura CERT_TRUST_STATUS . Para deshabilitar la comprobación de la longitud de la clave, establezca el valor CERT_CHAIN_STRONG_SIGN_DISABLE_END_CHECK_FLAG en el miembro dwStrongSignFlags de la estructura CERT_CHAIN_PARA apuntada por el parámetro pChainPara .
- Si las marcas de CERT_STRONG_SIGN_ENABLE_CRL_CHECK o CERT_STRONG_SIGN_ENABLE_OCSP_CHECK se establecen en la estructura de CERT_STRONG_SIGN_SERIALIZED_INFO y se encuentra una respuesta CRL o OCSP sin una firma segura, la respuesta CRL o OCSP se tratará como sin conexión. Es decir, los errores CERT_TRUST_IS_OFFLINE_REVOCATION y CERT_TRUST_REVOCATION_STATUS_UNKNOWN se establecen en el campo dwErrorStatus de la estructura CERT_TRUST_STATUS . Además, el miembro dwRevocationResult de la estructura CERT_REVOCATION_INFO se establece en NTE_BAD_ALGID.
Ejemplos
Para obtener un ejemplo que use esta función, vea Ejemplo de programa C: Creación de una cadena de certificados.
Requisitos
| Cliente mínimo compatible | Windows XP [aplicaciones de escritorio | aplicaciones para UWP] |
| Servidor mínimo compatible | Windows Server 2003 [aplicaciones de escritorio | aplicaciones para UWP] |
| Plataforma de destino | Windows |
| Encabezado | wincrypt.h |
| Library | Crypt32.lib |
| Archivo DLL | Crypt32.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