Estensione della funzionalità CertOpenStore

L'archivio certificati è fondamentale per tutte le operazioni di gestione dei certificati. La funzionalità della funzione CertOpenStore può essere estesa tramite l'uso di una funzione del provider di archivi certificati installabile (o registrata). Per una panoramica di come installare o registrare funzioni da usare con CryptoAPI, vedere Panoramica dell'OID.

CertOpenStore apre un archivio vuoto in memoria e chiama la funzione del provider di archiviazione (se registrata o installata) usando l'identificatore di oggetto (OID) passato nel parametro lpszStoreProvider . Per un elenco dei tipi di provider predefiniti forniti con CryptoAPI, vedere CertOpenStore.

La funzione del provider di archivi copia i certificati e gli elenchi di revoche di certificati (CRL) nell'archivio in memoria specificato dall'handle hCertStore passato. La nuova funzione del provider di archivi può usare qualsiasi funzione dell'archivio certificati CryptoAPI, ad esempio CertAddCertificateContextToStore o CertAddSerializedElementToStore, per aggiungere i certificati e i CRL all'archivio in memoria. Inoltre, la funzione store-provider restituisce facoltativamente valori per tutti i membri dati della struttura CERT_STORE_PROV_INFO . La funzione deve aggiornare questa struttura solo se supporta funzioni di callback aggiuntive. Ad esempio, se l'archivio deve essere un archivio di sola lettura, il supporto di altre funzioni di callback probabilmente non sarebbe necessario. Per informazioni dettagliate e prototipi delle possibili funzioni di callback, vedere Funzioni di callback del provider dell'archivio certificati.

L'archivio TrustedPeople per utente è limitato a archivi fisici predefiniti. Non è possibile estendere l'archivio TrustedPeople per utente. Tuttavia, è possibile estendere l'archivio TrustedPeople del computer locale.

Windows XP e Windows Server 2003: L'archivio TrustedPeople per utente non è limitato agli archivi fisici predefiniti.

Uno dei membri dati della struttura CERT_STORE_PROV_INFO è la matrice rgpvStoreProvFunc . Se la funzione del provider di archiviazione deve supportare una o più funzioni di callback, deve fornire puntatori per questa matrice. Questi puntatori devono puntare alle funzioni di callback che devono essere usate per altre attività dell'archivio certificati, ad esempio la chiusura dell'archivio. La figura seguente illustra il flusso di questo processo.

Come illustrato nella figura seguente, dopo l'apertura dell'archivio, altre funzioni CryptoAPI (ad esempio CertCloseStore) usano la matrice di puntatori per accedere alle funzioni di callback che eseguono l'attività desiderata. La definizione della struttura di CERT_STORE_PROV_INFO e i prototipi delle funzioni di callback predefinite fornite con CryptoAPI vengono visualizzate nelle funzioni di callback del provider dell'archivio certificati.

Le API di archiviazione consentono a un provider di archivi di gestire i certificati, i CRL e gli elenchi di attendibilità certificati (CRL) all'esterno della cache dell'archivio (ad esempio, un database esterno di certificati, ad esempio fornito dal database del server di certificati Microsoft).

CertOpenStore invia tramite il parametro pszStoreProvider alla funzione del provider installabile CertDllOpenStoreProv appropriata. Il provider restituisce informazioni nel parametro pStoreProvInfo che punta a una struttura CERT_STORE_PROV_INFO . La struttura CERT_STORE_PROV_INFO contiene un membro dwStoreProvFlags . Il flag CERT_STORE_PROV_EXTERNAL_FLAG è stato aggiunto per consentire al provider di indicare che i certificati, i CRL e gli elenchi di scopi consentiti sono esterni alla cache dell'archivio.

CertDllOpenStoreProv restituisce una matrice di funzioni di callback. Un provider può implementare le funzioni di callback seguenti:

• 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

Nelle chiamate al WRITE_CERT, WRITE_CRL e WRITE_CTL funzioni di callback quando viene impostato il CERT_STORE_PROV_WRITE_ADD_FLAG, i 16 bit superiori del parametro dwFlags contengono il valore dwAddDisposition . Per supportare gli archivi esterni, un provider può implementare le funzioni di callback seguenti:

• 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

Le funzioni di callback del certificato hanno le firme seguenti:

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
        );

Le firme per le funzioni di callback CRL e CTL sono identiche a quella precedente con il puntatore al CERT_CONTEXT sostituito con un puntatore a un CRL_CONTEXT o a un CTL_CONTEXT.

Il callback FIND_CERT viene chiamato quando le API di archiviazione enumerare, trovare o aggiungere certificati. pPrevCertContext e ppvStoreProvFindInfo sono impostati su NULL per avviare una nuova ricerca. L'oggetto ppvStoreProvFindInfo restituito viene passato alla ricerca successiva in cui può essere liberata dal provider. Il provider può impostare tutte, alcune o nessuna delle proprietà del certificato. Il provider ha la possibilità di rinviare fino a quando non viene chiamato il callback GET_CERT_PROPERTY. È consigliabile che i provider impostino il maggior numero possibile di proprietà per consentire la copia in un altro archivio.

I tipi di ricerca dei certificati seguenti sono supportati in 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

Il callback FIND_CERT viene chiamato per ognuno dei tipi di ricerca precedenti. I parametri passati a CertFindCertificateInStore vengono copiati direttamente nella struttura CERT_STORE_PROV_FIND_INFO prima che venga chiamato il callback FIND_CERT. Per informazioni dettagliate sui valori dei campi per i diversi tipi di ricerca della struttura CERT_STORE_PROV_FIND_INFO, vedere CertFindCertificateInStore.

I tipi di ricerca dei certificati seguenti supportano le API CertGetSubjectCertificateFromStore e CertGetIssuerCertificateFromStore e consentono di determinare se il certificato esiste già nell'archivio prima di aggiungere:

• CERT_FIND_SUBJECT_CERT
• CERT_FIND_ISSUER_OF
• CERT_FIND_EXISTING

Per CERT_FIND_SUBJECT_CERT, il parametro pvFindPara punta a una struttura CERT_INFO che contiene l'emittente e serialNumber dell'oggetto. Per CERT_FIND_ISSUER_OF , pvFindPara punta a una struttura CERT_CONTEXT dell'oggetto. Per CERT_FIND_EXISTING , pvFindPara punta a un CERT_CONTEXT del certificato per verificarne l'esistenza nell'archivio.

Il callback FREE_FIND_CERT viene chiamato quando il certificato restituito dal callback FIND_CERT non è stato rilasciato in un FIND_CERT successivo successivo, con il relativo conteggio dei riferimenti decrementato su zero o tramite una chiamata a CertCloseStore. Prima di chiamare il callback CLOSE, tutti i certificati restituiti dal callback FIND_CERT devono essere rilasciati al provider passando a una chiamata al FIND_CERT callback o una chiamata al callback FREE_FIND_CERT. Lo stesso vale per i callback CRL e CTL.

Il callback GET_CERT_PROPERTY viene chiamato da CertGetCertificateContextProperty se non riesce a trovare la proprietà specificata per il parametro pCertContext . Lo stesso vale per GET_CRL_PROPERTY e GET_CTL_PROPERTY.

Il callback FIND_CRL viene chiamato quando le API di archiviazione enumerano o ottengono CRL e prima di aggiungere un CRL. Verranno definiti i tipi di ricerca CRL seguenti:

Per CRL_FIND_ISSUED_BY , pvFindPara è un puntatore a un CERT_CONTEXT dell'emittente CRL. Per CRL_FIND_EXISTING, pvFindPara è un puntatore a un CRL_CONTEXT del CRL per determinare se esiste già nell'archivio.

Il callback FIND_CTL viene chiamato quando le API di archiviazione enumerano o trovano elenchi di scopi consentiti. I tipi di ricerca CTL seguenti sono supportati in CertFindCTLInStore:

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

Il callback FIND_CTL viene chiamato per ognuno dei tipi di ricerca precedenti. I parametri passati a CertFindCTLInStore vengono copiati direttamente nella struttura CERT_STORE_PROV_FIND_INFO prima che venga chiamato il callback FIND_CTL. Per informazioni dettagliate sui valori dei campi per i diversi tipi di ricerca della struttura CERT_STORE_PROV_FIND_INFO, vedere CertFindCTLInStore.

Il tipo di ricerca CTL CTL_FIND_EXISTING consente di determinare se il CTL esiste già nell'archivio prima di eseguire un'aggiunta CTL.

Per CTL_FIND_EXISTING , pvFindPara è un puntatore alla struttura CTL_CONTEXT del CTL per determinare se esiste già nell'archivio.