ホーム › Security.Cryptography › CertGetEnhancedKeyUsage

CertGetEnhancedKeyUsage

関数

証明書の拡張キー使用法(EKU)を取得する。

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

シグネチャ

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

BOOL CertGetEnhancedKeyUsage(
    const CERT_CONTEXT* pCertContext,
    DWORD dwFlags,
    CTL_USAGE* pUsage,   // optional
    DWORD* pcbUsage
);

パラメーター

名前

型

方向

説明

pCertContext

CERT_CONTEXT*

CERT_CONTEXT 証明書コンテキストへのポインターです。

dwFlags

DWORD

この関数が証明書の拡張、拡張プロパティ、またはその両方のいずれを対象にするかを示します。0 を指定した場合、関数は証明書の EKU 拡張と EKU 拡張プロパティ値の両方に基づいて、証明書の有効な用途を返します。

EKU 拡張または EKU プロパティ値のいずれか一方のみを返すには、次のフラグを設定します。

値	意味
CERT_FIND_EXT_ONLY_ENHKEY_USAGE_FLAG	拡張のみを取得します。
CERT_FIND_PROP_ONLY_ENHKEY_USAGE_FLAG	拡張プロパティ値のみを取得します。

pUsage

CTL_USAGE*

outoptional

証明書の有効な用途を受け取る CERT_ENHKEY_USAGE 構造体へのポインターです (CERT_ENHKEY_USAGE は CTL_USAGE 構造体の別名 typedef です)。

このパラメーターには、メモリ割り当てのためにキー使用法のサイズを設定する目的で NULL を指定できます。詳細については、 Retrieving Data of Unknown Length を参照してください。

pcbUsage

DWORD*

inout

pUsage が指す構造体のサイズをバイト単位で指定する DWORD へのポインターです。関数が戻るとき、この DWORD には構造体のサイズがバイト単位で格納されます。

戻り値の型: BOOL

公式ドキュメント

証明書の拡張キー使用法 (EKU) 拡張、または EKU 拡張プロパティから情報を取得します。

戻り値

関数が成功した場合は、0 以外の値 (TRUE) を返します。

関数が失敗した場合は、0 (FALSE) を返します。

解説(Remarks)

証明書に EKU 拡張がある場合、その拡張には証明書の有効な用途を示すオブジェクト識別子 (OID) が列挙されます。Microsoft 環境では、証明書の有効な用途を指定する EKU 拡張プロパティが証明書に付加されている場合もあります。

証明書に EKU 拡張も EKU 拡張プロパティもない場合、その証明書はすべての用途に対して有効であると見なされます。
EKU 拡張または EKU 拡張プロパティのいずれか一方のみがある場合、その証明書は備えている拡張または拡張プロパティに示された用途に対してのみ有効です。
証明書に EKU 拡張と EKU 拡張プロパティの両方がある場合、その証明書は両方のリストに含まれる用途に対してのみ有効です。

dwFlags に 0 を指定した場合、CERT_ENHKEY_USAGE 構造体の cUsageIdentifier メンバーには、EKU 拡張と EKU 拡張プロパティ値の両方の値によって決定される、証明書の有効な用途の数が設定されます。

cUsageIdentifier メンバーが 0 の場合、その証明書はすべての用途に対して有効であるか、または有効な用途がまったくないかのいずれかです。証明書がすべての用途に対して有効なのか、まったく有効でないのかを判別するには、GetLastError の呼び出しの戻り値を使用できます。GetLastError が CRYPT_E_NOT_FOUND を返す場合、その証明書はすべての用途に対して有効です。0 を返す場合、その証明書には有効な用途がありません。

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

各言語での呼び出し定義

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

BOOL CertGetEnhancedKeyUsage(
    const CERT_CONTEXT* pCertContext,
    DWORD dwFlags,
    CTL_USAGE* pUsage,   // optional
    DWORD* pcbUsage
);

[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("CRYPT32.dll", SetLastError = true, ExactSpelling = true)]
static extern bool CertGetEnhancedKeyUsage(
    IntPtr pCertContext,   // CERT_CONTEXT*
    uint dwFlags,   // DWORD
    IntPtr pUsage,   // CTL_USAGE* optional, out
    ref uint pcbUsage   // DWORD* in/out
);

<DllImport("CRYPT32.dll", SetLastError:=True, ExactSpelling:=True)>
Public Shared Function CertGetEnhancedKeyUsage(
    pCertContext As IntPtr,   ' CERT_CONTEXT*
    dwFlags As UInteger,   ' DWORD
    pUsage As IntPtr,   ' CTL_USAGE* optional, out
    ByRef pcbUsage As UInteger   ' DWORD* in/out
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

' pCertContext : CERT_CONTEXT*
' dwFlags : DWORD
' pUsage : CTL_USAGE* optional, out
' pcbUsage : DWORD* in/out
Declare PtrSafe Function CertGetEnhancedKeyUsage Lib "crypt32" ( _
    ByVal pCertContext As LongPtr, _
    ByVal dwFlags As Long, _
    ByVal pUsage As LongPtr, _
    ByRef pcbUsage As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

CertGetEnhancedKeyUsage = ctypes.windll.crypt32.CertGetEnhancedKeyUsage
CertGetEnhancedKeyUsage.restype = wintypes.BOOL
CertGetEnhancedKeyUsage.argtypes = [
    ctypes.c_void_p,  # pCertContext : CERT_CONTEXT*
    wintypes.DWORD,  # dwFlags : DWORD
    ctypes.c_void_p,  # pUsage : CTL_USAGE* optional, out
    ctypes.POINTER(wintypes.DWORD),  # pcbUsage : DWORD* in/out
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('CRYPT32.dll')
CertGetEnhancedKeyUsage = Fiddle::Function.new(
  lib['CertGetEnhancedKeyUsage'],
  [
    Fiddle::TYPE_VOIDP,  # pCertContext : CERT_CONTEXT*
    -Fiddle::TYPE_INT,  # dwFlags : DWORD
    Fiddle::TYPE_VOIDP,  # pUsage : CTL_USAGE* optional, out
    Fiddle::TYPE_VOIDP,  # pcbUsage : DWORD* in/out
  ],
  Fiddle::TYPE_INT)

#[link(name = "crypt32")]
extern "system" {
    fn CertGetEnhancedKeyUsage(
        pCertContext: *const CERT_CONTEXT,  // CERT_CONTEXT*
        dwFlags: u32,  // DWORD
        pUsage: *mut CTL_USAGE,  // CTL_USAGE* optional, out
        pcbUsage: *mut u32  // DWORD* 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 CertGetEnhancedKeyUsage(IntPtr pCertContext, uint dwFlags, IntPtr pUsage, ref uint pcbUsage);
"@
$api = Add-Type -MemberDefinition $sig -Name 'CRYPT32_CertGetEnhancedKeyUsage' -Namespace Win32 -PassThru
# $api::CertGetEnhancedKeyUsage(pCertContext, dwFlags, pUsage, pcbUsage)

#uselib "CRYPT32.dll"
#func global CertGetEnhancedKeyUsage "CertGetEnhancedKeyUsage" sptr, sptr, sptr, sptr
; CertGetEnhancedKeyUsage varptr(pCertContext), dwFlags, varptr(pUsage), varptr(pcbUsage)   ; 戻り値は stat
; pCertContext : CERT_CONTEXT* -> "sptr"
; dwFlags : DWORD -> "sptr"
; pUsage : CTL_USAGE* optional, out -> "sptr"
; pcbUsage : DWORD* in/out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

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