Función CertFindCTLInStore (wincrypt.h)

Artículo
07/16/2024

La función certFindCTLInStore encuentra la primera o siguiente lista de confianza de certificados (CTL) contexto que coincide con los criterios de búsqueda establecidos por el dwFindType y su pvFindParaasociado . Esta función se puede usar en un bucle para buscar todos los contextos de CTL en un almacén de certificados de que coincidan con los criterios de búsqueda especificados.

Sintaxis

PCCTL_CONTEXT CertFindCTLInStore(
  [in] HCERTSTORE    hCertStore,
  [in] DWORD         dwMsgAndCertEncodingType,
  [in] DWORD         dwFindFlags,
  [in] DWORD         dwFindType,
  [in] const void    *pvFindPara,
  [in] PCCTL_CONTEXT pPrevCtlContext
);

Parámetros

[in] hCertStore

Identificador del almacén de certificados que se va a buscar.

[in] dwMsgAndCertEncodingType

Especifica el tipo de codificación que se usa en el CTL. Siempre es aceptable especificar los tipos de codificación de mensajes de certificado y combinándolos con una operación orOR bit a bit, como se muestra en el ejemplo siguiente:

X509_ASN_ENCODING | PKCS_7_ASN_ENCODING tipos de codificación definidos actualmente son:

X509_ASN_ENCODING
PKCS_7_ASN_ENCODING

Este parámetro solo se usa cuando el parámetro dwFindType está establecido en CTL_FIND_USAGE.

[in] dwFindFlags

Se puede establecer cuando dwFindType se establece en CTL_FIND_USAGE. Para obtener más información, consulte los comentarios en CTL_FIND_USAGE, a continuación.

[in] dwFindType

Especifica el tipo de búsqueda que se va a realizar. El tipo de búsqueda determina el tipo de datos, el contenido y el uso de pvFindPara. Este parámetro puede ser uno de los siguientes valores.

Valor	Significado
CTL_FIND_ANY	Tipo de datos de pvFindPara: NULL. Cualquier CTL es una coincidencia.
CTL_FIND_SHA1_HASH	Tipo de datos de pvFindPara: CRYPT_HASH_BLOB. Se encuentra un CTL con un hash que coincide con el hash en la estructura CRYPT_HASH_BLOB.
CTL_FIND_MD5_HASH	Tipo de datos de pvFindPara: CRYPT_HASH_BLOB. Se encuentra un CTL con un hash que coincide con el hash en la estructura CRYPT_HASH_BLOB.
CTL_FIND_USAGE	Tipo de datos de pvFindPara: CTL_FIND_USAGE_PARA. Se encuentra cualquier CTL que tenga un identificador de uso, un identificador de lista o un firmante que coincidan con el identificador de uso, el identificador de lista o el firmante en la estructura de CTL_FIND_USAGE_PARA. Si el miembro cUsageIdentifier tiene tamaño SubjectUsage, cualquier CTL es una coincidencia. Si el miembro cbData de miembro ListIdentifier es cero, cualquier identificador de lista es una coincidencia. Si el miembro cbData de listIdentifier es CTL_FIND_NO_LIST_ID_CBDATA, solo se CTL_FIND_NO_LIST_ID_CBDATA un CTL sin un identificador de lista es una coincidencia. Si el miembro pSigner de la estructura CTL_FIND_USAGE_PARA es null, cualquier firmante de CTL es una coincidencia y solo se usan los miembros Issuer y SerialNumber en la estructuraCERT_INFO pSigner de . Si pSigner es CTL_FIND_NO_SIGNER_PTR, solo un CTL sin un firmante es una coincidencia.
CTL_FIND_SAME_USAGE_FLAG	Tipo de datos de pvFindPara: CTL_FIND_USAGE_PARA. Solo se coinciden las CCL con exactamente los mismos identificadores de uso. Las CCL que tienen identificadores de uso adicionales no coinciden. Por ejemplo, si solo se especifica "1.2.3" en la estructura de CTL_FIND_USAGE_PARA, para una coincidencia, el CTL solo debe contener "1.2.3" y ningún identificador de uso adicional.
CTL_FIND_EXISTING	Tipo de datos de pvFindPara: PCCTL_CONTEXT. Busca la siguiente CRL que es una coincidencia exacta de la CTL_CONTEXT.
CTL_FIND_SUBJECT	Tipo de datos de pvFindPara: CTL_FIND_SUBJECT_PARA. Se encuentra un CTL que tiene el asunto especificado. certFindSubjectInCTL se puede llamar para obtener un puntero a la entrada del sujeto en el CTL. El miembro pUsagePara de CTL_FIND_SUBJECT_PARA se puede establecer opcionalmente para habilitar la coincidencia descrita anteriormente en CTL_FIND_USAGE.

[in] pvFindPara

Puntero al valor de búsqueda asociado al parámetro dwFindType.

[in] pPrevCtlContext

Puntero al último CTL_CONTEXT devuelto por esta función. Debe ser NULL para obtener el primer CTL en el almacén. Las CCL sucesivas se recuperan estableciendo pPrevCtlContext al puntero al CTL_CONTEXT devuelto por una llamada de función anterior. Se omiten los certificados que no cumplan los criterios de búsqueda o que hayan sido eliminados previamente por CertDeleteCTLFromStore. Esta función libera el CTL_CONTEXT al que hacen referencia los valores que no sonNULL de este parámetro.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es un puntero a un CTL de solo lectura contexto.

Para obtener información de error extendida, llame a GetLastError. A continuación se indican algunos códigos de error posibles.

Código devuelto	Descripción
CRYPT_E_NOT_FOUND	No se encontraron CTL en el almacén, no se encontró ningún CTL que coincida con los criterios de búsqueda o la función alcanzó el final de la lista del almacén.
E_INVALIDARG	El identificador del parámetro hCertStore no es el mismo que en el contexto CTL al que apunta el parámetro pPrevCtlCon text o un valor que no es válido se especificó en el parámetro dwFindType.

Observaciones

Se libera un puntero devuelto cuando se pasa como el pPrevCtlContext en una llamada posterior a la función. De lo contrario, el puntero debe liberarse llamando a CertFreeCTLContext. UnNULLpPrevCtlContext pasado a la función siempre se libera con una llamada a CertFreeCTLContext, incluso si la función genera un error.

se puede llamar a certDuplicateCTLContext para hacer un duplicado del contexto devuelto. El contexto de CTL devuelto se puede agregar a un almacén de certificados diferente mediante CertAddCTLContextToStore, o un vínculo a ese contexto de CTL se puede agregar a un almacén de no colección mediante CertAddCTLLinkToStore. Si no se encuentra un CTL que coincida con los criterios de búsqueda, se devuelve NULL.

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