Función CertGetCertificateChain (wincrypt.h)

La función CertGetCertificateChain de crea un contexto de cadena de certificados a partir de un certificado final y vuelve, si es posible, a un certificado raíz de 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 compila 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 comprobación de la lista de confianza, la revocación o el almacén raíz. La hora actual del sistema se usa si NULL se pasa 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 de (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.

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 la cadena, libere la cadena llamando a la función CertFreeCertificateChain.

Valor devuelto

Si la función se realiza 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.

Observaciones

Cuando una aplicación solicita una cadena de certificados, la estructura devuelta tiene la forma de un CERT_CHAIN_CONTEXT. Este contexto contiene una matriz de CERT_SIMPLE_CHAIN estructuras en las que 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 de 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 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, los errores CERT_TRUST_HAS_WEAK_SIGNATURE y CERT_TRUST_IS_NOT_SIGNATURE_VALID se establecen en el campo dwErrorStatus de la estructura de CERT_TRUST_STATUS. Para deshabilitar la comprobación de la longitud de la clave, establezca el valor de CERT_CHAIN_STRONG_SIGN_DISABLE_END_CHECK_FLAG en el miembro dwStrongSignFlags de la estructura de CERT_CHAIN_PARA apuntado por el parámetro pChainPara de .
• Si las marcas 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 de CERT_TRUST_IS_OFFLINE_REVOCATION y CERT_TRUST_REVOCATION_STATUS_UNKNOWN se establecen en el campo dwErrorStatus de la estructura de CERT_TRUST_STATUS. Además, el miembro dwRevocationResult de la estructura de CERT_REVOCATION_INFO se establece en NTE_BAD_ALGID.

Las siguientes recomendaciones se aplicarían a cualquier aplicación de Windows que llame a estas API para comprobar un certificado de autenticación del servidor TLS:

• Habilitar solo la comprobación de revocación para el certificado final.
  • Establezca la marca CERT_CHAIN_REVOCATION_CHECK_END_CERT.
  • La mayoría de los certificados de ENTIDAD de certificación tienen CRL con una validez de tiempo de 1 a 6 meses.
    • Puesto que las CRL descargadas se almacenan en caché, esta validez es demasiado larga para tener mucho valor.
  • Si hay un riesgo de entidad de certificación, los certificados también se agregarían al CTL no permitido de Windows.
  • La práctica recomendada para los servidores TLS es admitir la asociación OCSP para el certificado final.
    • En ese caso, no se necesitará ninguna recuperación de red a menos que la respuesta OCSP grapada haya expirado.
• Habilite las recuperaciones de red para CRL, OCSP, emisores de AIA y taxis CTL de la plataforma Windows y raíces de terceros.
  • Cuando se establece el CERT_CHAIN_REVOCATION_CHECK_END_CERT anterior, este es el valor predeterminado.
  • No establezca ninguna de las marcas siguientes para evitar las recuperaciones de red. Consulte la tabla dwFlags anterior para obtener más información sobre estas marcas:
    • CERT_CHAIN_CACHE_ONLY_URL_RETRIEVAL
    • CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY
    • CERT_CHAIN_DISABLE_AIA
• Habilite el tiempo de espera acumulado para las recuperaciones de red CRL y OCSP.
  • Establezca la marca de CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT pasada a CertGetCertificateChain.
  • Proporciona un límite superior en el tiempo total permitido para las recuperaciones de red CRL y OCSP.
• Reduzca el tiempo máximo permitido para cada recuperación de red de 15 a 10 segundos.
  • Establezca el campo dwUrlRetrievalTimeout de en el CERT_CHAIN_PARA pasado a CertGetCertificateChain a 10 * 1000 milisegundos.
  • Esto también reduce el tiempo de espera acumulado de 20 a 10 segundos.
    • Solo se deben descargar las respuestas OCSP para los certificados finales. 5 segundos debe ser suficiente para esa descarga.
• Omitir los errores de revocación sin conexión.
  • Establezca CERT_CHAIN_POLICY_IGNORE_ALL_REV_UNKNOWN_FLAGS en el CERT_CHAIN_POLICY_PARA pasado a CertVerifyCertificateChainPolicy(CERT_CHAIN_POLICY_SSL).
  • La recuperación de red de OCSP y CRL es el mejor intento. La mayoría de las recuperaciones de red deben realizarse correctamente en un par de segundos, pero no es 100% garantizado.
• Información de validación de certificados finales de caché.
  • Establezca el CERT_CHAIN_CACHE_END_CERT.
    • Habilita el almacenamiento en caché de LRU de información sobre los certificados finales además de los certificados intermedios.
  • Es habitual realizar varias conexiones TLS al mismo servidor.

Ejemplos

Para obtener un ejemplo que usa esta función, vea Programa C de ejemplo: Crear una cadena de certificados.

Requisitos

Consulte también

CERT_CHAIN_PARA

CertDuplicateCertificateChain

CertFreeCertificateChain

funciones de comprobación de la cadena de certificados