CertFindCertificateInStore 関数 (wincrypt.h)

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識別子が設定されている場合、証明書には拡張キー使用法プロパティがあります。

dwFindFlagsでCERT_FIND_OPTIONAL_ENHKEY_USAGE_FLAGが設定 場合、キー使用法拡張機能またはプロパティのない証明書も一致します。 このフラグの設定は、pvFindParaNULL 渡すよりも優先されます。

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_ATTRpszObjId メンバーが NULL場合、属性オブジェクト識別子は無視されます。

CERT_RDN_ATTRdwValueType メンバーがCERT_RDN_ANY_TYPE場合、値の型は無視されます。

CERT_RDN_VALUE_BLOBpbData メンバーが 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 使用して、適切な型の名前文字列に変換されます。 その後、大文字と小文字を区別しない部分文字列の一致が実行されます。 この値を設定すると、検索は、エンコードの種類が 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_SHA1_SHA256_HASH
pvFindParaのデータ型: CRYPT_HASH_BLOB 構造体。

CRYPT_HASH_BLOB 構造体のハッシュと一致する SHA1 + SHA256 ハッシュを持つ証明書を検索します。

CERT_FIND_SHA256_HASH
pvFindParaのデータ型: CRYPT_HASH_BLOB 構造体。

CRYPT_HASH_BLOB 構造体のハッシュと一致する SHA256 ハッシュを持つ証明書を検索します。

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_ATTRpszObjId メンバーが NULL場合、属性オブジェクト識別子は無視されます。

CERT_RDN_ATTRdwValueType メンバーがCERT_RDN_ANY_TYPE場合、値の型は無視されます。

CERT_RDN_VALUE_BLOBpbData メンバーが 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 の値には別 形式があります。 1 つの形式では Unicode 文字列を使用し、もう 1 つは ASCII 文字列を使用します。 "_W" で終わる値、またはサフィックスのない値は Unicode を使用します。 "_A" で終わる値は、ASCII 文字列を使用します。
 

[in] pvFindPara

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

[in] pPrevCertContext

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

戻り値

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

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

CertFindCertificateInStore 返す以外の NULLCERT_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を設定する必要があります。 比較を行う前に、一致する文字列を X509_UNICODE_NAME を使用して変換し、Unicode 比較を提供します。

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

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

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

次の例は、検索条件を満たす証明書ストアで証明書コンテキストを見つける方法を示しています。 この例のコンテキストを含む完全な例については、「例 C Program: Certificate Store Operations」を参照してください。

この関数を使用する別の例については、「例 C Program: Collection and Sibling Certificate Store Operations」を参照してください。

#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 アプリ]
ターゲット プラットフォーム の ウィンドウズ
ヘッダー wincrypt.h
ライブラリ Crypt32.lib
DLL Crypt32.dll

関連項目

CERT_CONTEXT

CertAddCertificateContextToStore

CertAddCertificateLinkToStore

CertDuplicateCertificateContext

CertEnumCertificatesInStore

CertFreeCertificateContext

CertGetCertificateChain

CertNameToStr

証明書関数の