ホーム › Security.Cryptography.Certificates › IX509Enrollment

IX509Enrollment

COMIDispatch (デュアル)

📘 Microsoft Learn (日本語) · English

✅ IDispatch を実装(デュアルインターフェース)。HSP では comobj 経由でメソッド名による遅延バインド呼び出しができます(vtableインデックス不要)。

IID728ab346-217d-11da-b2a4-000e7bbb2b09継承元IDispatch呼び出し名前(IDispatch) または vtbl自前メソッド開始 vtbl7

公式ドキュメント

最上位のオブジェクトを表し、証明書階層への登録(エンロール)と証明書応答のインストールを可能にします。

メソッド 23

vtbl = vtable インデックス(0始まり)。IDispatch 実装のため HSP ではメソッド名でも呼べます(上記)。低レベルの index 呼び出し用に vtbl も掲載。0〜2 は IUnknown。

vtbl 7 HRESULT Initialize(X509CertificateEnrollmentContext Context)

登録(エンロール)オブジェクトを初期化し、既定の PKCS を作成します。

Context

X509CertificateEnrollmentContext

要求された登録(エンロール)がユーザー向けか、コンピューター向けか、またはコンピューターの代理として動作する管理者向けかを指定する X509CertificateEnrollmentContext 列挙値。

戻り値

関数が成功した場合、S_OK を返します。

関数が失敗した場合、エラーを示す HRESULT 値を返します。使用され得る値には次の表に示すものが含まれますが、これらに限定されません。一般的なエラーコードの一覧については、Common HRESULT Values を参照してください。

戻り値/値	説明
HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZED)	登録(エンロール)オブジェクトは既に初期化されています。

解説(Remarks)

Initialize メソッドは、新しいキーペアを作成し、要求に関連付けられた属性、拡張、およびクリティカル拡張のための空のコレクションを初期化します。

vtbl 8 HRESULT InitializeFromTemplateName(X509CertificateEnrollmentContext Context, LPWSTR strTemplateName)

テンプレートの共通名(CN)から登録(エンロール)オブジェクトを初期化します。

Context	X509CertificateEnrollmentContext	in	要求された登録(エンロール)がユーザー向けか、コンピューター向けか、またはコンピューターの代理として動作する管理者向けかを示す X509CertificateEnrollmentContext 列挙値。
strTemplateName	LPWSTR	in	Active Directory に表示されるテンプレートの共通名(CN)、またはドット区切り 10 進表記のオブジェクト識別子を格納する BSTR 変数。

戻り値

関数が成功した場合、S_OK を返します。

戻り値/値	説明
HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZED)	登録(エンロール)オブジェクトは既に初期化されています。

解説(Remarks)

InitializeFromTemplateName メソッドは次の処理を行います。

テンプレートを調べて、必要な要求の種類を判別します。
適切な種類の要求オブジェクト(PKCS #10、PKCS #7、または CMC)を作成します。
値が現在存在する場合、要求に次のプロパティを設定します。
テンプレートを使用して要求オブジェクトを初期化します。
署名数、発行ポリシー、およびアプリケーションポリシーをテンプレートから取得します。

vtbl 9 HRESULT InitializeFromRequest(IX509CertificateRequest* pRequest)

既存の IX509CertificateRequest オブジェクトから登録(エンロール)オブジェクトを初期化します。

pRequest

IX509CertificateRequest*

inoptional

IX509CertificateRequest インターフェイスへのポインター。

戻り値

関数が成功した場合、S_OK を返します。

戻り値/値	説明
HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZED)	登録(エンロール)オブジェクトは既に初期化されています。

解説(Remarks)

InitializeFromRequest メソッドは次の処理を行います。

要求が PKCS #10、PKCS #7、または CMC の要求オブジェクトであることを検証します。
要求に関連付けられたテンプレートがあれば取得します。
テンプレートを検証します。
要求オブジェクトを Request プロパティに設定します。
署名数、発行ポリシー、およびアプリケーションポリシーをテンプレートから取得します。
更新用証明書が存在する場合は取得します。

vtbl 10 HRESULT CreateRequest(EncodingType Encoding, LPWSTR* pValue)

エンコードされた証明書要求を取得します。

Encoding	EncodingType	in	DER エンコードされた要求に適用される Unicode エンコードの種類を指定する EncodingType 列挙値。既定値は XCN_CRYPT_STRING_BASE64 です。
pValue	LPWSTR*	out	DER エンコードされた要求を格納する BSTR 変数へのポインター。

戻り値

関数が成功した場合、S_OK を返します。

戻り値/値	説明
CERTSRV_E_PROPERTY_EMPTY	証明書要求が見つかりません。
OLE_E_BLANK	登録(エンロール)オブジェクトが初期化されていません。

解説(Remarks)

CreateRequest メソッドは、必要に応じて Encode メソッドを呼び出し、関連付けられた要求オブジェクトの生データをエンコードします。

このメソッドは、初期化時に指定された情報とその他の指定されたプロパティを使用してダミー証明書を作成し、要求ストアに格納します。また、必要に応じてキーペアも作成します。登録(エンロール)オブジェクトの初期化方法や設定したプロパティによっては、キーペアを作成する必要がない場合があります。たとえば、既存のキーを使用して証明書を更新する場合や、証明書要求に関連付けられた IX509PrivateKey オブジェクトが既存のキーを表している場合、このメソッドは新しいキーペアを作成しません。

スマートカードが関係する場合、このメソッドは外部プロパティを拡張としてエンコードし、それらをダミー証明書に含め、ダミー証明書をスマートカードのキーコンテナーに書き込みます。スマートカードのログオン証明書は、個人ストアではなく要求ストアにエンコードされます。

CreateRequest メソッドを呼び出す前に、次のいずれかのメソッドを呼び出して IX509Enrollment オブジェクトを初期化する必要があります。

vtbl 11 HRESULT Enroll()

要求をエンコードし、適切な証明機関(CA)に送信して、応答をインストールします。

戻り値

関数が成功した場合、S_OK を返します。

戻り値/値	説明
OLE_E_BLANK	登録(エンロール)オブジェクトが初期化されていません。

解説(Remarks)

このメソッドは、必要に応じてキーペアを作成する場合があります。登録(エンロール)オブジェクトの初期化方法や設定したプロパティによっては、キーペアを作成する必要がない場合があります。たとえば、既存のキーを使用して証明書を更新する場合や、証明書要求に関連付けられた IX509PrivateKey オブジェクトが既存のキーを表している場合、このメソッドは新しいキーペアを作成しません。

登録(エンロール)を行う前に、次のいずれかのメソッドを呼び出して IX509Enrollment オブジェクトを初期化する必要があります。

登録(エンロール)操作が成功すると、関数は S_OK を返します。ただし、これは必ずしも CA からの応答がインストールされたことを意味しません。登録(エンロール)の状態を確認するには、Status プロパティを呼び出してください。

vtbl 12 HRESULT InstallResponse(InstallResponseRestrictionFlags Restrictions, LPWSTR strResponse, EncodingType Encoding, LPWSTR strPassword)

証明書チェーンをエンドエンティティのコンピューターにインストールします。(IX509Enrollment.InstallResponse)

Restrictions

InstallResponseRestrictionFlags

インストールできる証明書の種類を指定する InstallResponseRestrictionFlags 列挙値。次の値の 1 つ以上を指定できます。

値	意味
AllowNone	信頼されていない証明書、または対応する要求が存在しない証明書をインストールしません。
AllowNoOutstandingRequest	秘密キーを、ダミー証明書からではなく証明書応答から作成します。これにより、ダミー証明書は省略可能になります。この値が設定されていない場合、ダミー証明書が存在している必要があり、秘密キーはそこから抽出されます。
AllowUntrustedCertificate	信頼されていないエンドエンティティ証明書および証明機関証明書をインストールします。証明機関証明書には、ルート CA 証明書および下位 CA 証明書が含まれます。エンドエンティティ証明書は個人ストアにインストールされ、CA 証明書は証明機関ストアにインストールされます。
AllowUntrustedRoot	AllowUntrustedCertificate フラグと同じ動作を行いますが、ルートが信頼されていないために証明書チェーンを構築できない場合でも証明書をインストールします。注意 Windows Vista では、このフラグの動作は AllowUntrustedCertificate フラグに定義された動作と同じです。Windows Vista with SP1 以降では、信頼されていないルートにチェーンする証明書をインストールできます。

strResponse

LPWSTR

DER エンコードされた応答を格納する BSTR 変数。

Encoding

EncodingType

DER エンコードされた応答を格納する文字列に適用されるエンコードの種類を指定する EncodingType 列挙値。

strPassword

LPWSTR

証明書のインストールに使用する省略可能なパスワード。パスワードを使用しないことを示すには、NULL または空文字列を指定できます。パスワードがある場合は、使用が終わったら SecureZeroMemory 関数を呼び出してメモリからクリアしてください。パスワードの保護の詳細については、Handling Passwords を参照してください。

Windows 8 および Windows Server 2012 以降では、NULL または空のパスワードは、PFX パケットが PFXExportCertStoreEx 関数で PKCS12_PROTECT_TO_DOMAIN_SIDS フラグを使用して作成されたことを意味する場合があります。その場合、PFX は Active Directory グループに対して暗号化されています。詳細については、PFXExportCertStoreEx および PFXImportCertStore を参照してください。

戻り値

関数が成功した場合、S_OK を返します。

戻り値	説明
E_ACCESSDENIED	このメソッドが Web から呼び出され、Restrictions パラメーターに AllowNoOutstandingRequest または AllowUntrustedCertificate が指定されました。
HRESULT_FROM_WIN32(ERROR_ARITHMETIC_OVERFLOW	パスワードを格納する文字列の長さが 64 キロバイトを超えています。
OLE_E_BLANK	登録(エンロール)オブジェクトが初期化されていません。

解説(Remarks)

InstallResponse メソッドは次の処理を行います。

外部ストアからダミー証明書を取得します。
応答に含まれる証明書を取得し、コンピューターにインストールします。
外部ストアのダミー証明書から、個人ストアに新しくインストールされた証明書へプロパティをコピーします。

InstallResponse メソッドを呼び出す前に、次のいずれかのメソッドを呼び出して IX509Enrollment オブジェクトを初期化する必要があります。

このメソッドを Web から呼び出す場合、Restrictions パラメーターに指定できるのは AllowNone または AllowUntrustedRoot のみです。AllowNoOutstandingRequest または AllowUntrustedCertificate を指定すると、このメソッドは E_ACCESSDENIED エラーを返します。

vtbl 13 HRESULT CreatePFX(LPWSTR strPassword, PFXExportOptions ExportOptions, EncodingType Encoding, LPWSTR* pValue)

個人情報交換(PFX)メッセージを作成します。

strPassword	LPWSTR	in	PFX メッセージのパスワードを格納する BSTR 変数。パスワードを使用しないことを示すには NULL を指定できます。パスワードの使用が終わったら、SecureZeroMemory 関数を呼び出してメモリからクリアしてください。パスワードの保護の詳細については、Handling Passwords を参照してください。
ExportOptions	PFXExportOptions	in	証明書チェーンのどの範囲をエクスポートするかを指定する PFXExportOptions 列挙値。証明書のみ、ルートを含まない証明書チェーン、またはチェーン全体をエクスポートできます。
Encoding	EncodingType	in	DER エンコードされたメッセージに適用される Unicode エンコードの種類を指定する EncodingType 列挙値。既定値は XCN_CRYPT_STRING_BASE64 です。
pValue	LPWSTR*	out	DER エンコードされた PFX メッセージを格納する BSTR 変数へのポインター。

戻り値

関数が成功した場合、S_OK を返します。

戻り値/値	説明
CERTSRV_E_PROPERTY_EMPTY	証明書が見つかりません。
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)	証明書チェーンが見つかりません。
OLE_E_BLANK	登録(エンロール)オブジェクトが初期化されていません。

解説(Remarks)

PFX 形式は PKCS #12 とも呼ばれます。CreatePFX メソッドは次の処理を行います。

既定のプロバイダー用の証明書ストアをメモリ内に開きます。
インストール済みの証明書をストアに追加するか、証明書チェーンを構築してそれへのリンクを追加します。
指定されたエクスポートオプションに応じて、証明書と秘密キーを PFX メッセージにエクスポートします。
エクスポートされたメッセージを DER を使用してエンコードします。

このメソッドを呼び出す前に、次のいずれかのメソッドを呼び出して IX509Enrollment オブジェクトを初期化する必要があります。

さらに、Enroll メソッドから正常に復帰している必要があります。

vtbl 14 HRESULT get_Request(IX509CertificateRequest** pValue)

登録(エンロール)オブジェクトに関連付けられた証明書要求を取得します。

pValue

IX509CertificateRequest**

out

この登録に関連付けられた証明書要求 IX509CertificateRequest オブジェクトを受け取るポインタである。

解説(Remarks)

このプロパティは、InitializeFromRequest メソッドが呼び出されるときに設定できます。

vtbl 15 HRESULT get_Silent(VARIANT_BOOL* pValue)

証明書の登録(エンロール)処理中にユーザーインターフェイスを表示するかどうかを示すブール値を指定または取得します。(Get)

pValue

VARIANT_BOOL*

out

サイレント(UI を抑制する)モードが有効かどうかを表す VARIANT_BOOL を受け取るポインタである。

解説(Remarks)

このプロパティは、登録(エンロール)オブジェクトを初期化する前に設定できます。

vtbl 16 HRESULT put_Silent(VARIANT_BOOL Value)

証明書の登録(エンロール)処理中にユーザーインターフェイスを表示するかどうかを示すブール値を指定または取得します。(Put)

Value

VARIANT_BOOL

UI を表示しないサイレントモードの有効・無効を VARIANT_BOOL で指定する。

解説(Remarks)

このプロパティは、登録(エンロール)オブジェクトを初期化する前に設定できます。

vtbl 17 HRESULT get_ParentWindow(INT* pValue)

登録(エンロール)情報の表示に使用するウィンドウの ID を指定または取得します。(Get)

pValue

INT*

out

UI 表示時の親ウィンドウハンドル(INT として扱う)を受け取るポインタである。

解説(Remarks)

このプロパティは、登録(エンロール)オブジェクトを初期化する前に呼び出すことができます。呼び出さない場合、オブジェクトの初期化時に指定されることがあります。

vtbl 18 HRESULT put_ParentWindow(INT Value)

登録(エンロール)情報の表示に使用するウィンドウの ID を指定または取得します。(Put)

Value

INT

UI 表示時の親ウィンドウハンドルを INT として指定する。

解説(Remarks)

vtbl 19 HRESULT get_NameValuePairs(IX509NameValuePairs** ppValue)

登録(エンロール)オブジェクトに関連付けられた名前と値のペアのコレクションを取得します。

ppValue

IX509NameValuePairs**

out

登録に関連付けられた名前と値のペアのコレクション IX509NameValuePairs を受け取るポインタである。

解説(Remarks)

名前と値のペアは、CA が処理するための要求とともに証明機関(CA)へ渡されます。IX509NameValuePairs オブジェクトは、オブジェクトの初期化時に IX509Enrollment オブジェクトに関連付けられます。したがって、このプロパティを呼び出す前に、次のいずれかのメソッドを呼び出して IX509Enrollment オブジェクトを初期化する必要があります。

vtbl 20 HRESULT get_EnrollmentContext(X509CertificateEnrollmentContext* pValue)

証明書がコンピューター向けかエンドユーザー向けかを識別する登録(エンロール)コンテキストを取得します。

pValue

X509CertificateEnrollmentContext*

out

この登録の登録コンテキストを表す X509CertificateEnrollmentContext 値を受け取るポインタである。

解説(Remarks)

このプロパティを呼び出す前に、次のいずれかのメソッドを呼び出して IX509Enrollment オブジェクトを初期化する必要があります。

vtbl 21 HRESULT get_Status(IX509EnrollmentStatus** ppValue)

登録(エンロール)処理の状態を監視し、エラー情報を取得するために使用できる IX509EnrollmentStatus オブジェクトを取得します。

ppValue

IX509EnrollmentStatus**

out

登録要求の処理状態を表す IX509EnrollmentStatus オブジェクトを受け取るポインタである。

vtbl 22 HRESULT get_Certificate(EncodingType Encoding, LPWSTR* pValue)

インストール済みの証明書を取得します。

Encoding	EncodingType	in	取得する証明書文字列のエンコーディング種別を指定する EncodingType 列挙値である。
pValue	LPWSTR*	out	登録で発行された証明書を指定エンコーディングの文字列として受け取るポインタである。

vtbl 23 HRESULT get_Response(EncodingType Encoding, LPWSTR* pValue)

証明機関から返された証明書応答を取得します。

Encoding	EncodingType	in	取得する応答文字列のエンコーディング種別を指定する EncodingType 列挙値である。
pValue	LPWSTR*	out	CA から受け取った証明書応答を指定エンコーディングの文字列として受け取るポインタである。

vtbl 24 HRESULT get_CertificateFriendlyName(LPWSTR* pValue)

証明書の表示名を指定または取得します。(Get)

pValue

LPWSTR*

out

発行された証明書の表示名(フレンドリ名)を文字列として受け取るポインタである。

vtbl 25 HRESULT put_CertificateFriendlyName(LPWSTR strValue)

証明書の表示名を指定または取得します。(Put)

strValue

LPWSTR

発行された証明書に設定する表示名(フレンドリ名)を文字列で指定する。

vtbl 26 HRESULT get_CertificateDescription(LPWSTR* pValue)

証明書の説明を格納する文字列を指定または取得します。(Get)

pValue

LPWSTR*

out

発行された証明書の説明文を文字列として受け取るポインタである。

vtbl 27 HRESULT put_CertificateDescription(LPWSTR strValue)

証明書の説明を格納する文字列を指定または取得します。(Put)

strValue

LPWSTR

発行された証明書に設定する説明文を文字列で指定する。

vtbl 28 HRESULT get_RequestId(INT* pValue)

Enroll メソッドによって証明機関に送信された証明書要求の一意の識別子を取得します。

pValue

INT*

out

CA 上での要求 ID を表す INT を受け取るポインタである。

解説(Remarks)

RequestId プロパティの値は、登録(エンロール)処理中に設定されます。この値は、クライアントと CA の間のその後の通信で使用できます。たとえば、CA が最初の送信時に要求を保留中としてマークした場合、クライアントは再度 CA に接続して証明書応答の取得を試みる際に、要求 ID と構成文字列を使用できます。構成文字列を取得するには、CAConfigString プロパティを呼び出します。

vtbl 29 HRESULT get_CAConfigString(LPWSTR* pValue)

証明書要求の送信先である証明機関(CA)を識別する構成文字列を取得します。

pValue

LPWSTR*

out

対象の CA を識別する構成文字列(サーバー名と CA 名)を受け取るポインタである。

解説(Remarks)

構成文字列には、証明機関の Domain Name System(DNS)名と共通名(CN)が含まれます。文字列の形式は "CAComputerDNSName\CACommonName" です。

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

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数:

#define global IID_IX509Enrollment "{728AB346-217D-11DA-B2A4-000E7BBB2B09}"
#usecom global IX509Enrollment IID_IX509Enrollment "{}"
#comfunc global IX509Enrollment_Initialize                   7 int
#comfunc global IX509Enrollment_InitializeFromTemplateName   8 int,wstr
#comfunc global IX509Enrollment_InitializeFromRequest        9 sptr
#comfunc global IX509Enrollment_CreateRequest                10 int,var
#comfunc global IX509Enrollment_Enroll                       11
#comfunc global IX509Enrollment_InstallResponse              12 int,wstr,int,wstr
#comfunc global IX509Enrollment_CreatePFX                    13 wstr,int,int,var
#comfunc global IX509Enrollment_get_Request                  14 sptr
#comfunc global IX509Enrollment_get_Silent                   15 var
#comfunc global IX509Enrollment_put_Silent                   16 int
#comfunc global IX509Enrollment_get_ParentWindow             17 var
#comfunc global IX509Enrollment_put_ParentWindow             18 int
#comfunc global IX509Enrollment_get_NameValuePairs           19 sptr
#comfunc global IX509Enrollment_get_EnrollmentContext        20 var
#comfunc global IX509Enrollment_get_Status                   21 sptr
#comfunc global IX509Enrollment_get_Certificate              22 int,var
#comfunc global IX509Enrollment_get_Response                 23 int,var
#comfunc global IX509Enrollment_get_CertificateFriendlyName  24 var
#comfunc global IX509Enrollment_put_CertificateFriendlyName  25 wstr
#comfunc global IX509Enrollment_get_CertificateDescription   26 var
#comfunc global IX509Enrollment_put_CertificateDescription   27 wstr
#comfunc global IX509Enrollment_get_RequestId                28 var
#comfunc global IX509Enrollment_get_CAConfigString           29 var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。
; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。#define global IID_IX509Enrollment "{728AB346-217D-11DA-B2A4-000E7BBB2B09}"
#usecom global IX509Enrollment IID_IX509Enrollment "{}"
#comfunc global IX509Enrollment_Initialize                   7 int
#comfunc global IX509Enrollment_InitializeFromTemplateName   8 int,wstr
#comfunc global IX509Enrollment_InitializeFromRequest        9 sptr
#comfunc global IX509Enrollment_CreateRequest                10 int,sptr
#comfunc global IX509Enrollment_Enroll                       11
#comfunc global IX509Enrollment_InstallResponse              12 int,wstr,int,wstr
#comfunc global IX509Enrollment_CreatePFX                    13 wstr,int,int,sptr
#comfunc global IX509Enrollment_get_Request                  14 sptr
#comfunc global IX509Enrollment_get_Silent                   15 sptr
#comfunc global IX509Enrollment_put_Silent                   16 int
#comfunc global IX509Enrollment_get_ParentWindow             17 sptr
#comfunc global IX509Enrollment_put_ParentWindow             18 int
#comfunc global IX509Enrollment_get_NameValuePairs           19 sptr
#comfunc global IX509Enrollment_get_EnrollmentContext        20 sptr
#comfunc global IX509Enrollment_get_Status                   21 sptr
#comfunc global IX509Enrollment_get_Certificate              22 int,sptr
#comfunc global IX509Enrollment_get_Response                 23 int,sptr
#comfunc global IX509Enrollment_get_CertificateFriendlyName  24 sptr
#comfunc global IX509Enrollment_put_CertificateFriendlyName  25 wstr
#comfunc global IX509Enrollment_get_CertificateDescription   26 sptr
#comfunc global IX509Enrollment_put_CertificateDescription   27 wstr
#comfunc global IX509Enrollment_get_RequestId                28 sptr
#comfunc global IX509Enrollment_get_CAConfigString           29 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。
; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。