Extensión de la funcionalidad CertOpenStore

El almacén de certificados es central para todas las operaciones de administración de certificados. La funcionalidad de la función CertOpenStore se puede ampliar mediante el uso de una función de proveedor de certificados de almacén de certificados instalable (o registrada). Para obtener información general sobre cómo instalar o registrar funciones para su uso con CryptoAPI, consulte Información general sobre OID.

Nota

Los almacenes de certificados personalizados no se migran automáticamente al realizar implementaciones automatizadas. Para migrar almacenes de certificados personalizados, debe crear un manifiesto para migrar los almacenes personalizados y usar la Herramienta de migración de estado de usuario (USMT) de Windows.

 

CertOpenStore abre un almacén vacío en memoria y llama a la función del proveedor de almacenamiento (si está registrada o instalada) mediante el identificador de objeto (OID) que se pasó en el parámetro lpszStoreProvider . Para obtener una lista de los tipos de proveedor predefinidos que se proporcionan con CryptoAPI, consulte CertOpenStore.

La función del proveedor de almacenamiento copia sus certificados y listas de revocación de certificados (CRL) en el almacén en memoria especificado por el identificador hCertStore que se le ha pasado. La nueva función del proveedor de almacén puede usar cualquiera de las funciones de almacén de certificados CryptoAPI, como CertAddCertificateContextToStore o CertAddSerializedElementToStore, para agregar sus certificados y CRL al almacén en memoria. Además, la función store-provider devuelve opcionalmente valores para todos los miembros de datos de la estructura CERT_STORE_PROV_INFO . La función solo necesita actualizar esta estructura si admite funciones de devolución de llamada adicionales. Por ejemplo, si el almacén era un almacén de solo lectura, es probable que no se necesite la compatibilidad con otras funciones de devolución de llamada. Para obtener detalles y prototipos de las posibles funciones de devolución de llamada, consulte Funciones de devolución de llamada del proveedor del almacén de certificados.

El almacén TrustedPeople por usuario está restringido a almacenes físicos predefinidos. No se puede ampliar el almacén TrustedPeople por usuario. Sin embargo, puede ampliar el almacén trustedPeople de la máquina local.

Windows XP y Windows Server 2003: El almacén trustedPeople por usuario no está restringido a almacenes físicos predefinidos.

Uno de los miembros de datos de la estructura CERT_STORE_PROV_INFO es la matriz rgpvStoreProvFunc . Si la función del proveedor de almacenamiento necesita admitir una o varias de las funciones de devolución de llamada, debe proporcionar punteros para esta matriz. Estos punteros deben apuntar a las funciones de devolución de llamada que se van a usar para otras actividades del almacén de certificados (como cerrar el almacén). En la ilustración siguiente se muestra el flujo de este proceso.

Como se muestra en la ilustración siguiente, una vez abierto el almacén, otras funciones CryptoAPI (como CertCloseStore) usan la matriz de punteros para acceder a las funciones de devolución de llamada que realizan la tarea prevista. La definición de la estructura de CERT_STORE_PROV_INFO y los prototipos de las funciones de devolución de llamada predeterminadas que se proporcionan con CryptoAPI se muestran en funciones de devolución de llamada del proveedor del almacén de certificados.

Las API de almacén permiten a un proveedor de almacén mantener los certificados, las CRL y las listas de confianza de certificados (CTL) fuera de la memoria caché del almacén (por ejemplo, una base de datos externa de certificados, como la proporcionada por la base de datos de Microsoft Certificate Server).

CertOpenStore envía a través del parámetro pszStoreProvider a la función de proveedor instalable CertDllOpenStoreProv adecuada. El proveedor devuelve información en el parámetro pStoreProvInfo que apunta a una estructura de CERT_STORE_PROV_INFO . La estructura CERT_STORE_PROV_INFO contiene un miembro dwStoreProvFlags . Se agregó la marca CERT_STORE_PROV_EXTERNAL_FLAG para permitir que el proveedor indique que los certificados, las CRL y las CTL son externos a la memoria caché del almacén.

CertDllOpenStoreProv devuelve una matriz de funciones de devolución de llamada. Un proveedor puede implementar las siguientes funciones de devolución de llamada:

• CERT_STORE_PROV_CLOSE_FUNC
• CERT_STORE_PROV_READ_CERT_FUNC
• CERT_STORE_PROV_WRITE_CERT_FUNC
• CERT_STORE_PROV_DELETE_CERT_FUNC
• CERT_STORE_PROV_SET_CERT_PROPERTY_FUNC
• CERT_STORE_PROV_READ_CRL_FUNC
• CERT_STORE_PROV_WRITE_CRL_FUNC
• CERT_STORE_PROV_DELETE_CRL_FUNC
• CERT_STORE_PROV_SET_CRL_PROPERTY_FUNC
• CERT_STORE_PROV_READ_CTL_FUNC
• CERT_STORE_PROV_WRITE_CTL_FUNC
• CERT_STORE_PROV_DELETE_CTL_FUNC
• CERT_STORE_PROV_SET_CTL_PROPERTY_FUNC

En las llamadas al WRITE_CERT, WRITE_CRL y WRITE_CTL funciones de devolución de llamada cuando se establece el CERT_STORE_PROV_WRITE_ADD_FLAG, los 16 bits superiores del parámetro dwFlags contienen el valor dwAddDisposition . Para admitir almacenes externos, un proveedor puede implementar las siguientes funciones de devolución de llamada:

• CERT_STORE_PROV_FIND_CERT_FUNC
• CERT_STORE_PROV_FREE_FIND_CERT_FUNC
• CERT_STORE_PROV_GET_CERT_PROPERTY_FUNC
• CERT_STORE_PROV_FIND_CRL_FUNC
• CERT_STORE_PROV_FREE_FIND_CRL_FUNC
• CERT_STORE_PROV_GET_CRL_PROPERTY_FUNC
• CERT_STORE_PROV_FIND_CTL_FUNC
• CERT_STORE_PROV_FREE_FIND_CTL_FUNC
• CERT_STORE_PROV_GET_CTL_PROPERTY_FUNC

Las funciones de devolución de llamada de certificado tienen las siguientes firmas:

typedef struct _CERT_STORE_PROV_FIND_INFO {
    DWORD               cbSize;
    DWORD               dwMsgAndCertEncodingType;
    DWORD               dwFindFlags;
    DWORD               dwFindType;
    const void          *pvFindPara;
} CERT_STORE_PROV_FIND_INFO, *PCERT_STORE_PROV_FIND_INFO;
typedef const CERT_STORE_PROV_FIND_INFO CCERT_STORE_PROV_FIND_INFO,
    *PCCERT_STORE_PROV_FIND_INFO;

typedef BOOL (WINAPI *PFN_CERT_STORE_PROV_FIND_CERT)(
        IN HCERTSTOREPROV hStoreProv,
        IN PCCERT_STORE_PROV_FIND_INFO pFindInfo,
        IN PCCERT_CONTEXT pPrevCertContext,
        IN DWORD dwFlags,
        IN OUT void **ppvStoreProvFindInfo,
        OUT PCCERT_CONTEXT *ppProvCertContext
        );

typedef BOOL (WINAPI *PFN_CERT_STORE_PROV_FREE_FIND_CERT)(
        IN HCERTSTOREPROV hStoreProv,
        IN PCCERT_CONTEXT pCertContext,
        IN void *pvStoreProvFindInfo,
        IN DWORD dwFlags
        );

typedef BOOL (WINAPI *PFN_CERT_STORE_PROV_GET_CERT_PROPERTY)(
        IN HCERTSTOREPROV hStoreProv,
        IN PCCERT_CONTEXT pCertContext,
        IN DWORD dwPropId,
        IN DWORD dwFlags,
        OUT void *pvData,
        IN OUT DWORD *pcbData
        );

Las firmas de las funciones de devolución de llamada CRL y CTL son idénticas a las anteriores con el puntero al CERT_CONTEXT reemplazado por un puntero a un CRL_CONTEXT o CTL_CONTEXT.

Se llama a la devolución de llamada FIND_CERT cuando las API de almacén enumeran, buscan o agregan certificados. pPrevCertContext y ppvStoreProvFindInfo se establecen en NULL para iniciar una nueva búsqueda. El proveedor devuelve ppvStoreProvFindInfo devuelto en la siguiente búsqueda en la que el proveedor puede liberarlo. El proveedor puede establecer todas, algunas o ninguna de las propiedades del certificado. El proveedor tiene la opción de aplazar hasta que se llame a la devolución de llamada GET_CERT_PROPERTY. Se recomienda que los proveedores establezcan tantas propiedades como sea posible para permitir la copia en otro almacén.

Los siguientes tipos de búsqueda de certificados se admiten en CertFindCertificateInStore:

• CERT_FIND_ANY
• CERT_FIND_SHA1_HASH
• CERT_FIND_MD5_HASH
• CERT_FIND_PROPERTY
• CERT_FIND_PUBLIC_KEY
• CERT_FIND_SUBJECT_NAME
• CERT_FIND_SUBJECT_ATTR
• CERT_FIND_ISSUER_NAME
• CERT_FIND_ISSUER_ATTR
• CERT_FIND_SUBJECT_STR_A
• CERT_FIND_SUBJECT_STR_W
• CERT_FIND_ISSUER_STR_A
• CERT_FIND_ISSUER_STR_W
• CERT_FIND_KEY_SPEC
• CERT_FIND_ENHKEY_USAGE

Se llama a la devolución de llamada FIND_CERT para cada uno de los tipos de búsqueda anteriores. Los parámetros pasados a CertFindCertificateInStore se copian directamente en la estructura CERT_STORE_PROV_FIND_INFO antes de llamar a la devolución de llamada FIND_CERT. Para obtener más información sobre los valores de campo de los diferentes tipos de búsqueda de la estructura de CERT_STORE_PROV_FIND_INFO, consulte CertFindCertificateInStore.

Los siguientes tipos de búsqueda de certificados admiten las API CertGetSubjectCertificateFromStore y CertGetIssuerCertificateFromStore y ayudan a determinar si el certificado ya existe en el almacén antes de agregar:

• CERT_FIND_SUBJECT_CERT
• CERT_FIND_ISSUER_OF
• CERT_FIND_EXISTING

Para CERT_FIND_SUBJECT_CERT, el parámetro pvFindPara apunta a una estructura de CERT_INFO que contiene el emisor y serialNumber del asunto. Para CERT_FIND_ISSUER_OF, pvFindPara apunta a una estructura CERT_CONTEXT del asunto. Para CERT_FIND_EXISTING, pvFindPara apunta a un CERT_CONTEXT del certificado para comprobar su existencia en el almacén.

Se llama a la devolución de llamada FREE_FIND_CERT cuando el certificado devuelto por el FIND_CERT devolución de llamada no se ha publicado al usarse en un siguiente FIND_CERT posterior, lo que hace que su recuento de referencias se decremente en cero o se libere mediante una llamada a CertCloseStore. Antes de llamar a la devolución de llamada CLOSE, todos los certificados devueltos por el FIND_CERT devolución de llamada deben liberarse en el proveedor pasando a una llamada a la devolución de llamada de FIND_CERT o una llamada a la devolución de llamada FREE_FIND_CERT. Lo mismo se aplica a las devoluciones de llamada CRL y CTL.

CertGetCertificateContextProperty llama a la devolución de llamada GET_CERT_PROPERTY si no encuentra la propiedad especificada para el parámetro pCertContext. Lo mismo sucede con GET_CRL_PROPERTY y GET_CTL_PROPERTY.

Se llama a la devolución de llamada FIND_CRL cuando las API de almacén enumeran u obtienen CRL y antes de agregar una CRL. Se definirán los siguientes tipos de búsqueda crL:

Para CRL_FIND_ISSUED_BY, pvFindPara es un puntero a una CERT_CONTEXT del emisor crL. Para CRL_FIND_EXISTING, pvFindPara es un puntero a una CRL_CONTEXT de la CRL para determinar si ya existe en el almacén.

Se llama a la devolución de llamada FIND_CTL cuando las API de almacén enumeran o buscan CTL. Los siguientes tipos de búsqueda de CTL se admiten en CertFindCTLInStore:

• CTL_FIND_ANY
• CTL_FIND_SHA1_HASH
• CTL_FIND_MD5_HASH
• CTL_FIND_USAGE
• CTL_FIND_SUBJECT
• CTL_FIND_EXISTING

Se llama a la devolución de llamada FIND_CTL para cada uno de los tipos de búsqueda anteriores. Los parámetros pasados a CertFindCTLInStore se copian directamente en la estructura de CERT_STORE_PROV_FIND_INFO antes de llamar a la devolución de llamada FIND_CTL. Para obtener más información sobre los valores de campo de los diferentes tipos de búsqueda de la estructura de CERT_STORE_PROV_FIND_INFO, consulte CertFindCTLInStore.

El CTL_FIND_EXISTING tipo de búsqueda CTL ayuda a determinar si el CTL ya existe en el almacén antes de agregar un CTL.

Para CTL_FIND_EXISTING, pvFindPara es un puntero a la estructura CTL_CONTEXT del CTL para determinar si ya existe en el almacén.