CertOpenStore 機能の拡張

証明書ストアは、すべての証明書管理操作の中心です。 CertOpenStore 関数の機能は、インストール可能 (または登録済み) の証明書ストア プロバイダー関数を使用して拡張できます。 CryptoAPI で使用する関数をインストールまたは登録する方法の概要については、「OID の 概要」を参照してください。

CertOpenStore はメモリ内の空のストアを開き、lpszStoreProvider パラメーターで渡されたオブジェクト識別子 (OID) を使用してストア プロバイダー関数を呼び出します (登録またはインストールされている場合)。 CryptoAPI に付属する定義済みのプロバイダーの種類の一覧については、「 CertOpenStore」を参照してください。

ストア プロバイダー関数は、その証明書と 証明書失効リスト (CRL) を、渡された hCertStore ハンドルで指定されたメモリ内ストアにコピーします。 新しいストア プロバイダー関数では、 CertAddCertificateContextToStore や CertAddSerializedElementToStore などの任意の CryptoAPI 証明書ストア関数を使用して、証明書と CRL をメモリ内ストアに追加できます。 さらに、ストア プロバイダー関数は、必要に応じて 、CERT_STORE_PROV_INFO 構造体のすべてのデータ メンバーの値を返します。 関数は、追加のコールバック関数をサポートしている場合にのみ、この構造体を更新する必要があります。 たとえば、ストアが読み取り専用ストアである場合、他のコールバック関数のサポートはおそらく必要ありません。 可能なコールバック関数の詳細とプロトタイプについては、「 証明書ストア プロバイダーコールバック関数」を参照してください。

ユーザーごとの TrustedPeople ストアは、定義済みの物理ストアに制限されます。 ユーザーごとの TrustedPeople ストアを拡張することはできません。 ただし、ローカル コンピューターの TrustedPeople ストアを拡張することはできます。

Windows XP および Windows Server 2003: ユーザーごとの TrustedPeople ストアは、定義済みの物理ストアに制限されません。

CERT_STORE_PROV_INFO 構造体のデータ メンバーの 1 つは、rgpvStoreProvFunc 配列です。 ストア プロバイダー関数が 1 つ以上のコールバック関数をサポートする必要がある場合は、この配列のポインターを提供する必要があります。 これらのポインターは、他の証明書ストア アクティビティ (ストアの閉じるなど) に使用されるコールバック関数を指す必要があります。 次の図は、このプロセスのフローを示しています。

次の図に示すように、ストアを開いた後、他の CryptoAPI 関数 ( CertCloseStore など) はポインターの配列を使用して、目的のタスクを実行するコールバック関数にアクセスします。 CryptoAPI で提供される既定のコールバック関数のCERT_STORE_PROV_INFO構造とプロトタイプの定義は、「証明書ストア プロバイダー コールバック関数」に示されています。

ストア API を使用すると、ストア プロバイダーは、ストアのキャッシュの外部 (たとえば、Microsoft 証明書サーバー データベースによって提供される証明書の外部データベース) の外部にある証明書、CRL、および証明書 信頼リスト (CCTL) を維持できます。

CertOpenStore は 、pszStoreProvider パラメーターを介して、適切な CertDllOpenStoreProv インストール可能プロバイダー関数にディスパッチします。 プロバイダーは、CERT_STORE_PROV_INFO構造体を指す pStoreProvInfo パラメーターの情報を返します。 CERT_STORE_PROV_INFO構造体には dwStoreProvFlags メンバーが含まれています。 証明書、CRL、および CCTL がストアのキャッシュの外部にあることをプロバイダーが示せるように、CERT_STORE_PROV_EXTERNAL_FLAG フラグが追加されました。

CertDllOpenStoreProv は コールバック関数の配列を返します。 プロバイダーは、次のコールバック関数を実装できます。

• 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

CERT_STORE_PROV_WRITE_ADD_FLAGが設定されている場合、WRITE_CERT、WRITE_CRL、およびWRITE_CTLコールバック関数の呼び出しでは、 dwFlags パラメーターの上位 16 ビットに dwAddDisposition 値が含まれます。 外部ストアをサポートするために、プロバイダーは次のコールバック関数を実装できます。

• 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

証明書コールバック関数には、次の署名があります。

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

CRL および CTL コールバック関数のシグネチャは、上記と同じですが、CERT_CONTEXTへのポインターは、CRL_CONTEXTまたはCTL_CONTEXTへのポインターに置き換えられます。

ストア API が証明書を列挙、検索、または追加すると、FIND_CERT コールバックが呼び出されます。 新しい FIND を開始するには、pPrevCertContext と ppvStoreProvFindInfo が NULL に設定されます。 返された ppvStoreProvFindInfo は、プロバイダーによって解放される可能性がある次の検索で返されます。 プロバイダーは、証明書のプロパティのすべて、一部、またはいずれも設定できない場合があります。 プロバイダーには、GET_CERT_PROPERTY コールバックが呼び出されるまで延期するオプションがあります。 プロバイダーは、別のストアへのコピーを許可するために、できるだけ多くのプロパティを設定することをお勧めします。

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

上記の検索の種類ごとに、FIND_CERT コールバックが呼び出されます。 CertFindCertificateInStore に渡されるパラメーターは、FIND_CERT コールバックが呼び出される前に、CERT_STORE_PROV_FIND_INFO構造体に直接コピーされます。 CERT_STORE_PROV_FIND_INFO構造体のさまざまな検索型のフィールド値の詳細については、「 CertFindCertificateInStore」を参照してください。

次の証明書検索の種類では 、CertGetSubjectCertificateFromStore API と CertGetIssuerCertificateFromStore API がサポートされており、追加する前に証明書がストアに既に存在するかどうかを判断するのに役立ちます。

• CERT_FIND_SUBJECT_CERT
• CERT_FIND_ISSUER_OF
• CERT_FIND_EXISTING

CERT_FIND_SUBJECT_CERTの場合、 pvFindPara パラメーターは、サブジェクトの Issuer と SerialNumber を含む CERT_INFO 構造体を指します。 CERT_FIND_ISSUER_OFの場合、 pvFindPara は 件名の CERT_CONTEXT 構造体を指します。 CERT_FIND_EXISTINGの場合、pvFindPara は証明書のCERT_CONTEXTを指し、ストア内に存在することをチェックします。

FREE_FIND_CERT コールバックは、FIND_CERT コールバックによって返された証明書が、後続の次のFIND_CERTで使用され、したがって 参照カウント が 0 にデクリメントされるか、 CertCloseStore の呼び出しによって解放されることによって解放されなかった場合に呼び出されます。 CLOSE コールバックが呼び出される前に、FIND_CERT コールバックによって返されるすべての証明書が、FIND_CERT コールバックの呼び出しまたはFREE_FIND_CERT コールバックの呼び出しに渡されることによって、プロバイダーに解放される必要があります。 CRL および CTL コールバックにも同じことが当てはまります。

GET_CERT_PROPERTYコールバックは、pCertContext パラメーターの指定されたプロパティが見つからない場合、CertGetCertificateContextProperty によって呼び出されます。 GET_CRL_PROPERTYとGET_CTL_PROPERTYについても同様です。

ストア API が CRL を列挙または取得するとき、および CRL を追加する前に、FIND_CRL コールバックが呼び出されます。 次の CRL 検索の種類が定義されます。

CRL_FIND_ISSUED_BYの場合、 pvFindPara は CRL 発行者の CERT_CONTEXT へのポインターです。 CRL_FIND_EXISTINGの場合、 pvFindPara は CRL の CRL_CONTEXT へのポインターであり、ストアに既に存在するかどうかを判断します。

ストア API が CCTL を列挙または検索すると、FIND_CTL コールバックが呼び出されます。 CertFindCTLInStore では、次の CTL 検索の種類がサポートされています。

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

上記の検索の種類ごとに、FIND_CTL コールバックが呼び出されます。 CertFindCTLInStore に渡されるパラメーターは、FIND_CTL コールバックが呼び出される前に、CERT_STORE_PROV_FIND_INFO構造体に直接コピーされます。 CERT_STORE_PROV_FIND_INFO構造体のさまざまな検索型のフィールド値の詳細については、「 CertFindCTLInStore」を参照してください。

CTL_FIND_EXISTING CTL 検索の種類は、CTL の追加を実行する前に、ストアに CTL が既に存在するかどうかを判断するのに役立ちます。

CTL_FIND_EXISTINGの場合、 pvFindPara は CTL の CTL_CONTEXT 構造へのポインターであり、ストアに既に存在するかどうかを判断します。