Función CertFindChainInStore (wincrypt.h)

Artículo
07/16/2024

La función certFindChainInStore busca el primer certificado o el siguiente en un almacén de que cumple los criterios especificados. A continuación, compila y comprueba un contexto de cadena de certificados para ese certificado. El certificado que se encuentra y para el que se compila la cadena se selecciona según los criterios establecidos por los parámetros dwFindFlags, dwFindTypey pvFindPara. Esta función se puede usar en un bucle para buscar todos los certificados de un almacén de certificados que coincidan con los criterios de búsqueda especificados y para crear un contexto de cadena de certificados para cada certificado encontrado.

Sintaxis

PCCERT_CHAIN_CONTEXT CertFindChainInStore(
  [in] HCERTSTORE           hCertStore,
  [in] DWORD                dwCertEncodingType,
  [in] DWORD                dwFindFlags,
  [in] DWORD                dwFindType,
  [in] const void           *pvFindPara,
  [in] PCCERT_CHAIN_CONTEXT pPrevChainContext
);

Parámetros

[in] hCertStore

Identificador del almacén en el que se va a buscar un certificado en el que se compila una cadena. Este identificador se pasa como un almacén adicional al CertGetCertificateChain función a medida que se compila la cadena.

[in] dwCertEncodingType

El tipo de codificación de certificado que se usó para codificar el almacén. La tipo de codificación de mensajes identificador, contenida en el alto word de este valor, esta función omite.

Este parámetro puede ser el siguiente tipo de codificación de certificado definido actualmente.

Valor	Significado
X509_ASN_ENCODING 1 (0x1)	Especifica la codificación de certificados X.509.

[in] dwFindFlags

Contiene opciones adicionales para la búsqueda. Los valores posibles de este parámetro dependen del valor del parámetro dwFindType.

Este parámetro puede contener cero o una combinación de uno o varios de los valores siguientes cuando dwFindType contiene CERT_CHAIN_FIND_BY_ISSUER.

Valor	Significado
CERT_CHAIN_FIND_BY_ISSUER_COMPARE_KEY_FLAG	Compara la clave pública del certificado con el proveedor de servicios criptográficos clave pública. Esta comparación es la última comprobación realizada en la cadena cuando se compila. Dado que el hCryptProv miembro de un emisor contiene una clave privada, es posible que deba comprobarse varias veces durante este proceso; para facilitar esta comprobación, el miembro dwAcquirePrivateKeyFlags se puede establecer en la estructura de CERT_CHAIN_FIND_BY_ISSUER_PARA para habilitar el almacenamiento en caché de ese hCryptProv.
CERT_CHAIN_FIND_BY_ISSUER_COMPLEX_CHAIN_FLAG	De forma predeterminada, solo se comprueba la primera cadena simple en busca de coincidencias de nombre del emisor. Con este conjunto de marcas, el valor predeterminado se invalida y las cadenas simples posteriores también se comprueban si el nombre del emisor coincide.
CERT_CHAIN_FIND_BY_ISSUER_CACHE_ONLY_FLAG	Mejora el rendimiento de esta función haciendo que busque solo los almacenes del sistema almacenados en caché (Root, My, Ca, Trust) para buscar certificados de emisor. Si no se establece esta marca, la función busca en los almacenes del sistema almacenados en caché y en el almacén representado por el parámetro hCertStore.
CERT_CHAIN_FIND_BY_ISSUER_CACHE_ONLY_URL_FLAG	Solo se busca la caché de direcciones URL. Internet no se busca.
CERT_CHAIN_FIND_BY_ISSUER_LOCAL_MACHINE_FLAG	Solo abre los almacenes de certificados de máquina local. No se abren los almacenes de certificados del usuario actual.
CERT_CHAIN_FIND_BY_ISSUER_NO_KEY_FLAG	No se realiza ninguna comprobación para determinar si el certificado tiene una clave privada asociada.

[in] dwFindType

Determina qué criterios usar para buscar un certificado en el almacén.

Este parámetro puede ser el siguiente valor definido actualmente.

CERT_CHAIN_FIND_BY_ISSUER

Busca el certificado en función del nombre del emisor. El parámetro pvFindPara es un puntero a una estructura CERT_CHAIN_FIND_BY_ISSUER_PARA que contiene miembros que modifican la búsqueda.

La cadena de certificados se crea para un certificado con una clave privada disponible . De forma predeterminada, solo se comparan los emisores de la primera cadena simple en una coincidencia de nombre del emisor. Si se establece esta marca, se comprueban todas las cadenas de un certificado de emisor que coincide con uno de un conjunto de nombres de emisor.

Esta función comparará el nombre blobs pasados en la estructura de pvFindPara a cualquier entidad de certificación (CA) de la cadena, no solo la entidad de certificación del certificado raíz.

Esta función no realiza ninguna comprobación de revocación.

Si pPrevChainContext no es NULL, esta función devolverá una cadena para un certificado diferente cada vez que se llame a la función. Si solo hay un certificado adecuado, pero hay dos entidades de certificación emisoras coincidentes, una de las cuales se revoca, es posible que esta función devuelva la cadena revocada. Si la aplicación comprueba la revocación por sí misma a través de llamadas a la función CertVerifyRevocation y busca la cadena no adecuada, una llamada adicional a la función CertFindChainInStore no devolverá una cadena que incluya el mismo certificado de la entidad de certificación válida. En su lugar, devolverá una cadena completamente diferente con un certificado diferente o NULL, si no se puede encontrar dicha cadena.

[in] pvFindPara

Puntero que contiene criterios de búsqueda adicionales. El tipo y el formato de los datos a los que apunta este parámetro dependen del valor del parámetro dwFindType.

[in] pPrevChainContext

Puntero a una estructura CERT_CHAIN_CONTEXT devuelta desde una llamada anterior a esta función. La búsqueda se inicia a partir de este certificado. Para la primera llamada a esta función, este parámetro debe ser NULL. En las llamadas posteriores, es el puntero devuelto por la llamada anterior a la función. Si este parámetro no es NULL, esta función liberará esta estructura.

Valor devuelto

Si no se compila el contexto de cadena primero o siguiente, se devuelve NULL. De lo contrario, se devuelve un puntero a una estructura de CERT_CHAIN_CONTEXT de solo lectura. La estructura CERT_CHAIN_CONTEXT se libera cuando se pasa como parámetro pPrevChainContext en una llamada posterior a esta función. De lo contrario, la estructura CERT_CHAIN_CONTEXT debe liberarse explícitamente mediante una llamada a la función CertFreeCertificateChain .

Observaciones

El parámetro pPrevChainContext debe ser NULL en la primera llamada para compilar el contexto de la cadena. Para compilar el siguiente contexto de cadena, el pPrevChainContext se establece en la estructura CERT_CHAIN_CONTEXT devuelta por una llamada anterior. Si pPrevChainContext no es NULL, esta función siempre libera la estructura mediante el uso de la función CertFreeCertificateChain, incluso si se produce un error.

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	Crypt32.lib
DLL de	Crypt32.dll