Función CertFindCertificateInStore (wincrypt.h)

Artículo
07/11/2024

La función certFindCertificateInStore busca el primer o siguiente contexto de de certificado en un almacén de certificados de que coincida 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 certificados de en un almacén de certificados de que coincidan con los criterios de búsqueda especificados.

Sintaxis

PCCERT_CONTEXT CertFindCertificateInStore(
  [in] HCERTSTORE     hCertStore,
  [in] DWORD          dwCertEncodingType,
  [in] DWORD          dwFindFlags,
  [in] DWORD          dwFindType,
  [in] const void     *pvFindPara,
  [in] PCCERT_CONTEXT pPrevCertContext
);

Parámetros

[in] hCertStore

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

[in] dwCertEncodingType

Especifica el tipo de codificación usada. Tanto el certificado como los tipos de codificación de mensajes deben especificarse combinándolos con una operación ORbit 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

[in] dwFindFlags

Se usa con algunos valores de dwFindType para modificar los criterios de búsqueda. Para la mayoría de los valores de dwFindType, no se usa dwFindFlags y debe establecerse en cero. Para obtener información detallada, vea Comentarios.

[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
CERT_FIND_ANY	Tipo de datos de pvFindPara: null, no se usa. No se usan criterios de búsqueda. Devuelve el siguiente certificado del almacén. Nota Es posible que el orden del contexto del certificado no se conserve en el almacén. Para acceder a un certificado específico, debe iterar entre los certificados del almacén.
CERT_FIND_CERT_ID	Tipo de datos de pvFindPara: estructura CERT_ID. Busque el certificado identificado por el CERT_IDespecificado.
CERT_FIND_CTL_USAGE	Tipo de datos de pvFindPara: estructura CTL_USAGE. Busca un certificado que tenga una extensión de szOID_ENHANCED_KEY_USAGE o un CERT_CTL_PROP_ID que coincida con el pszUsageIdentifier miembro de la estructura de CTL_USAGE.
CERT_FIND_ENHKEY_USAGE	Tipo de datos de pvFindPara: estructura CERT_ENHKEY_USAGE. Busca un certificado en el almacén que tenga un uso mejorado de claves extensión o una propiedad de uso de clave mejorada y un identificador de uso que coincida con el miembro cUsageIdentifier en la estructura de CERT_ENHKEY_USAGE. Un certificado tiene una extensión de uso de clave mejorada si tiene una estructura de CERT_EXTENSION con el miembro pszObjId establecido en szOID_ENHANCED_KEY_USAGE. Un certificado tiene una propiedad de uso de clave mejorada si se establece su identificador de CERT_ENHKEY_USAGE_PROP_ID. Si CERT_FIND_OPTIONAL_ENHKEY_USAGE_FLAG se establece en dwFindFlags, los certificados sin la extensión de uso de claves o la propiedad también coinciden. Establecer esta marca tiene prioridad sobre el paso de NULL en pvFindPara. Si se establece CERT_FIND_EXT_ONLY_ENHKEY_USAGE_FLAG, solo se realiza una coincidencia en la extensión de uso de claves. Para obtener información sobre las modificaciones de marcas en los criterios de búsqueda, vea Comentarios.
CERT_FIND_EXISTING	Tipo de datos de pvFindPara: estructura CERT_CONTEXT. Busca un certificado que sea una coincidencia exacta del contexto de certificado especificado.
CERT_FIND_HASH	Tipo de datos de pvFindPara: estructura CRYPT_HASH_BLOB. Busca un certificado con un hash SHA1 que coincida con el hash de la estructura CRYPT_HASH_BLOB.
CERT_FIND_HAS_PRIVATE_KEY	Tipo de datos de pvFindPara: null, no se usa. Busca un certificado que tenga una clave privada. La clave puede ser efímera o guardarse en el disco. La clave puede ser una clave heredada de Cryptography API (CAPI) o una clave CNG. Nota Es posible que el orden del contexto del certificado no se conserve en el almacén. Por lo tanto, para acceder a un certificado específico, debe iterar en todos los certificados. Windows 8 y Windows Server 2012: comienza la compatibilidad con esta marca.
CERT_FIND_ISSUER_ATTR	Tipo de datos de pvFindPara: estructura CERT_RDN. Busca un certificado con atributos de emisor especificados que coincidan con los atributos de la estructura CERT_RDN. Si se establecen estos valores, la función compara los atributos del emisor en un certificado con elementos de la matriz de CERT_RDN_ATTR de esta estructura CERT_RDN. Las comparaciones recorren en iteración los atributos de CERT_RDN_ATTR buscando una coincidencia con los atributos del emisor del certificado. Si el miembro pszObjId de CERT_RDN_ATTR es NULL, se omite el identificador del objeto de atributo. Si el miembro dwValueType de CERT_RDN_ATTR es CERT_RDN_ANY_TYPE, se omite el tipo de valor. Si el miembro pbData de CERT_RDN_VALUE_BLOB es null, cualquier valor es una coincidencia. Actualmente solo se admite una coincidencia exacta y con distinción entre mayúsculas y minúsculas. Para obtener información sobre las opciones Unicode, vea Comentarios. Cuando se establecen estos valores, la búsqueda está restringida a certificados cuyo tipo de codificación coincide con dwCertEncodingType.
CERT_FIND_ISSUER_NAME	Tipo de datos de pvFindPara: estructura CERT_NAME_BLOB. Busque un certificado con una coincidencia exacta del nombre completo del emisor con el nombre en CERT_NAME_BLOB La búsqueda está restringida a los certificados que coinciden con el dwCertEncodingType.
CERT_FIND_ISSUER_OF	Tipo de datos de pvFindPara: estructura CERT_CONTEXT. Busca un certificado con un asunto que coincida con el emisor en CERT_CONTEXT. En lugar de usar certFindCertificateInStore con este valor, use la función CertGetCertificateChain .
CERT_FIND_ISSUER_STR	Tipo de datos de pvFindPara: cadena Unicode terminada en null. Busca un certificado que contenga la cadena de nombre del emisor especificada. El miembro emisor del certificado se convierte en una cadena de nombre del tipo adecuado mediante la forma adecuada de CertNameToStr formateado como CERT_SIMPLE_NAME_STR. A continuación, se realiza una coincidencia de subcadena que no distingue mayúsculas de minúsculas dentro de una cadena. Cuando se establece este valor, la búsqueda está restringida a certificados cuyo tipo de codificación coincide con dwCertEncodingType. Si se produce un error en la coincidencia de subcadena y el asunto contiene un RDN de correo electrónico con cadena codificada punycode, se usa CERT_NAME_STR_ENABLE_PUNYCODE_FLAG para convertir el asunto a una cadena Unicode y se vuelve a realizar la coincidencia de subcadena.
CERT_FIND_KEY_IDENTIFIER	Tipo de datos de pvFindPara: estructura CRYPT_HASH_BLOB. Busca un certificado con una propiedad CERT_KEY_IDENTIFIER_PROP_ID que coincida con el identificador de clave de CRYPT_HASH_BLOB.
CERT_FIND_KEY_SPEC	Tipo de datos de pvFindPara: variable DWORD que contiene una especificación de clave. Busca un certificado que tenga una propiedad CERT_KEY_SPEC_PROP_ID que coincida con la especificación de clave en pvFindPara.
CERT_FIND_MD5_HASH	Tipo de datos de pvFindPara: estructura CRYPT_HASH_BLOB. Busca un certificado con un hash MD5 que coincida con el hash de CRYPT_HASH_BLOB.
CERT_FIND_PROPERTY	Tipo de datos de pvFindPara: DWORD variable que contiene un identificador de propiedad. Busca un certificado con una propiedad que coincida con el identificador de propiedad especificado por el valor de DWORD en pvFindPara.
CERT_FIND_PUBLIC_KEY	Tipo de datos de pvFindPara: estructura CERT_PUBLIC_KEY_INFO. Busca un certificado con una clave pública que coincida con la clave pública en la estructura CERT_PUBLIC_KEY_INFO.
CERT_FIND_SHA1_HASH	Tipo de datos de pvFindPara: estructura CRYPT_HASH_BLOB. Busca un certificado con un hash SHA1 que coincida con el hash de la estructura CRYPT_HASH_BLOB.
CERT_FIND_SHA1_SHA256_HASH	Tipo de datos de pvFindPara: estructura CRYPT_HASH_BLOB. Busca un certificado con un hash SHA1 + SHA256 que coincida con el hash de la estructura CRYPT_HASH_BLOB.
CERT_FIND_SHA256_HASH	Tipo de datos de pvFindPara: estructura CRYPT_HASH_BLOB. Busca un certificado con un hash SHA256 que coincida con el hash en la estructura CRYPT_HASH_BLOB.
CERT_FIND_SIGNATURE_HASH	Tipo de datos de pvFindPara: estructura CRYPT_HASH_BLOB. Busca un certificado con un hash de firma que coincida con el hash de firma de la estructura CRYPT_HASH_BLOB.
CERT_FIND_SUBJECT_ATTR	Tipo de datos de pvFindPara: estructura CERT_RDN. Busca un certificado con atributos de asunto especificados que coincidan con los atributos de la estructura CERT_RDN. Si se establecen valores de RDN, la función compara los atributos del firmante en un certificado con elementos de la matriz de CERT_RDN_ATTR en esta estructura de CERT_RDN. Las comparaciones recorren en iteración los atributos de CERT_RDN_ATTR buscando una coincidencia con los atributos del firmante del certificado. Si el miembro pszObjId de CERT_RDN_ATTR es NULL, se omite el identificador del objeto de atributo. Si el miembro dwValueType de CERT_RDN_ATTR es CERT_RDN_ANY_TYPE, se omite el tipo de valor. Si el miembro pbData de CERT_RDN_VALUE_BLOB es null, cualquier valor es una coincidencia. Actualmente solo se admite una coincidencia exacta y con distinción entre mayúsculas y minúsculas. Para obtener información sobre las opciones Unicode, vea Comentarios. Cuando se establecen estos valores, la búsqueda está restringida a certificados cuyo tipo de codificación coincide con dwCertEncodingType.
CERT_FIND_SUBJECT_CERT	Tipo de datos de pvFindPara: estructura CERT_INFO. Busca un certificado con un emisor y un número de serie que coincidan con el emisor y el número de serie en la estructura de CERT_INFO.
CERT_FIND_SUBJECT_NAME	Tipo de datos de pvFindPara: estructura CERT_NAME_BLOB. Busca un certificado con una coincidencia exacta del nombre completo del firmante con el nombre en la estructura CERT_NAME_BLOB. La búsqueda está restringida a certificados que coinciden con el valor de dwCertEncodingType.
CERT_FIND_SUBJECT_STR	Tipo de datos de pvFindPara: cadena Unicode terminada en null. Busca un certificado que contenga la cadena de nombre del firmante especificada. El miembro firmante del certificado se convierte en una cadena de nombre del tipo adecuado mediante la forma adecuada de CertNameToStr formateado como CERT_SIMPLE_NAME_STR. A continuación, se realiza una coincidencia de subcadena que no distingue mayúsculas de minúsculas dentro de una cadena. Cuando se establece este valor, la búsqueda está restringida a certificados cuyo tipo de codificación coincide con dwCertEncodingType.
CERT_FIND_CROSS_CERT_DIST_POINTS	Tipo de datos de pvFindPara: No se usa. Busque un certificado que tenga una extensión o propiedad de punto de distribución entre certificados.
CERT_FIND_PUBKEY_MD5_HASH	Tipo de datos de pvFindPara: estructura CRYPT_HASH_BLOB. Busque un certificado cuya clave pública con hash MD5 coincida con el hash especificado.

Nota Hay formas alternativas del valor de dwFindType que pasan una cadena en pvFindPara. Un formulario usa una cadena Unicode y la otra una cadena ASCII. Los valores que terminan en "_W" o sin un sufijo usan Unicode. Los valores que terminan con "_A" usan cadenas ASCII.

[in] pvFindPara

Apunta a un elemento de datos o una estructura usados con dwFindType.

[in] pPrevCertContext

Puntero a la última estructura CERT_CONTEXT devuelta por esta función. Este parámetro debe ser NULL en la primera llamada de la función. Para buscar certificados sucesivos que cumplan los criterios de búsqueda, establezca pPrevCertContext en el puntero devuelto por la llamada anterior a la función. Esta función libera los valores de CERT_CONTEXT a los que hace referencia novalores NULL de este parámetro.

Valor devuelto

Si la función se ejecuta correctamente, la función devuelve un puntero a una estructura de CERT_CONTEXT de solo lectura.

Si se produce un error en la función y no se encuentra un certificado que coincida con los criterios de búsqueda, el valor devuelto es NULL.

UnNULLCERT_CONTEXT que certFindCertificateInStore debe liberarse CertFreeCertificateCon text o que se pase como parámetro pPrevCertContext en una llamada posterior a CertFindCertificateInStore.

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 encontró ningún certificado que coincida con los criterios de búsqueda. Esto puede ocurrir si el almacén está vacío o se alcanza 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 certificado apuntado por el parámetro pPrevCertContext o un valor que no es válido se especificó en el parámetro dwFindType.

Observaciones

El parámetro dwFindFlags se usa para modificar los criterios de algunos tipos de búsqueda.

El valor de dwFindFlags de CERT_UNICODE_IS_RDN_ATTRS_FLAG solo se usa con los valores de CERT_FIND_SUBJECT_ATTR y CERT_FIND_ISSUER_ATTR para dwFindType. CERT_UNICODE_IS_RDN_ATTRS_FLAG debe establecerse si la estructura CERT_RDN_ATTR a la que apunta pvFindPara se inicializó con cadenas Unicode. Antes de realizar cualquier comparación, la cadena que se va a comparar se convierte mediante X509_UNICODE_NAME para proporcionar comparaciones Unicode.

Los siguientes valores dwFindFlags solo se usan con el valor de CERT_FIND_ENKEY_USAGE para dwFindType:

se puede llamar a certDuplicateCertificateContext para hacer un duplicado del contexto devuelto. El contexto devuelto se puede agregar a un almacén de certificados de diferente mediante CertAddCertificateContextToStoreo un vínculo a ese contexto de certificado se puede agregar a un almacén que no sea un almacén de recopilación mediante CertAddCertificateLinkToStore.

El puntero devuelto se libera cuando se pasa como parámetro pPrevCertContext en una llamada posterior a la función. De lo contrario, el puntero debe liberarse explícitamente llamando a CertFreeCertificateContext. CertFindCertificateInStore certFindCertificateInStore que no es NULL certFreeCertificateContext, incluso si se produce un error en la función.

Ejemplos

En el ejemplo siguiente se muestra cómo buscar un contexto de certificado en el almacén de certificados que cumpla un criterio de búsqueda. Para obtener un ejemplo completo que incluya el contexto de este ejemplo, vea Programa C de ejemplo: Operaciones de almacén de certificados.

Para obtener otro ejemplo que usa esta función, vea Programa C de ejemplo: recopilación y operaciones del almacén de certificados del mismo nivel.

#include <windows.h>
#include <stdio.h>
#include <Wincrypt.h>
#pragma comment(lib, "crypt32.lib")

#define MY_ENCODING_TYPE  (PKCS_7_ASN_ENCODING | X509_ASN_ENCODING)

void main()
{
//-------------------------------------------------------------------
// Declare and initialize variables.
HCERTSTORE  hSystemStore;              // The system store handle.
PCCERT_CONTEXT  pDesiredCert = NULL;   // Set to NULL for the first 
                                       // call to
                                       // CertFindCertificateInStore.
LPCSTR lpszCertSubject = (LPCSTR) "Cert_subject_1";


//-------------------------------------------------------------------
// Open the certificate store to be searched.

if(hSystemStore = CertOpenStore(
     CERT_STORE_PROV_SYSTEM, 
     0,                      // Encoding type not needed 
                             // with this PROV.
     NULL,                   // Accept the default HCRYPTPROV. 
     CERT_SYSTEM_STORE_CURRENT_USER,
                             // Set the system store location in 
                             // the registry.
     L"MY"))                 // Could have used other predefined 
                             // system stores
                             // including Trust, CA, or Root.
{
   printf("Opened the MY system store. \n");
}
else
{
   printf( "Could not open the MY system store.\n");
   exit(1);
}
//-------------------------------------------------------------------
// Get a certificate that has lpszCertSubject as its 
// subject. 

if(pDesiredCert=CertFindCertificateInStore(
      hSystemStore,
      MY_ENCODING_TYPE,           // Use X509_ASN_ENCODING.
      0,                          // No dwFlags needed. 
      CERT_FIND_SUBJECT_STR,      // Find a certificate with a
                                  // subject that matches the string
                                  // in the next parameter.
      lpszCertSubject ,           // The Unicode string to be found
                                  // in a certificate's subject.
      NULL))                      // NULL for the first call to the
                                  // function. In all subsequent
                                  // calls, it is the last pointer
                                  // returned by the function.
{
  printf("The desired certificate was found. \n");
}
else
{
   printf("Could not find the desired certificate.\n");
}
//-------------------------------------------------------------------
// Clean up. 

if(pDesiredCert)
    CertFreeCertificateContext(pDesiredCert);
if(hSystemStore)
    CertCloseStore(
        hSystemStore, 
        CERT_CLOSE_STORE_CHECK_FLAG);

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