CertFindCertificateInStore 関数 (wincrypt.h)

[アーティクル]
03/15/2023

CertFindCertificateInStore 関数は、dwFindType とそれに関連付けられている pvFindPara によって確立された検索条件に一致する証明書ストア内の最初または次の証明書コンテキストを検索します。この関数をループで使用すると、指定した検索条件に一致する証明書ストア内のすべての証明書を検索できます。

構文

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

パラメーター

[in] hCertStore

検索する証明書ストアのハンドル。

[in] dwCertEncodingType

使用するエンコードの種類を指定します。次の例に示すように、証明書とメッセージエンコードの両方の種類をビットごとの OR 操作と組み合わせて指定する必要があります。

X509_ASN_ENCODING |PKCS_7_ASN_ENCODING 現在定義されているエンコードの種類は次のとおりです。

X509_ASN_ENCODING
PKCS_7_ASN_ENCODING

[in] dwFindFlags

一部の dwFindType 値と共に使用して検索条件を変更します。ほとんどの dwFindType 値では、 dwFindFlags は使用されず、ゼロに設定する必要があります。詳細については、「解説」を参照してください。

[in] dwFindType

検索の種類を指定します。検索の種類によって、データ型、コンテンツ、 および pvFindPara の使用が決まります。このパラメーターには、次の値のいずれかを指定できます。

値	意味
CERT_FIND_ANY	pvFindPara のデータ型: NULL、使用されません。検索条件は使用されません。ストア内の次の証明書を返します。メモ証明書コンテキストの順序はストア内で保持されない場合があります。特定の証明書にアクセスするには、ストア内の証明書を反復処理する必要があります。
CERT_FIND_CERT_ID	pvFindPara のデータ型: 構造体CERT_ID。指定した CERT_IDによって識別される証明書を見つけます。
CERT_FIND_CTL_USAGE	pvFindPara のデータ型: 構造体CTL_USAGE。 szOID_ENHANCED_KEY_USAGE拡張機能を持つ証明書、またはCTL_USAGE構造体の pszUsageIdentifier メンバーと一致する CERT_CTL_PROP_ID を検索します。
CERT_FIND_ENHKEY_USAGE	pvFindPara のデータ型: 構造体CERT_ENHKEY_USAGE。拡張キー使用法拡張または拡張キー使用法プロパティと、CERT_ENHKEY_USAGE構造体の cUsageIdentifier メンバーと一致する使用状況識別子を持つストア内の証明書を検索します。 pszObjId メンバーが szOID_ENHANCED_KEY_USAGE に設定されたCERT_EXTENSION構造を持つ証明書には、拡張キー使用法拡張機能があります。証明書のCERT_ENHKEY_USAGE_PROP_ID識別子が設定されている場合、証明書には拡張キー使用法プロパティがあります。 CERT_FIND_OPTIONAL_ENHKEY_USAGE_FLAGが dwFindFlags で設定されている場合は、キー使用法の拡張機能またはプロパティのない証明書も一致します。このフラグの設定は、pvFindPara で NULL を渡すよりも優先されます。 CERT_FIND_EXT_ONLY_ENHKEY_USAGE_FLAGが設定されている場合は、キー使用法拡張機能でのみ一致が行われます。検索条件に対するフラグの変更については、「解説」を参照してください。
CERT_FIND_EXISTING	pvFindPara のデータ型: 構造体CERT_CONTEXT。指定した証明書コンテキストと完全に一致する証明書を検索します。
CERT_FIND_HASH	pvFindPara のデータ型: CRYPT_HASH_BLOB構造体。 CRYPT_HASH_BLOB構造内のハッシュと一致する SHA1 ハッシュを持つ証明書を検索します。
CERT_FIND_HAS_PRIVATE_KEY	pvFindPara のデータ型: NULL、使用されません。秘密キーを持つ証明書を検索します。キーは一時的なものでも、ディスクに保存することもできます。キーには、従来の Cryptography API (CAPI) キーまたは CNG キーを指定できます。メモ証明書コンテキストの順序はストア内で保持されない場合があります。そのため、特定の証明書にアクセスするには、すべての証明書を反復処理する必要があります。 Windows 8とWindows Server 2012: このフラグのサポートが開始されます。
CERT_FIND_ISSUER_ATTR	pvFindPara のデータ型: 構造体CERT_RDN。 CERT_RDN構造内の属性と一致する、指定された発行者属性を持つ証明書を検索します。これらの値が設定されている場合、関数は証明書内の発行者の属性を、このCERT_RDN構造体のCERT_RDN_ATTR配列の要素と比較します。比較では、証明書の発行者属性との一致を探す CERT_RDN_ATTR 属性を反復処理します。 CERT_RDN_ATTRの pszObjId メンバーが NULL の場合、属性オブジェクト識別子は無視されます。 CERT_RDN_ATTRの dwValueType メンバーがCERT_RDN_ANY_TYPEされている場合、値の型は無視されます。 CERT_RDN_VALUE_BLOBの pbData メンバーが NULL の場合、すべての値が一致します。現時点では、大文字と小文字を区別する正確な一致のみがサポートされています。 Unicode オプションの詳細については、「解説」を参照してください。これらの値を設定すると、検索は、エンコードの種類が dwCertEncodingType と一致する証明書に制限されます。
CERT_FIND_ISSUER_NAME	pvFindPara のデータ型: 構造体CERT_NAME_BLOB。 CERT_NAME_BLOB内の名前を持つ発行者名全体と完全に一致する証明書を検索します。検索は dwCertEncodingType と一致する証明書に制限されます。
CERT_FIND_ISSUER_OF	pvFindPara のデータ型: 構造体CERT_CONTEXT。 CERT_CONTEXTの発行者と一致するサブジェクトを持つ証明書を検索します。この値で CertFindCertificateInStore を使用する代わりに、 CertGetCertificateChain 関数を使用します。
CERT_FIND_ISSUER_STR	pvFindPara のデータ型: Null で終わる Unicode 文字列。指定した発行者名文字列を含む証明書を検索します。証明書の発行者メンバーは、CERT_SIMPLE_NAME_STR形式の適切な形式の CertNameToStr を使用して、適切な型の名前文字列に変換されます。次に、大文字と小文字を区別しない substring-within-a-string の一致が実行されます。この値を設定すると、検索は、エンコードの種類が dwCertEncodingType と一致する証明書に制限されます。部分文字列の一致が失敗し、件名に Punycode でエンコードされた文字列を含む電子メール RDN が含まれている場合は、 CERT_NAME_STR_ENABLE_PUNYCODE_FLAG を使用して件名を Unicode 文字列に変換し、部分文字列の一致が再度実行されます。
CERT_FIND_KEY_IDENTIFIER	pvFindPara のデータ型: CRYPT_HASH_BLOB構造体。 CRYPT_HASH_BLOBのキー識別子と一致するCERT_KEY_IDENTIFIER_PROP_ID プロパティを持つ証明書を検索します。
CERT_FIND_KEY_SPEC	pvFindPara のデータ型: キー指定を含む DWORD 変数。 pvFindPara のキー指定に一致するCERT_KEY_SPEC_PROP_ID プロパティを持つ証明書を検索します。
CERT_FIND_MD5_HASH	pvFindPara のデータ型: CRYPT_HASH_BLOB構造体。 CRYPT_HASH_BLOBのハッシュと一致する MD5 ハッシュを持つ証明書を検索します。
CERT_FIND_PROPERTY	pvFindPara のデータ型: プロパティ識別子を含む DWORD 変数。 pvFindPara の DWORD 値で指定されたプロパティ識別子と一致するプロパティを持つ証明書を検索します。
CERT_FIND_PUBLIC_KEY	pvFindPara のデータ型: 構造体CERT_PUBLIC_KEY_INFO。 CERT_PUBLIC_KEY_INFO構造の公開キーと一致する公開キーを持つ証明書を検索します。
CERT_FIND_SHA1_HASH	pvFindPara のデータ型: CRYPT_HASH_BLOB構造体。 CRYPT_HASH_BLOB構造内のハッシュと一致する SHA1 ハッシュを持つ証明書を検索します。
CERT_FIND_SIGNATURE_HASH	pvFindPara のデータ型: CRYPT_HASH_BLOB構造体。 CRYPT_HASH_BLOB構造の署名ハッシュと一致する署名ハッシュを持つ証明書を検索します。
CERT_FIND_SUBJECT_ATTR	pvFindPara のデータ型: CERT_RDN構造体。 CERT_RDN構造の属性と一致する指定されたサブジェクト属性を持つ証明書を検索します。 RDN 値が設定されている場合、この関数は、証明書内のサブジェクトの属性と、このCERT_RDN構造体のCERT_RDN_ATTR配列の要素を比較します。比較では、証明書のサブジェクトの属性との一致を探して、 CERT_RDN_ATTR 属性を反復処理します。 CERT_RDN_ATTR の pszObjId メンバーが NULL の場合、属性オブジェクト識別子は無視されます。 CERT_RDN_ATTR の dwValueType メンバーがCERT_RDN_ANY_TYPE場合、値の型は無視されます。 CERT_RDN_VALUE_BLOB の pbData メンバーが NULL の場合、値は一致します。現時点では、大文字と小文字を区別する正確な一致のみがサポートされています。 Unicode オプションの詳細については、「解説」を参照してください。これらの値を設定すると、検索は、エンコードの種類が dwCertEncodingType と一致する証明書に制限されます。
CERT_FIND_SUBJECT_CERT	pvFindPara のデータ型: CERT_INFO構造体。発行者とシリアル番号の両方を持つ証明書を検索し、 CERT_INFO 構造の発行者とシリアル番号に一致します。
CERT_FIND_SUBJECT_NAME	pvFindPara のデータ型: CERT_NAME_BLOB構造体。サブジェクト名全体と CERT_NAME_BLOB 構造の名前が完全に一致する証明書を検索します。検索は、 dwCertEncodingType の値と一致する証明書に制限されます。
CERT_FIND_SUBJECT_STR	pvFindPara のデータ型: Null で終わる Unicode 文字列。指定したサブジェクト名文字列を含む証明書を検索します。証明書のサブジェクトメンバーは、CERT_SIMPLE_NAME_STR形式の適切な形式の CertNameToStr を使用して、適切な型の名前文字列に変換されます。次に、大文字と小文字を区別しない部分文字列内の一致が実行されます。この値を設定すると、検索は、エンコードの種類が dwCertEncodingType と一致する証明書に制限されます。
CERT_FIND_CROSS_CERT_DIST_POINTS	pvFindPara のデータ型: 使用されません。クロス証明書配布ポイント拡張機能またはプロパティを持つ証明書を検索します。
CERT_FIND_PUBKEY_MD5_HASH	pvFindPara のデータ型: CRYPT_HASH_BLOB構造体。 MD5 ハッシュ公開キーが指定したハッシュと一致する証明書を検索します。

メモpvFindPara で文字列を渡す dwFindType の値には、代替形式があります。一方の形式では Unicode 文字列を使用し、もう 1 つの形式は ASCII 文字列を使用します。 "_W" で終わる値、またはサフィックスのない値は Unicode を使用します。 "_A" で終わる値は、ASCII 文字列を使用します。

[in] pvFindPara

dwFindType で使用されるデータ項目または構造体を指します。

[in] pPrevCertContext

この関数によって返される最後のCERT_CONTEXT 構造体へのポインター。このパラメーターは、関数の最初の呼び出しで NULL である必要があります。検索条件を満たす連続する証明書を検索するには、 pPrevCertContext を、関数の前の呼び出しによって返されたポインターに設定します。この関数は、このパラメーターの NULL 以外の値によって参照されるCERT_CONTEXTを解放します。

戻り値

関数が成功した場合、関数は読み取り専用のCERT_CONTEXT 構造体へのポインターを返します。

関数が失敗し、検索条件に一致する証明書が見つからない場合、戻り値は NULL になります。

CertFindCertificateInStore が返す NULL 以外のCERT_CONTEXTは、CertFreeCertificateContext によって解放されるか、CertFindCertificateInStore への後続の呼び出しで pPrevCertContext パラメーターとして渡される必要があります。

拡張エラー情報については、 GetLastError を呼び出します。考えられるエラーコードの一部を次に示します。

リターンコード	説明
CRYPT_E_NOT_FOUND	検索条件に一致する証明書が見つかりませんでした。これは、ストアが空であるか、ストアのリストの末尾に達した場合に発生する可能性があります。
E_INVALIDARG	hCertStore パラメーターのハンドルは、pPrevCertContext パラメーターが指す証明書コンテキストのハンドルと同じではないか、dwFindType パラメーターで無効な値が指定されました。

注釈

dwFindFlags パラメーターは、一部の検索の種類の条件を変更するために使用されます。

CERT_UNICODE_IS_RDN_ATTRS_FLAG dwFindFlags 値は、dwFindType のCERT_FIND_SUBJECT_ATTRとCERT_FIND_ISSUER_ATTRの値でのみ使用されます。 pvFindPara が指すCERT_RDN_ATTR構造体が Unicode 文字列で初期化された場合は、CERT_UNICODE_IS_RDN_ATTRS_FLAGを設定する必要があります。比較を行う前に、一致する文字列は、Unicode 比較を提供するために X509_UNICODE_NAME を使用して変換されます。

次の dwFindFlags 値は、 dwFindType のCERT_FIND_ENKEY_USAGE値でのみ使用されます。

CertDuplicateCertificateContext を呼び出して、返されるコンテキストの複製を作成できます。返されたコンテキストは、CertAddCertificateContextToStore を使用して別の証明書ストアに追加することも、CertAddCertificateLinkToStore を使用してコレクションストアではないストアにその証明書コンテキストへのリンクを追加することもできます。

返されたポインターは、関数の後続の呼び出しで pPrevCertContext パラメーターとして渡されると解放されます。それ以外の場合は、 CertFreeCertificateContext を呼び出して、ポインターを明示的に解放する必要があります。 NULL ではない pPrevCertContext は、関数にエラーがある場合でも、CertFreeCertificateContext の呼び出しを使用して CertFindCertificateInStore によって常に解放されます。

例

次の例は、検索条件を満たす証明書ストアで証明書コンテキストを検索する方法を示しています。この例のコンテキストを含む完全な例については、「 C プログラムの例: 証明書ストア操作」を参照してください。

この関数を使用する別の例については、「サンプル C プログラム: コレクションと兄弟証明書ストア操作」を参照してください。

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

要件

要件	値
サポートされている最小のクライアント	Windows XP [デスクトップアプリ \| UWP アプリ]
サポートされている最小のサーバー	Windows Server 2003 [デスクトップアプリのみ \| UWP アプリ]
対象プラットフォーム	Windows
ヘッダー	wincrypt.h
Library	Crypt32.lib
[DLL]	Crypt32.dll