Función CertFindCertificateInStore (wincrypt.h)
La función CertFindCertificateInStore busca el primer o siguiente contexto de certificado en un almacén de certificados que coincida 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 certificados de un almacén de certificados 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 que se va a buscar.
[in] dwCertEncodingType
Especifica el tipo de codificación utilizada. Los tipos de codificación de certificados y mensajes deben especificarse combinándolos 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
[in] dwFindFlags
Se usa con algunos valores dwFindType para modificar los criterios de búsqueda. Para la mayoría de los valores dwFindType , dwFindFlags no se usa y debe establecerse en cero. Para obtener información detallada, vea Comentarios.
[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 |
|---|---|
|
Tipo de datos de pvFindPara: NULL, no utilizado.
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 dentro del almacén.
Para acceder a un certificado específico, debe iterar entre los certificados del almacén.
|
|
Tipo de datos de pvFindPara: estructura CERT_ID .
Busque el certificado identificado por el CERT_ID especificado. |
|
Tipo de datos de pvFindPara: estructura CTL_USAGE .
Busca un certificado que tenga una extensión szOID_ENHANCED_KEY_USAGE o un CERT_CTL_PROP_ID que coincida con el miembro pszUsageIdentifier de la estructura CTL_USAGE . |
|
Tipo de datos de pvFindPara: estructura CERT_ENHKEY_USAGE .
Busca un certificado en el almacén que tenga una extensión de uso de clave mejorada o una propiedad de uso de clave mejorada y un identificador de uso que coincida con el miembro cUsageIdentifier en la estructura 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 son coincidencias. Establecer esta marca tiene prioridad sobre pasar 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. |
|
Tipo de datos de pvFindPara: estructura CERT_CONTEXT .
Busca un certificado que coincida exactamente con el contexto de certificado especificado. |
|
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 . |
|
Tipo de datos de pvFindPara: NULL, no utilizado.
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 dentro del almacén. Por lo tanto, para acceder a un certificado específico, debe iterar en todos los certificados.
|
|
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 CERT_RDN_ATTR de esta estructura CERT_RDN . Las comparaciones recorren en iteración los atributos de CERT_RDN_ATTR que buscan 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 que distingue mayúsculas de 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. |
|
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 dwCertEncodingType. |
|
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 . |
|
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 utilizando el formato adecuado de CertNameToStr con el formato CERT_SIMPLE_NAME_STR. A continuación, se realiza una coincidencia de subcadena sin distinción entre mayúsculas y minúsculas dentro de una cadena. Cuando se establece este valor, la búsqueda se restringe a los 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, CERT_NAME_STR_ENABLE_PUNYCODE_FLAG se usa para convertir el asunto en una cadena Unicode y se vuelve a realizar la coincidencia de subcadena. |
|
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. |
|
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. |
|
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. |
|
Tipo de datos de pvFindPara: variable DWORD que contiene un identificador de propiedad.
Busca un certificado con una propiedad que coincida con el identificador de propiedad especificado por el valor DWORD en pvFindPara. |
|
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 . |
|
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 . |
|
Tipo de datos de pvFindPara: estructura CRYPT_HASH_BLOB .
Busca un certificado con un hash de firma que coincida con el hash de firma en la estructura CRYPT_HASH_BLOB . |
|
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 RDN, la función compara los atributos del asunto en un certificado con elementos de la matriz 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 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 que distingue mayúsculas de 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. |
|
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 CERT_INFO . |
|
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 los certificados que coinciden con el valor de dwCertEncodingType. |
|
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 con el formato CertNameToStr adecuado como CERT_SIMPLE_NAME_STR. A continuación, se realiza una coincidencia de subcadena sin distinción entre mayúsculas y minúsculas dentro de una cadena. Cuando se establece este valor, la búsqueda se restringe a los certificados cuyo tipo de codificación coincide con dwCertEncodingType. |
|
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. |
|
Tipo de datos de pvFindPara: estructura CRYPT_HASH_BLOB .
Busque un certificado cuya clave pública con hash MD5 coincida con el hash especificado. |
[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 la CERT_CONTEXT a la que hacen referencia los valores que no son 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.
CertFreeCertificateContext debe liberar un CERT_CONTEXT que CertFindCertificateInStore devuelve o pasarse 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 |
|---|---|
|
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. |
|
El identificador del parámetro hCertStore no es el mismo que en el contexto del certificado al que apunta el parámetro pPrevCertContext , o bien se especificó un valor que no es válido en el parámetro dwFindType . |
Comentarios
El parámetro dwFindFlags se usa para modificar los criterios de algunos tipos de búsqueda.
El valor de CERT_UNICODE_IS_RDN_ATTRS_FLAG dwFindFlags 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 de 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 hacer coincidir 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 duplicar el contexto devuelto. El contexto devuelto se puede agregar a un almacén de certificados diferente mediante CertAddCertificateContextToStore o se puede agregar un vínculo a ese contexto de certificado a un almacén que no es un almacén de colecciones 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 libera siempre un pPrevCertContext que no es NULL mediante una llamada a 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 del almacén de certificados.
Para obtener otro ejemplo en el que se usa esta función, vea Ejemplo de programa C: 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 | 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 |
Consulte también
CertAddCertificateContextToStore
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de