ホーム › Security.Cryptography › CertVerifyCTLUsage

CertVerifyCTLUsage

関数

サブジェクトが指定したCTL使用法に適合するか検証する。

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

シグネチャ

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

BOOL CertVerifyCTLUsage(
    DWORD dwEncodingType,
    DWORD dwSubjectType,
    void* pvSubject,
    CTL_USAGE* pSubjectUsage,
    DWORD dwFlags,
    CTL_VERIFY_USAGE_PARA* pVerifyUsagePara,   // optional
    CTL_VERIFY_USAGE_STATUS* pVerifyUsageStatus
);

パラメーター

名前	型	方向	説明
dwEncodingType	DWORD	in	使用するエンコーディングの種類を指定します。現在は X509_ASN_ENCODING と PKCS_7_ASN_ENCODING のみが使用されますが、将来追加のエンコーディングの種類が追加される可能性があります。現在のいずれのエンコーディングの種類についても、次を使用してください。 X509_ASN_ENCODING \| PKCS_7_ASN_ENCODING。
dwSubjectType	DWORD	in	dwSubjectType パラメーターが CTL_CERT_SUBJECT_TYPE に設定されている場合、pvSubject は CERT_CONTEXT 構造体を指します。この構造体の SubjectAlgorithm メンバーが調べられ、サブジェクトの識別情報の表現方法が決定されます。当初は SubjectAlgorithm の値として SHA1 と MD5 のハッシュのみがサポートされます。該当するハッシュプロパティが CERT_CONTEXT 構造体から取得されます。 dwSubjectType パラメーターが CTL_ANY_SUBJECT_TYPE に設定されている場合、pvSubject は CTL_ANY_SUBJECT_INFO 構造体を指します。この構造体の SubjectAlgorithm メンバーは CTL のアルゴリズムの種類と一致している必要があり、SubjectIdentifier メンバーはいずれかの CTL エントリと一致している必要があります。 dwSubjectType が上記いずれかの値に設定されている場合、dwEncodingType は使用されません。
pvSubject	void*	in	dwSubjectType パラメーターと組み合わせて使用される値です。
pSubjectUsage	CTL_USAGE*	in	サブジェクトの想定される使用法を指定するために使用する CTL_USAGE 構造体へのポインターです。
dwFlags	DWORD	in	CERT_VERIFY_INHIBIT_CTL_UPDATE_FLAG が設定されていない場合、 CTL_VERIFY_USAGE_PARA の rghCtlStore で指定されたいずれかのストア内にある、有効期間が切れた CTL が置き換えられることがあります。置き換えられた場合、pVerifyUsageStatus の dwFlags メンバーに CERT_VERIFY_UPDATED_CTL_FLAG が設定されます。このフラグが設定されている場合、ストア内にあって有効期間が切れた CTL に対して、有効期間内の更新済み CTL を受信したとしても更新は行われません。 CERT_VERIFY_TRUSTED_SIGNERS_FLAG が設定されている場合、署名者を見つけるために CTL_VERIFY_USAGE_PARA の rghSignerStore で指定された署名者ストアのみが検索されます。設定されていない場合、署名者ストアは署名者の証明書を見つけるための追加の検索元として利用されます。詳細については「解説」を参照してください。 CERT_VERIFY_NO_TIME_CHECK_FLAG が設定されている場合、CTL の有効期間チェックは行われません。設定されていない場合は行われます。 CERT_VERIFY_ALLOW_MORE_USAGE_FLAG が設定されている場合、CTL は pSubjectUsage で指定された使用法識別子に加えて、その他の使用法識別子を含むことができます。設定されていない場合、見つかった CTL には追加の使用法識別子は含まれません。
pVerifyUsagePara	CTL_VERIFY_USAGE_PARA*	inoptional	CTL を見つけるために検索するストアと、許容される CTL 署名者を含むストアを指定する CTL_VERIFY_USAGE_PARA 構造体へのポインターです。ListIdentifier メンバーを設定すると、検索がさらに限定されます。
pVerifyUsageStatus	CTL_VERIFY_USAGE_STATUS*	inout	CTL_VERIFY_USAGE_STATUS 構造体へのポインターです。CertVerifyCTLUsage を呼び出す前に、この構造体の cbSize メンバーを構造体のサイズ (バイト単位) に設定し、その他のすべてのフィールドをゼロに設定する必要があります。詳細については CTL_VERIFY_USAGE_STATUS を参照してください。

戻り値の型: BOOL

公式ドキュメント

使用法識別子を含み、署名され、かつ有効期間内である証明書信頼リスト (CTL: certificate trust list) を検索することで、サブジェクトが指定された使用法において信頼されていることを検証します。

戻り値

サブジェクトが指定された使用法において信頼されている場合は TRUE が返されます。それ以外の場合は FALSE が返されます。GetLastError は次のいずれかのエラーコードを返すことがあります。

値	説明
CRYPT_E_NO_VERIFY_USAGE_DLL	サブジェクトの使用法を検証するための DLL またはエクスポート関数が見つかりませんでした。
CRYPT_E_NO_VERIFY_USAGE_CHECK	呼び出された関数がサブジェクトに対して使用法チェックを実行できませんでした。
CRYPT_E_VERIFY_USAGE_OFFLINE	サーバーがオフラインであったため、呼び出された関数が使用法チェックを完了できませんでした。
CRYPT_E_NOT_IN_CTL	サブジェクトが CTL 内に見つかりませんでした。
CRYPT_E_NO_TRUSTED_SIGNER	メッセージまたは信頼リストの署名を検証するための信頼された署名者が見つかりませんでした。

pVerifyUsageStatus が指す CTL_VERIFY_USAGE_PARA の dwError メンバーには、同じエラーコードが設定されます。

解説(Remarks)

CertVerifyCTLUsage は、オブジェクト識別子 (OID) を使用してインストールできる関数へのディスパッチャーです。まず、pSubjectUsage が指す CLT_USAGE 構造体内の最初の使用法オブジェクト識別子に一致する OID 関数を見つけようとします。これに失敗した場合、既定の CertDllVerifyCTLUsage 関数を使用します。

Cryptnet.dll 内の CertDllVerifyCTLUsage 関数は OID を使用してインストールでき、次の特性を持ちます。

pVerifyUsagePara の rghCtlStore で CTL ストアが指定されている場合、CTL を見つけるためにそれらのストアのみが検索されます。指定されていない場合、CTL を見つけるために Trust システムストアが検索されます。
CERT_VERIFY_TRUSTED_SIGNERS_FLAG が設定されている場合、署名者の発行者とシリアル番号に対応する証明書を見つけるために、pVerifyUsagePara の rghSignerStore で指定された署名者ストアのみが検索されます。設定されていない場合、署名者の証明書を見つけるために、CTL メッセージのストア、pVerifyUsagePara の rghSignerStore で指定された署名者ストア、Trust システムストア、CA システムストア、ROOT、およびソフトウェア発行元証明書 (SPC: Software Publisher Certificate) システムストアが検索されます。いずれの場合も、見つかった証明書内の公開鍵を使用して CTL の署名が検証されます。
CTL に NextUpdate メンバーが設定されており、CERT_VERIFY_NO_TIME_CHECK が設定されていない場合、有効期間が検証されます。
ストアから取得した CTL の有効期間が切れている場合、有効期間内のバージョンを取得する試みが行われます。CertDllVerifyCTLUsage 関数は、CTL の NextUpdateLocation プロパティまたは NextUpdateLocation 拡張を使用するか、署名者の情報から NextUpdateLocation 属性を検索します。

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

各言語での呼び出し定義

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

BOOL CertVerifyCTLUsage(
    DWORD dwEncodingType,
    DWORD dwSubjectType,
    void* pvSubject,
    CTL_USAGE* pSubjectUsage,
    DWORD dwFlags,
    CTL_VERIFY_USAGE_PARA* pVerifyUsagePara,   // optional
    CTL_VERIFY_USAGE_STATUS* pVerifyUsageStatus
);

[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("CRYPT32.dll", SetLastError = true, ExactSpelling = true)]
static extern bool CertVerifyCTLUsage(
    uint dwEncodingType,   // DWORD
    uint dwSubjectType,   // DWORD
    IntPtr pvSubject,   // void*
    IntPtr pSubjectUsage,   // CTL_USAGE*
    uint dwFlags,   // DWORD
    IntPtr pVerifyUsagePara,   // CTL_VERIFY_USAGE_PARA* optional
    IntPtr pVerifyUsageStatus   // CTL_VERIFY_USAGE_STATUS* in/out
);

<DllImport("CRYPT32.dll", SetLastError:=True, ExactSpelling:=True)>
Public Shared Function CertVerifyCTLUsage(
    dwEncodingType As UInteger,   ' DWORD
    dwSubjectType As UInteger,   ' DWORD
    pvSubject As IntPtr,   ' void*
    pSubjectUsage As IntPtr,   ' CTL_USAGE*
    dwFlags As UInteger,   ' DWORD
    pVerifyUsagePara As IntPtr,   ' CTL_VERIFY_USAGE_PARA* optional
    pVerifyUsageStatus As IntPtr   ' CTL_VERIFY_USAGE_STATUS* in/out
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

' dwEncodingType : DWORD
' dwSubjectType : DWORD
' pvSubject : void*
' pSubjectUsage : CTL_USAGE*
' dwFlags : DWORD
' pVerifyUsagePara : CTL_VERIFY_USAGE_PARA* optional
' pVerifyUsageStatus : CTL_VERIFY_USAGE_STATUS* in/out
Declare PtrSafe Function CertVerifyCTLUsage Lib "crypt32" ( _
    ByVal dwEncodingType As Long, _
    ByVal dwSubjectType As Long, _
    ByVal pvSubject As LongPtr, _
    ByVal pSubjectUsage As LongPtr, _
    ByVal dwFlags As Long, _
    ByVal pVerifyUsagePara As LongPtr, _
    ByVal pVerifyUsageStatus As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

CertVerifyCTLUsage = ctypes.windll.crypt32.CertVerifyCTLUsage
CertVerifyCTLUsage.restype = wintypes.BOOL
CertVerifyCTLUsage.argtypes = [
    wintypes.DWORD,  # dwEncodingType : DWORD
    wintypes.DWORD,  # dwSubjectType : DWORD
    ctypes.POINTER(None),  # pvSubject : void*
    ctypes.c_void_p,  # pSubjectUsage : CTL_USAGE*
    wintypes.DWORD,  # dwFlags : DWORD
    ctypes.c_void_p,  # pVerifyUsagePara : CTL_VERIFY_USAGE_PARA* optional
    ctypes.c_void_p,  # pVerifyUsageStatus : CTL_VERIFY_USAGE_STATUS* in/out
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('CRYPT32.dll')
CertVerifyCTLUsage = Fiddle::Function.new(
  lib['CertVerifyCTLUsage'],
  [
    -Fiddle::TYPE_INT,  # dwEncodingType : DWORD
    -Fiddle::TYPE_INT,  # dwSubjectType : DWORD
    Fiddle::TYPE_VOIDP,  # pvSubject : void*
    Fiddle::TYPE_VOIDP,  # pSubjectUsage : CTL_USAGE*
    -Fiddle::TYPE_INT,  # dwFlags : DWORD
    Fiddle::TYPE_VOIDP,  # pVerifyUsagePara : CTL_VERIFY_USAGE_PARA* optional
    Fiddle::TYPE_VOIDP,  # pVerifyUsageStatus : CTL_VERIFY_USAGE_STATUS* in/out
  ],
  Fiddle::TYPE_INT)

#[link(name = "crypt32")]
extern "system" {
    fn CertVerifyCTLUsage(
        dwEncodingType: u32,  // DWORD
        dwSubjectType: u32,  // DWORD
        pvSubject: *mut (),  // void*
        pSubjectUsage: *mut CTL_USAGE,  // CTL_USAGE*
        dwFlags: u32,  // DWORD
        pVerifyUsagePara: *mut CTL_VERIFY_USAGE_PARA,  // CTL_VERIFY_USAGE_PARA* optional
        pVerifyUsageStatus: *mut CTL_VERIFY_USAGE_STATUS  // CTL_VERIFY_USAGE_STATUS* in/out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("CRYPT32.dll", SetLastError = true)]
public static extern bool CertVerifyCTLUsage(uint dwEncodingType, uint dwSubjectType, IntPtr pvSubject, IntPtr pSubjectUsage, uint dwFlags, IntPtr pVerifyUsagePara, IntPtr pVerifyUsageStatus);
"@
$api = Add-Type -MemberDefinition $sig -Name 'CRYPT32_CertVerifyCTLUsage' -Namespace Win32 -PassThru
# $api::CertVerifyCTLUsage(dwEncodingType, dwSubjectType, pvSubject, pSubjectUsage, dwFlags, pVerifyUsagePara, pVerifyUsageStatus)

#uselib "CRYPT32.dll"
#func global CertVerifyCTLUsage "CertVerifyCTLUsage" sptr, sptr, sptr, sptr, sptr, sptr, sptr
; CertVerifyCTLUsage dwEncodingType, dwSubjectType, pvSubject, varptr(pSubjectUsage), dwFlags, varptr(pVerifyUsagePara), varptr(pVerifyUsageStatus)   ; 戻り値は stat
; dwEncodingType : DWORD -> "sptr"
; dwSubjectType : DWORD -> "sptr"
; pvSubject : void* -> "sptr"
; pSubjectUsage : CTL_USAGE* -> "sptr"
; dwFlags : DWORD -> "sptr"
; pVerifyUsagePara : CTL_VERIFY_USAGE_PARA* optional -> "sptr"
; pVerifyUsageStatus : CTL_VERIFY_USAGE_STATUS* in/out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "CRYPT32.dll"
#cfunc global CertVerifyCTLUsage "CertVerifyCTLUsage" int, int, sptr, var, int, var, var
; res = CertVerifyCTLUsage(dwEncodingType, dwSubjectType, pvSubject, pSubjectUsage, dwFlags, pVerifyUsagePara, pVerifyUsageStatus)
; dwEncodingType : DWORD -> "int"
; dwSubjectType : DWORD -> "int"
; pvSubject : void* -> "sptr"
; pSubjectUsage : CTL_USAGE* -> "var"
; dwFlags : DWORD -> "int"
; pVerifyUsagePara : CTL_VERIFY_USAGE_PARA* optional -> "var"
; pVerifyUsageStatus : CTL_VERIFY_USAGE_STATUS* in/out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "CRYPT32.dll"
#cfunc global CertVerifyCTLUsage "CertVerifyCTLUsage" int, int, sptr, sptr, int, sptr, sptr
; res = CertVerifyCTLUsage(dwEncodingType, dwSubjectType, pvSubject, varptr(pSubjectUsage), dwFlags, varptr(pVerifyUsagePara), varptr(pVerifyUsageStatus))
; dwEncodingType : DWORD -> "int"
; dwSubjectType : DWORD -> "int"
; pvSubject : void* -> "sptr"
; pSubjectUsage : CTL_USAGE* -> "sptr"
; dwFlags : DWORD -> "int"
; pVerifyUsagePara : CTL_VERIFY_USAGE_PARA* optional -> "sptr"
; pVerifyUsageStatus : CTL_VERIFY_USAGE_STATUS* in/out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。