Función CertFindChainInStore (wincrypt.h)

Artículo
03/15/2023

La función CertFindChainInStore busca el primer o siguiente certificado en un almacén 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, dwFindType y 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 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 a la función CertGetCertificateChain a medida que se compila la cadena.

[in] dwCertEncodingType

Tipo de codificación de certificado que se usó para codificar el almacén. Esta función omite el identificador de tipo de codificación de mensaje , contenido en el alto WORD de este valor.

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

Value	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 para 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.

Value	Significado
CERT_CHAIN_FIND_BY_ISSUER_COMPARE_KEY_FLAG	Compara la clave pública del certificado con la clave pública del proveedor de servicios criptográficos. Esta comparación es la última comprobación realizada en la cadena cuando se compila. Dado que el miembro hCryptProv de un emisor contiene una clave privada, es posible que tenga que comprobarse varias veces durante este proceso; para facilitar esta comprobación, el miembro dwAcquirePrivateKeyFlags se puede establecer en la estructura 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 que la primera cadena simple coincida con el 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 en la memoria caché de direcciones URL. No se busca en Internet.
CERT_CHAIN_FIND_BY_ISSUER_LOCAL_MACHINE_FLAG	Solo abre los almacenes de certificados del equipo local. Los almacenes de certificados del usuario actual no se abren.
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 en busca de un certificado de emisor que coincida con uno de un conjunto de nombres de emisor.

Esta función comparará los blobs de nombre pasados en la estructura pvFindPara con 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 encuentra 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 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 primer contexto de cadena o siguiente, se devuelve NULL . De lo contrario, se devuelve un puntero a una estructura de CERT_CHAIN_CONTEXT de solo lectura. La estructura de 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 de CERT_CHAIN_CONTEXT debe liberarse explícitamente llamando a la función CertFreeCertificateChain .

Comentarios

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, 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 la función CertFreeCertificateChain , incluso si se produce un error.

Requisitos


Cliente mínimo compatible	Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	wincrypt.h
Library	Crypt32.lib
Archivo DLL	Crypt32.dll