IX509Enrollment2
COMIDispatch (デュアル)comobj 経由でメソッド名による遅延バインド呼び出しができます(vtableインデックス不要)。公式ドキュメント
IX509Enrollment2 インターフェイスを使用すると、証明書階層への登録(エンロール)と証明書応答のインストールを行うことができます。
メソッド 5
vtbl = vtable インデックス(0始まり)。IDispatch 実装のため HSP ではメソッド名でも呼べます(上記)。低レベルの index 呼び出し用に vtbl も掲載。0〜2 は IUnknown。
テンプレートを使用して登録(エンロール)オブジェクトを初期化します。
| context | X509CertificateEnrollmentContext | in | An X509CertificateEnrollmentContext 列挙値です。要求された登録(エンロール)がユーザー向けか、コンピューター向けか、またはコンピューターに代わって操作する管理者向けかを示します。次のいずれかの値を指定できます。
| ||||||||
| pPolicyServer | IX509EnrollmentPolicyServer* | inoptional | pTemplate パラメーターで指定されたテンプレートを含む証明書登録ポリシー(CEP)サーバーを表す IX509EnrollmentPolicyServer オブジェクトへのポインターです。 | ||||||||
| pTemplate | IX509CertificateTemplate* | inoptional | 初期化時に使用するテンプレートを表す IX509CertificateTemplate オブジェクトへのポインターです。 |
戻り値
関数が成功した場合、関数は S_OK を返します。
関数が失敗した場合は、エラーを示す HRESULT 値を返します。取り得る値には次の表に示すものが含まれますが、これらに限定されません。一般的なエラーコードの一覧については、Common HRESULT Values を参照してください。
| リターンコード/値 | 説明 |
|---|---|
| pPolicyServer パラメーターと pTemplate パラメーターに NULL を指定することはできません。 | |
|
登録(エンロール)オブジェクトは既に初期化されています。 |
解説(Remarks)
InitializeFromTemplate メソッドは、次の処理を行います。
- テンプレートを調べて、必要な要求の種類を判断します。
- 適切な種類の要求オブジェクト(PKCS #10、PKCS #7、または CMC)を作成します。
- 値が現在存在する場合、要求に次のプロパティを設定します。
- テンプレートを使用して要求オブジェクトを初期化します。
- テンプレートから署名数、発行ポリシー、およびアプリケーションポリシーを取得します。
エンドエンティティ コンピューターに証明書チェーンをインストールします。(IX509Enrollment2.InstallResponse2)
| Restrictions | InstallResponseRestrictionFlags | in | インストールできる証明書の種類を指定する InstallResponseRestrictionFlags 列挙値です。次の値の 1 つ以上を指定できます。
| ||||||||||
| strResponse | LPWSTR | in | DER エンコードされた応答を含む BSTR 変数です。 | ||||||||||
| Encoding | EncodingType | in | DER エンコードされた応答を含む文字列に適用されるエンコードの種類を指定する EncodingType 列挙値です。 | ||||||||||
| strPassword | LPWSTR | in | 証明書のインストールに使用する省略可能なパスワードです。パスワードを使用しないことを示すために NULL を指定できます。パスワードの使用が終わったら、SecureZeroMemory 関数を呼び出してメモリからクリアしてください。パスワードの保護の詳細については、Handling Passwords を参照してください。 | ||||||||||
| strEnrollmentPolicyServerUrl | LPWSTR | in | 証明書登録ポリシー(CEP)サーバーの URL を含む BSTR です。 | ||||||||||
| strEnrollmentPolicyServerID | LPWSTR | in | CEP サーバーの識別子を含む BSTR です。 | ||||||||||
| EnrollmentPolicyServerFlags | PolicyServerUrlFlags | in | PolicyServerUrlFlags 列挙値です。次のいずれかの値を指定できます。 | ||||||||||
| authFlags | X509EnrollmentAuthFlags | in | クライアント認証の種類を指定する X509EnrollmentAuthFlags 列挙値です。Windows 7 では、次の値のうち X509AuthCertificate のみを選択できます。 |
戻り値
関数が成功した場合、関数は S_OK を返します。
関数が失敗した場合は、エラーを示す HRESULT 値を返します。取り得る値には次の表に示すものが含まれますが、これらに限定されません。一般的なエラーコードの一覧については、Common HRESULT Values を参照してください。
| リターンコード | 説明 |
|---|---|
| このメソッドが Web から呼び出され、かつ Restrictions パラメーターに AllowNoOutstandingRequest または AllowUntrustedCertificate が指定されました。 | |
|
パスワードを含む文字列の長さが 64 キロバイトを超えています。 |
| 登録(エンロール)オブジェクトが初期化されていません。 |
解説(Remarks)
InstallResponse2 メソッドは、次の処理を行います。
- 外部ストアからダミー証明書を取得します。
- 応答に含まれる証明書を取得し、コンピューターにインストールします。
- 外部ストア内のダミー証明書から、個人ストアに新しくインストールされた証明書へプロパティをコピーします。
InstallResponse2 メソッドを呼び出す前に、次のいずれかのメソッドを呼び出して IX509Enrollment オブジェクトを初期化する必要があります。
Web からこのメソッドを呼び出す場合、Restrictions パラメーターに指定できるのは AllowNone または AllowUntrustedRoot のみです。AllowNoOutstandingRequest または AllowUntrustedCertificate を指定した場合、メソッドは E_ACCESSDENIED エラーを返します。
最後の 4 つのパラメーター(strEnrollmentPolicyServerUrl、strEnrollmentPolicyServerID、EnrollmentPolicyServerFlags、authFlags)は、InstallResponse メソッドには含まれていません。これらのパラメーターを使用すると、ICertPropertyEnrollmentPolicyServer インターフェイスとほぼ同じ方法で、インストールされた証明書にプロパティ値を追加できます。
初期化時に使用したテンプレートを含む証明書登録ポリシー(CEP)サーバーを取得します。(IX509Enrollment2.get_PolicyServer)
| ppPolicyServer | IX509EnrollmentPolicyServer** | out | この登録に関連付けられた IX509EnrollmentPolicyServer オブジェクトを受け取るポインタである。 |
初期化時に使用した証明書要求テンプレートを取得します。(IX509Enrollment2.get_Template)
| ppTemplate | IX509CertificateTemplate** | out | この登録に関連付けられた IX509CertificateTemplate オブジェクトを受け取るポインタである。 |
証明書登録サーバー(CES)に送信された証明書要求の一意の識別子を含む文字列を取得します。
| pValue | LPWSTR* | out | CA 上での要求 ID を文字列として受け取るポインタである。 |
解説(Remarks)
RequestIdString プロパティの値は、登録(エンロール)処理の過程で設定されます。この値は、クライアントと CES との間の後続の通信で使用できます。たとえば、CES が最初の送信時に要求を保留中としてマークした場合、クライアントは再び CES に接続して証明書応答を取得しようとする際に、この要求 ID 文字列を使用できます。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IX509Enrollment2 "{728AB350-217D-11DA-B2A4-000E7BBB2B09}" #usecom global IX509Enrollment2 IID_IX509Enrollment2 "{}" #comfunc global IX509Enrollment2_InitializeFromTemplate 30 int,sptr,sptr #comfunc global IX509Enrollment2_InstallResponse2 31 int,wstr,int,wstr,wstr,wstr,int,int #comfunc global IX509Enrollment2_get_PolicyServer 32 sptr #comfunc global IX509Enrollment2_get_Template 33 sptr #comfunc global IX509Enrollment2_get_RequestIdString 34 var ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。 ; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。#define global IID_IX509Enrollment2 "{728AB350-217D-11DA-B2A4-000E7BBB2B09}" #usecom global IX509Enrollment2 IID_IX509Enrollment2 "{}" #comfunc global IX509Enrollment2_InitializeFromTemplate 30 int,sptr,sptr #comfunc global IX509Enrollment2_InstallResponse2 31 int,wstr,int,wstr,wstr,wstr,int,int #comfunc global IX509Enrollment2_get_PolicyServer 32 sptr #comfunc global IX509Enrollment2_get_Template 33 sptr #comfunc global IX509Enrollment2_get_RequestIdString 34 sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。 ; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。