CertFindCTLInStore 関数 (wincrypt.h)

[アーティクル]
08/27/2023

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

構文

PCCTL_CONTEXT CertFindCTLInStore(
  [in] HCERTSTORE    hCertStore,
  [in] DWORD         dwMsgAndCertEncodingType,
  [in] DWORD         dwFindFlags,
  [in] DWORD         dwFindType,
  [in] const void    *pvFindPara,
  [in] PCCTL_CONTEXT pPrevCtlContext
);

パラメーター

[in] hCertStore

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

[in] dwMsgAndCertEncodingType

CTL で使用されるエンコードの種類を指定します。次の例に示すように、証明書とメッセージエンコードの両方の種類をビットごとの OR 操作と組み合わせて指定することは、常に許容されます。

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

X509_ASN_ENCODING
PKCS_7_ASN_ENCODING

このパラメーターは、 dwFindType パラメーターが CTL_FIND_USAGE に設定されている場合にのみ使用されます。

[in] dwFindFlags

dwFindType が CTL_FIND_USAGE に設定されている場合に設定できます。詳細については、「CTL_FIND_USAGE、以下」のコメントを参照してください。

[in] dwFindType

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

値	意味
CTL_FIND_ANY	pvFindPara のデータ型: NULL。すべての CTL が一致します。
CTL_FIND_SHA1_HASH	pvFindPara のデータ型: CRYPT_HASH_BLOB。 CRYPT_HASH_BLOB構造体内のハッシュと一致するハッシュを持つ CTL が見つかりました。
CTL_FIND_MD5_HASH	pvFindPara のデータ型: CRYPT_HASH_BLOB。 CRYPT_HASH_BLOB構造体内のハッシュと一致するハッシュを持つ CTL が見つかりました。
CTL_FIND_USAGE	pvFindPara のデータ型: CTL_FIND_USAGE_PARA。使用識別子、リスト識別子、または署名者が、 CTL_FIND_USAGE_PARA 構造体の使用状況識別子、リスト識別子、または署名者と一致する CTL が見つかりました。 cUsageIdentifier メンバーが SubjectUsage サイズの場合、任意の CTL が一致します。 ListIdentifier メンバーの cbData メンバーが 0 の場合、リスト識別子は一致します。 ListIdentifier の cbData メンバーがCTL_FIND_NO_LIST_ID_CBDATA場合、リスト識別子のない CTL のみが一致します。 CTL_FIND_USAGE_PARA構造体の pSigner メンバーが NULL の場合、CTL 署名者は一致し、pSignerCERT_INFO構造体の Issuer メンバーと SerialNumber メンバーのみが使用されます。 pSigner がCTL_FIND_NO_SIGNER_PTR場合、署名者のない CTL のみが一致します。
CTL_FIND_SAME_USAGE_FLAG	pvFindPara のデータ型: CTL_FIND_USAGE_PARA。まったく同じ使用状況識別子を持つ CCTL のみが一致します。追加の使用状況識別子を持つ CCTL は一致しません。たとえば、 CTL_FIND_USAGE_PARA 構造体で "1.2.3" のみが指定されている場合、一致する場合、CTL には "1.2.3" のみを含める必要があり、追加の使用識別子は含めてはなりません。
CTL_FIND_EXISTING	pvFindPara のデータ型: PCCTL_CONTEXT。 CTL_CONTEXTと完全に一致する次の CRL を検索します。
CTL_FIND_SUBJECT	pvFindPara のデータ型: CTL_FIND_SUBJECT_PARA。指定されたサブジェクトを持つ CTL が見つかりました。 CertFindSubjectInCTL を呼び出して、CTL 内のサブジェクトのエントリへのポインターを取得できます。 CTL_FIND_SUBJECT_PARAの pUsagePara メンバーは、必要に応じて、CTL_FIND_USAGEで前述した照合を有効にするように設定できます。

[in] pvFindPara

dwFindType パラメーターに関連付けられている検索値へのポインター。

[in] pPrevCtlContext

この関数によって返される最後のCTL_CONTEXT へのポインター。ストア内の最初の CTL を取得するには 、NULL にする必要があります。連続する CCTL は、 pPrevCtlContext を前の関数呼び出しによって返された CTL_CONTEXT へのポインターに設定することによって取得されます。検索条件を満たしていない証明書、または CertDeleteCTLFromStore によって以前に削除された証明書はすべてスキップされます。この関数は、このパラメーターの NULL 以外の値によって参照されるCTL_CONTEXTを解放します。

戻り値

関数が成功した場合、戻り値は読み取り専用の CTL コンテキストへのポインターです。

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

リターンコード	説明
CRYPT_E_NOT_FOUND	ストアに CCTL が見つからなかったか、検索条件に一致する CTL が見つからなかったか、関数がストアのリストの末尾に達しました。
E_INVALIDARG	hCertStore パラメーターのハンドルは、pPrevCtlContext パラメーターが指す CTL コンテキストのハンドルと同じではありません。または、無効な値が dwFindType パラメーターで指定されました。

注釈

返されたポインターは、関数の後続の呼び出しで pPrevCtlContext として渡されると解放されます。それ以外の場合は、 CertFreeCTLContext を呼び出してポインターを解放する必要があります。関数に渡された NULL 以外の pPrevCtlContext は、関数がエラーを生成した場合でも、常に CertFreeCTLContext の呼び出しで解放されます。

CertDuplicateCTLContext を呼び出して、返されるコンテキストの複製を作成できます。返された CTL コンテキストは、 CertAddCTLContextToStore を使用して別の証明書ストアに追加することも、 CertAddCTLLinkToStore を使用してその CTL コンテキストへのリンクを非コレクションストアに追加することもできます。検索条件に一致する CTL が見つからない場合は、 NULL が返されます。

要件

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