Win32 API 日本語リファレンス
ホーム › Security.Cryptography.Certificates › IX509EnrollmentHelper

IX509EnrollmentHelper

COMIDispatch (デュアル)
📘 Microsoft Learn (日本語) · English
✅ IDispatch を実装(デュアルインターフェース)。HSP では comobj 経由でメソッド名による遅延バインド呼び出しができます(vtableインデックス不要)。
IID728ab351-217d-11da-b2a4-000e7bbb2b09継承元IDispatch呼び出し名前(IDispatch) または vtbl自前メソッド開始 vtbl7

公式ドキュメント

IX509EnrollmentHelper インターフェイスは、Web アプリケーションが証明書を登録(エンロール)し、ポリシーサーバーの資格情報を資格情報キャッシュに保存し、ポリシーサーバーおよび登録サーバーを登録できるようにするメソッドを定義します。

メソッド 4

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

vtbl 7 HRESULT AddPolicyServer(LPWSTR strEnrollmentPolicyServerURI, LPWSTR strEnrollmentPolicyID, PolicyServerUrlFlags EnrollmentPolicyServerFlags, X509EnrollmentAuthFlags authFlags, LPWSTR strCredential, LPWSTR strPassword)

証明書登録ポリシー (CEP) サーバーを登録し、CEP アクセス資格情報を資格情報キャッシュに保存します。

strEnrollmentPolicyServerURILPWSTRin証明書登録ポリシーサーバーの URL を格納する BSTR です。
strEnrollmentPolicyIDLPWSTRin証明書登録ポリシーサーバーの ID を格納する BSTR です。ID には任意の文字列を指定できます。この値は、CEP サーバーをインストールする管理者が設定します。
EnrollmentPolicyServerFlagsPolicyServerUrlFlagsin

PolicyServerUrlFlags 列挙値です。AddPolicyServer 関数では、次の値のビットごとの OR を指定できます。

値 意味
PsfAutoEnrollmentEnabled
 証明書の自動登録が有効になっています。
PsfAllowUnTrustedCA
 CA によって署名された証明書をインストールするために、発行元 CA の証明書がクライアントによって信頼されている必要がないことを指定します。
authFlagsX509EnrollmentAuthFlagsin

クライアント認証の種類を指定する X509EnrollmentAuthFlags 列挙値です。次のいずれかの値を指定できます。

値 意味
X509AuthAnonymous
 匿名認証です。strCredential パラメーターと strPassword パラメーターを NULL に設定します。
X509AuthKerberos
 Kerberos 認証です。strCredential パラメーターと strPassword パラメーターを NULL に設定します。
X509AuthUsername
 クリアテキストのユーザー名とパスワードによる認証です。strCredential パラメーターと strPassword パラメーターに、ユーザー名とそれに対応するパスワードを設定します。これらの文字列は送信前に暗号化され、CEP サーバー上の資格情報コンテナーに安全に格納されます。
X509AuthCertificate
 ローカルコンピューターにインストールされ、サーバーがクライアントの ID を検証するために使用するクライアント認証証明書です。strPassword パラメーターを NULL に設定し、証明書のサムプリント (証明書の 20 バイトの SHA1 ハッシュ) を strCredential パラメーターに設定します。
strCredentialLPWSTRin資格情報を格納する BSTR です。
strPasswordLPWSTRinクリアテキストのパスワードを格納する BSTR です。

戻り値

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

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

戻り値 説明
E_INVALIDARG
 strEnrollmentPolicyServerURI、strCredential、または strPassword パラメーターを NULL または空にすることはできません。
HRESULT_FROM_WIN32(ERROR_ARITHMETIC_OVERFLOW)
 strPassword、strCredential、または strEnrollmentServerURI パラメーターが 64,000 文字を超えているか、埋め込み null 文字を含んでいます。

解説(Remarks)

次の表に示すように、strCredential 引数と strPassword 引数は、authFlags 引数に指定された値に応じて変化します。

flag パラメーター strCredential パラメーター strPassword パラメーター
X509AuthAnonymous NULL NULL
X509AuthKerberos NULL NULL
X509AuthUsername CEP サーバーが認識するクリアテキストのユーザー名。 ユーザー名に対応するクリアテキストのパスワード。
X509AuthCertificate 証明書の 20 バイトの SHA-1 ハッシュ (サムプリント) を格納します。 NULL
vtbl 8 HRESULT AddEnrollmentServer(LPWSTR strEnrollmentServerURI, X509EnrollmentAuthFlags authFlags, LPWSTR strCredential, LPWSTR strPassword)

証明書登録サーバー (CES) のアクセス資格情報を資格情報キャッシュに保存します。

strEnrollmentServerURILPWSTRin証明書登録サーバーの URL を格納する BSTR です。
authFlagsX509EnrollmentAuthFlagsin

クライアント認証の種類を指定する X509EnrollmentAuthFlags 列挙値です。次のいずれかの値を指定できます。

値 意味
X509AuthAnonymous
 匿名認証です。strCredential パラメーターと strPassword パラメーターを NULL に設定します。
X509AuthKerberos
 Kerberos 認証です。strCredential パラメーターと strPassword パラメーターを NULL に設定します。
X509AuthUsername
 クリアテキストのユーザー名とパスワードによる認証です。strCredential パラメーターと strPassword パラメーターに、ユーザー名とそれに対応するパスワードを設定します。これらの文字列は送信前に暗号化され、証明書登録サーバー上の資格情報コンテナーに安全に格納されます。
X509AuthCertificate
 ローカルコンピューターにインストールされ、サーバーがクライアントの ID を検証するために使用するクライアント認証証明書です。strPassword パラメーターを NULL に設定し、証明書のサムプリント (証明書の 20 バイトの SHA1 ハッシュ) を strCredential パラメーターに設定します。
strCredentialLPWSTRin資格情報を格納する BSTR です。
strPasswordLPWSTRinクリアテキストのパスワードを格納する BSTR です。

戻り値

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

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

戻り値 説明
E_INVALIDARG
 strEnrollmentServerURI パラメーターを NULL または空にすることはできません。

authFlags パラメーターに X509AuthAnonymous または X509AuthKerberos を指定した場合、strCredential パラメーターは NULL であってはなりません。

authFlags パラメーターに X509AuthCertificate を指定した場合、strCredential パラメーターは NULL でなければなりません。

authFlags パラメーターに X509AuthCertificate を指定した場合、strPassword パラメーターは NULL でなければなりませんが、strCredential パラメーターは NULL であってはなりません。
HRESULT_FROM_WIN32(ERROR_ARITHMETIC_OVERFLOW)
 strPassword、strCredential、または strEnrollmentServerURI パラメーターが 64,000 文字を超えているか、埋め込み null 文字を含んでいます。

解説(Remarks)

次の表に示すように、strCredential 引数と strPassword 引数は、authFlags 引数に指定された値に応じて変化します。

flag パラメーター strCredential パラメーター strPassword パラメーター
X509AuthAnonymous NULL NULL
X509AuthKerberos NULL NULL
X509AuthUsername CEP サーバーが認識するクリアテキストのユーザー名。 ユーザー名に対応するクリアテキストのパスワード。
X509AuthCertificate 証明書の 20 バイトの SHA-1 ハッシュ (サムプリント) を格納します。 NULL
vtbl 9 HRESULT Enroll(LPWSTR strEnrollmentPolicyServerURI, LPWSTR strTemplateName, EncodingType Encoding, WebEnrollmentFlags enrollFlags, LPWSTR* pstrCertificate)

証明書要求を登録(エンロール)し、発行された証明書を取得します。

strEnrollmentPolicyServerURILPWSTRin証明書登録ポリシーサーバーの URL を格納する BSTR です。
strTemplateNameLPWSTRinActive Directory に表示されるテンプレートの共通名 (CN)、またはドット区切りの 10 進数の オブジェクト識別子を格納する BSTR 変数です。
EncodingEncodingTypein表示のためにバイト配列に適用するエンコードの種類を指定する EncodingType 列挙値です。
enrollFlagsWebEnrollmentFlagsin

Web 登録の動作を指定する WebEnrollmentFlags 列挙値です。次の値を指定できます。

値 意味
EnrollPrompt
 このフラグが設定されており、証明書登録サーバーに使用できる認証資格情報がない場合、証明書サービスは資格情報の入力を求めます。認証資格情報がなく、このフラグも設定されていない場合、Enroll メソッドは失敗します。
pstrCertificateLPWSTR*out発行された証明書を格納する BSTR です。

戻り値

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

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

戻り値 説明
E_INVALIDARG
 strEnrollmentPolicyServerURI パラメーターと strTemplateName パラメーターを NULL にすることはできません。
HRESULT_FROM_WIN32(ERROR_ARITHMETIC_OVERFLOW)
 strEnrollmentPolicyServerURI パラメーターと strTemplateName パラメーターが 64,000 文字を超えているか、埋め込み null 文字を含んでいます。

解説(Remarks)

Enroll メソッドは、適切なテンプレートを取得し、InitializeFromTemplate を呼び出した後、IX509Enrollment オブジェクトの Enroll を呼び出します。

このメソッドは、発行された証明書をインストールしません。

vtbl 10 HRESULT Initialize(X509CertificateEnrollmentContext Context)

IX509EnrollmentHelper オブジェクトを初期化します。

ContextX509CertificateEnrollmentContextin

発行される証明書の対象となるエンドエンティティの性質を指定する X509CertificateEnrollmentContext 列挙値です。次のいずれかの値を指定できます。

値 意味
ContextUser
 証明書はエンドユーザーを対象としています。
ContextMachine
 証明書はコンピューターを対象としています。
ContextAdministratorForceMachine
 証明書は、コンピューターの代わりに管理者が要求しています。

戻り値

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

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

戻り値 説明
HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZED
 オブジェクトは既に初期化されています。
出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IX509EnrollmentHelper "{728AB351-217D-11DA-B2A4-000E7BBB2B09}"
#usecom global IX509EnrollmentHelper IID_IX509EnrollmentHelper "{}"
#comfunc global IX509EnrollmentHelper_AddPolicyServer      7 wstr,wstr,int,int,wstr,wstr
#comfunc global IX509EnrollmentHelper_AddEnrollmentServer  8 wstr,int,wstr,wstr
#comfunc global IX509EnrollmentHelper_Enroll               9 wstr,wstr,int,int,var
#comfunc global IX509EnrollmentHelper_Initialize           10 int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。