Compartir a través de

Función CertGetCertificateChain (wincrypt.h)

  • Artículo

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.

Valor Significado
CERT_CHAIN_CACHE_END_CERT
0x00000001		 Cuando se establece esta marca, el certificado final se almacena en caché, lo que puede 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.
CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY
0x80000000		 La comprobación de revocación solo tiene acceso a las direcciones URL almacenadas en caché. Esto impediría la recuperación de red de CRL o OCSP para los certificados de entidad de certificación finales o de ca. CACHE_ONLY depende de un compañero de la máquina para que ya haya recuperado la CRL o OCSP de la red.
CERT_CHAIN_REVOCATION_CHECK_OCSP_CERT
0x04000000		 Esta marca se usa internamente durante la creación de cadenas para un certificado de firma de 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 de OCSP independiente, 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 la comprobación de OCSP y CRL.

Windows Server 2003 y Windows XP: Este valor no se admite.
CERT_CHAIN_CACHE_ONLY_URL_RETRIEVAL
0x00000004		 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, como taxis de CTL, raíces de terceros y emisores de AIA. La mayoría de las raíces deben estar en un recurso de crypt32.dll. Si no es así, esta recuperación es necesaria para evitar un error de creación de cadena. Estos taxis y raíces se hospedan en servidores de Microsoft CDN de alto rendimiento.

Nota: Esta marca no es aplicable a la comprobación de revocación. Establezca CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY para usar solo direcciones URL almacenadas en caché para la comprobación de revocación. Normalmente, los taxis CTL ya se capturan previamente a través del servicio cryptsvc.
CERT_CHAIN_DISABLE_PASS1_QUALITY_FILTERING0x00000040 Por motivos de rendimiento, el segundo paso de creación de cadena solo considera posibles rutas de cadena que tienen una calidad mayor o igual que la más alta determinada durante el primer paso. El primer paso solo tiene en cuenta 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 tener en cuenta todas las posibles rutas de acceso de cadena durante el segundo paso.
CERT_CHAIN_DISABLE_MY_PEER_TRUST
0x00000800		 Esta marca no se admite. Los certificados del almacén "Mi" nunca se consideran para la confianza del mismo nivel.
CERT_CHAIN_ENABLE_PEER_TRUST
0x00000400		 Los certificados de entidad final del 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 ni CERT_TRUST_IS_UNTRUSTED_ROOTdwErrorStatus del parámetro ppChainContext.

Windows Server 2003 y Windows XP: Esta marca no se admite.
CERT_CHAIN_OPT_IN_WEAK_SIGNATURE
0x00010000		 Establecer esta marca 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.
CERT_CHAIN_RETURN_LOWER_QUALITY_CONTEXTS
0x00000080		 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 de cLowerQualityChainContext y rgpLowerQualityChainContext campos del contexto de cadena.
CERT_CHAIN_DISABLE_AUTH_ROOT_AUTO_UPDATE
0x00000100		 Establecer esta marca impide la actualización automática de raíces de terceros desde windows Update Web Server.
CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT
0x08000000		 Al establecer CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT y también se especifica un valor para el dwUrlRetrievalTimeout miembro de la estructura de 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 de 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 de 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 la directiva de grupo.
CERT_CHAIN_TIMESTAMP_TIME
0x00000200		 Cuando se establece esta marca, pTime se usa como la hora 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 sigue siendo válido. El resto de entidad de certificación (CA) y certificados raíz de la cadena se comprueban mediante la hora actual y no pTime.
CERT_CHAIN_DISABLE_AIA
0x00002000		 Al establecer esta marca, se desactivan explícitamente las recuperaciones de Acceso a la información de autoridad (AIA). A veces, los servidores TLS están configurados incorrectamente y no incluyen los certificados de CA correctos en el protocolo de enlace.

También puede establecer las siguientes marcas de revocación, pero solo se puede establecer una marca de este grupo a la vez.

Valor Significado
CERT_CHAIN_REVOCATION_CHECK_END_CERT
0x10000000		 La comprobación de revocación se realiza en el certificado final y solo el certificado final.
CERT_CHAIN_REVOCATION_CHECK_CHAIN
0x20000000		 La comprobación de revocación se realiza en todos los certificados de cada cadena.
CERT_CHAIN_REVOCATION_CHECK_CHAIN_EXCLUDE_ROOT
0x40000000		 La comprobación de revocación se realiza en todos los certificados de todas las cadenas, excepto en el certificado raíz.

[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

Requisito Valor
cliente mínimo admitido Windows XP [aplicaciones de escritorio | Aplicaciones para UWP]
servidor mínimo admitido Windows Server 2003 [aplicaciones de escritorio | Aplicaciones para UWP]
de la plataforma de destino de Windows
encabezado de wincrypt.h
biblioteca de Crypt32.lib
DLL de Crypt32.dll

Consulte también

CERT_CHAIN_PARA

CertDuplicateCertificateChain

CertFreeCertificateChain

funciones de comprobación de la cadena de certificados