Función CertFindCTLInStore (wincrypt.h)

Artículo
08/27/2023

La función CertFindCTLInStore busca el primer o siguiente contexto de lista de confianza de certificados (CTL) que coincide con los criterios de búsqueda establecidos por dwFindType y su pvFindPara asociado. Esta función se puede usar en un bucle para buscar todos los contextos de CTL en un almacén de certificados 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 utilizada en el CTL. Siempre es aceptable especificar los tipos de codificación de certificados y mensajes mediante su combinación con una operación OR 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 se establece en CTL_FIND_USAGE.

[in] dwFindFlags

Se puede establecer cuando dwFindType está establecido 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 está realizando. 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 valores siguientes.

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 de 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 de 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 es de tamaño SubjectUsage , cualquier CTL es una coincidencia. Si el miembro cbData del 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 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 de la estructura CERT_INFO pSigner. 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 CTL con exactamente los mismos identificadores de uso. Las CTL que tienen identificadores de uso adicionales no coinciden. Por ejemplo, si solo se especifica "1.2.3" en la estructura 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 sea una coincidencia exacta del CTL_CONTEXT.
CTL_FIND_SUBJECT	Tipo de datos de pvFindPara: CTL_FIND_SUBJECT_PARA. Se encuentra un CTL que tiene el asunto especificado. Se puede llamar a CertFindSubjectInCTL 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 CTL sucesivas se recuperan estableciendo pPrevCtlContext en el puntero al CTL_CONTEXT devuelto por una llamada de función anterior. Los certificados que no cumplan los criterios de búsqueda o que certDeleteCTLFromStore haya eliminado previamente se omiten. Esta función libera el CTL_CONTEXT al que hacen referencia los valores que no son NULL de este parámetro.

Valor devuelto

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

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 de la tienda.
E_INVALIDARG	El identificador del parámetro hCertStore no es el mismo que en el contexto de CTL al que apunta el parámetro pPrevCtlContext o se especificó un valor que no es válido en el parámetro dwFindType .

Comentarios

Se libera un puntero devuelto cuando se pasa como pPrevCtlContext en una llamada posterior a la función. De lo contrario, el puntero debe liberarse llamando a CertFreeCTLContext. Un valor pPrevCtlContext noNULL 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 duplicar el contexto devuelto. El contexto de CTL devuelto se puede agregar a un almacén de certificados diferente mediante CertAddCTLContextToStore o se puede agregar un vínculo a ese contexto de CTL a un almacén que no sea de colección mediante CertAddCTLLinkToStore. Si no se encuentra un CTL que coincida con los criterios de búsqueda, se devuelve NULL .

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2003 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	wincrypt.h
Library	Crypt32.lib
Archivo DLL	Crypt32.dll