ホーム › Security.Cryptography › CertFindCTLInStore

CertFindCTLInStore

関数

指定条件に合致するCTLをストアから検索する。

DLLCRYPT32.dll呼出規約winapiSetLastErrorあり対応OSWindows XP 以降

シグネチャ

// CRYPT32.dll
#include <windows.h>

CTL_CONTEXT* CertFindCTLInStore(
    HCERTSTORE hCertStore,
    DWORD dwMsgAndCertEncodingType,
    DWORD dwFindFlags,
    CERT_FIND_TYPE dwFindType,
    const void* pvFindPara,   // optional
    CTL_CONTEXT* pPrevCtlContext   // optional
);

パラメーター

名前

型

方向

説明

hCertStore

HCERTSTORE

検索対象となる証明書ストアのハンドル。

dwMsgAndCertEncodingType

DWORD

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

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

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

dwFindFlags

DWORD

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

dwFindType

CERT_FIND_TYPE

実行する検索の種類を指定します。検索の種類によって、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 署名者が一致し、pSigner の CERT_INFO 構造体内の Issuer メンバーと SerialNumber メンバーのみが使用されます。pSigner が CTL_FIND_NO_SIGNER_PTR の場合、署名者を持たない CTL のみが一致します。
CTL_FIND_SAME_USAGE_FLAG	pvFindPara のデータ型: CTL_FIND_USAGE_PARA。まったく同じ使用法識別子を持つ CTL のみが一致します。追加の使用法識別子を持つ CTL は一致しません。たとえば、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 で説明した一致処理を有効にできます (省略可能)。

pvFindPara

void*

inoptional

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

pPrevCtlContext

CTL_CONTEXT*

inoptional

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

戻り値の型: CTL_CONTEXT*

公式ドキュメント

dwFindType とそれに関連付けられた pvFindPara で指定された検索条件に一致する、最初または次の証明書信頼リスト (CTL) コンテキストを検索します。

戻り値

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

拡張エラー情報を取得するには、 GetLastError を呼び出します。発生する可能性のあるエラーコードを次に示します。

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

解説(Remarks)

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

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

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// CRYPT32.dll
#include <windows.h>

CTL_CONTEXT* CertFindCTLInStore(
    HCERTSTORE hCertStore,
    DWORD dwMsgAndCertEncodingType,
    DWORD dwFindFlags,
    CERT_FIND_TYPE dwFindType,
    const void* pvFindPara,   // optional
    CTL_CONTEXT* pPrevCtlContext   // optional
);

[DllImport("CRYPT32.dll", SetLastError = true, ExactSpelling = true)]
static extern IntPtr CertFindCTLInStore(
    IntPtr hCertStore,   // HCERTSTORE
    uint dwMsgAndCertEncodingType,   // DWORD
    uint dwFindFlags,   // DWORD
    uint dwFindType,   // CERT_FIND_TYPE
    IntPtr pvFindPara,   // void* optional
    IntPtr pPrevCtlContext   // CTL_CONTEXT* optional
);

<DllImport("CRYPT32.dll", SetLastError:=True, ExactSpelling:=True)>
Public Shared Function CertFindCTLInStore(
    hCertStore As IntPtr,   ' HCERTSTORE
    dwMsgAndCertEncodingType As UInteger,   ' DWORD
    dwFindFlags As UInteger,   ' DWORD
    dwFindType As UInteger,   ' CERT_FIND_TYPE
    pvFindPara As IntPtr,   ' void* optional
    pPrevCtlContext As IntPtr   ' CTL_CONTEXT* optional
) As IntPtr
End Function

' hCertStore : HCERTSTORE
' dwMsgAndCertEncodingType : DWORD
' dwFindFlags : DWORD
' dwFindType : CERT_FIND_TYPE
' pvFindPara : void* optional
' pPrevCtlContext : CTL_CONTEXT* optional
Declare PtrSafe Function CertFindCTLInStore Lib "crypt32" ( _
    ByVal hCertStore As LongPtr, _
    ByVal dwMsgAndCertEncodingType As Long, _
    ByVal dwFindFlags As Long, _
    ByVal dwFindType As Long, _
    ByVal pvFindPara As LongPtr, _
    ByVal pPrevCtlContext As LongPtr) As LongPtr
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

CertFindCTLInStore = ctypes.windll.crypt32.CertFindCTLInStore
CertFindCTLInStore.restype = ctypes.c_void_p
CertFindCTLInStore.argtypes = [
    wintypes.HANDLE,  # hCertStore : HCERTSTORE
    wintypes.DWORD,  # dwMsgAndCertEncodingType : DWORD
    wintypes.DWORD,  # dwFindFlags : DWORD
    wintypes.DWORD,  # dwFindType : CERT_FIND_TYPE
    ctypes.POINTER(None),  # pvFindPara : void* optional
    ctypes.c_void_p,  # pPrevCtlContext : CTL_CONTEXT* optional
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('CRYPT32.dll')
CertFindCTLInStore = Fiddle::Function.new(
  lib['CertFindCTLInStore'],
  [
    Fiddle::TYPE_VOIDP,  # hCertStore : HCERTSTORE
    -Fiddle::TYPE_INT,  # dwMsgAndCertEncodingType : DWORD
    -Fiddle::TYPE_INT,  # dwFindFlags : DWORD
    -Fiddle::TYPE_INT,  # dwFindType : CERT_FIND_TYPE
    Fiddle::TYPE_VOIDP,  # pvFindPara : void* optional
    Fiddle::TYPE_VOIDP,  # pPrevCtlContext : CTL_CONTEXT* optional
  ],
  Fiddle::TYPE_VOIDP)

#[link(name = "crypt32")]
extern "system" {
    fn CertFindCTLInStore(
        hCertStore: *mut core::ffi::c_void,  // HCERTSTORE
        dwMsgAndCertEncodingType: u32,  // DWORD
        dwFindFlags: u32,  // DWORD
        dwFindType: u32,  // CERT_FIND_TYPE
        pvFindPara: *const (),  // void* optional
        pPrevCtlContext: *mut CTL_CONTEXT  // CTL_CONTEXT* optional
    ) -> *mut CTL_CONTEXT;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("CRYPT32.dll", SetLastError = true)]
public static extern IntPtr CertFindCTLInStore(IntPtr hCertStore, uint dwMsgAndCertEncodingType, uint dwFindFlags, uint dwFindType, IntPtr pvFindPara, IntPtr pPrevCtlContext);
"@
$api = Add-Type -MemberDefinition $sig -Name 'CRYPT32_CertFindCTLInStore' -Namespace Win32 -PassThru
# $api::CertFindCTLInStore(hCertStore, dwMsgAndCertEncodingType, dwFindFlags, dwFindType, pvFindPara, pPrevCtlContext)

#uselib "CRYPT32.dll"
#func global CertFindCTLInStore "CertFindCTLInStore" sptr, sptr, sptr, sptr, sptr, sptr
; CertFindCTLInStore hCertStore, dwMsgAndCertEncodingType, dwFindFlags, dwFindType, pvFindPara, varptr(pPrevCtlContext)   ; 戻り値は stat
; hCertStore : HCERTSTORE -> "sptr"
; dwMsgAndCertEncodingType : DWORD -> "sptr"
; dwFindFlags : DWORD -> "sptr"
; dwFindType : CERT_FIND_TYPE -> "sptr"
; pvFindPara : void* optional -> "sptr"
; pPrevCtlContext : CTL_CONTEXT* optional -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "CRYPT32.dll"
#cfunc global CertFindCTLInStore "CertFindCTLInStore" sptr, int, int, int, sptr, var
; res = CertFindCTLInStore(hCertStore, dwMsgAndCertEncodingType, dwFindFlags, dwFindType, pvFindPara, pPrevCtlContext)
; hCertStore : HCERTSTORE -> "sptr"
; dwMsgAndCertEncodingType : DWORD -> "int"
; dwFindFlags : DWORD -> "int"
; dwFindType : CERT_FIND_TYPE -> "int"
; pvFindPara : void* optional -> "sptr"
; pPrevCtlContext : CTL_CONTEXT* optional -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "CRYPT32.dll"
#cfunc global CertFindCTLInStore "CertFindCTLInStore" sptr, int, int, int, sptr, sptr
; res = CertFindCTLInStore(hCertStore, dwMsgAndCertEncodingType, dwFindFlags, dwFindType, pvFindPara, varptr(pPrevCtlContext))
; hCertStore : HCERTSTORE -> "sptr"
; dwMsgAndCertEncodingType : DWORD -> "int"
; dwFindFlags : DWORD -> "int"
; dwFindType : CERT_FIND_TYPE -> "int"
; pvFindPara : void* optional -> "sptr"
; pPrevCtlContext : CTL_CONTEXT* optional -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。