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

ICertificateEnrollmentPolicyServerSetup

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

公式ドキュメント

ICertificateEnrollmentPolicyServerSetup インターフェイスは、Active Directory 証明書サービス (ADCS) における証明書登録ポリシー (CEP) Web サービスを表します。

メソッド 6

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

vtbl 7 HRESULT get_ErrorString(LPWSTR* pVal)

証明書登録ポリシー (CEP) Web サービスのセットアップ失敗に関する追加情報を含む文字列を取得します。

pValLPWSTR*out直近の操作で発生したエラーの説明文字列を受け取る LPWSTR へのポインタである。

解説(Remarks)

ICertificateEnrollmentPolicyServerSetup インターフェイスのいずれかのメソッドを呼び出すと、このプロパティ値は空のエラー文字列にリセットされます。

vtbl 8 HRESULT InitializeInstallDefaults()

ICertificateEnrollmentPolicyServerSetup オブジェクトを既定の構成で初期化します。

戻り値

戻り値 説明
E_ACCESSDENIED
 ユーザーはドメイン ルートまたはエンタープライズの管理者である必要があります。また、コンピューターはドメインに参加している必要があります。

ユーザーがドメイン ルート管理者またはエンタープライズ管理者でない場合、ErrorString プロパティには次の値が設定されます。

"セットアップを実行するには、Enterprise Admins グループのメンバーである必要があります。"

コンピューターがドメインに参加していない場合、ErrorString プロパティには次の値が設定されます。

"証明書登録 Web サービスまたは証明書登録ポリシー Web サービスは、ドメインのメンバーではないコンピューターにはインストールできません。"
HRESULT_FROM_WIN32(ERROR_INVALID_STATE)
 ICertificateEnrollmentPolicyServerSetup オブジェクトは既に初期化されています。ErrorString プロパティには次の値が設定されます。

"セットアップ オブジェクトは既に初期化されています。このオブジェクトを複数回初期化することはできません。"

解説(Remarks)

このメソッドは次の処理を実行します。

UnInstall 以外のメソッドを呼び出す前に、InitializeInstallDefaults メソッドを呼び出す必要があります。構成した CEP サービスをインストールするには Install メソッドを呼び出します。サービスを削除するには、新しい ICertificateEnrollmentPolicyServerSetup オブジェクトに対して UnInstall メソッドを呼び出します。
vtbl 9 HRESULT GetProperty(CEPSetupProperty propertyId, VARIANT* pPropertyValue)

証明書登録ポリシー (CEP) Web サービスの構成について、CEPSetupProperty 列挙値を取得します。

propertyIdCEPSetupPropertyin

取得するプロパティ値を指定する CEPSetupProperty 列挙型の値です。有効な値は次のとおりです。

値 説明
ENUM_CEPSETUPPROP_AUTHENTICATION pPropertyValue パラメーターには、使用する認証の種類を示す値が格納されます。
ENUM_CEPSETUPPROP_SSLCERTHASH pPropertyValue パラメーターには、認証時に使用される証明書 (存在する場合) のハッシュが格納されます。
ENUM_CEPSETUPPROP_KEYBASED_RENEWAL pPropertyValue パラメーターは、KeyBasedRenewal テンプレートのポリシーのみを返すモードで登録ポリシー サーバーをセットアップするかどうかを指定します。
ENUM_CEPSETUPPROP_URL CEP サービスの URL を格納します。GetProperty メソッドが正常に終了した場合、pPropertyValue 引数には "https://computerDNSname/ADPolicyProvider_cep_AuthenticationType/service.svc/cep" の形式の URL を含む VT_BSTR サブタイプが格納されます。認証の種類には次のいずれかを指定できます。
  • kerberos
  • usernamepassword
  • certificate
pPropertyValueVARIANT*out

プロパティ値を格納する VARIANT 変数へのポインターです。

propertyId パラメーターに ENUM_CEPSETUPPROP_AUTHENTICATION を指定した場合、GetProperty メソッドが正常に終了すると、pPropertyValue パラメーターには次のいずれかの定数が格納されます。

  • X509AuthKerberos
  • X509AuthUsername
  • X509AuthCertificate

propertyId パラメーターに ENUM_CEPSETUPPROP_SSLCERTHASH を指定した場合、GetProperty メソッドが正常に終了すると、pPropertyValue パラメーターにはハッシュを含む VT_BSTR サブタイプが格納されます。

propertyId パラメーターに ENUM_CEPSETUPPROP_AUTHENTICATION を指定した場合、pPropertyValue パラメーターには認証手順が格納されます。

propertyId パラメーターに ENUM_CEPSETUPPROP_URL を指定した場合、pPropertyValue パラメーターには証明書登録ポリシー (CEP) Web サービスの URL が格納されます。

propertyId パラメーターに ENUM_CEPSETUPPROP_KEYBASED_RENEWAL を指定した場合、pPropertyValue パラメーターには、KeyBasedRenewal テンプレートのポリシーのみを返すモードで登録ポリシー サーバーをセットアップするかどうかを示す VT_BOOL サブタイプを設定する必要があります。

戻り値

戻り値 説明
E_INVALIDARG
 propertyId 引数が CEPSetupProperty 列挙型のメンバーではありません。
E_POINTER
 pPropertyValue パラメーターに NULL を指定することはできません。
HRESULT_FROM_WIN32(ERROR_INVALID_STATE)
 ICertificateEnrollmentPolicyServerSetup オブジェクトが初期化されていません。

ErrorString プロパティ値には "セットアップ オブジェクトが初期化されていません。InitializeInstallDefaults メソッドでセットアップ オブジェクトを初期化してください。" が設定されます。
vtbl 10 HRESULT SetProperty(CEPSetupProperty propertyId, VARIANT* pPropertyValue)

証明書登録ポリシー (CEP) Web サービスの構成について、CEPSetupProperty 列挙値を指定します。

propertyIdCEPSetupPropertyin

設定するプロパティ値を指定する CEPSetupProperty 列挙型の値です。有効な値は次のとおりです。

値 説明
ENUM_CEPSETUPPROP_AUTHENTICATION pPropertyValue パラメーターには、使用する認証の種類を示す値が格納されます。
ENUM_CEPSETUPPROP_SSLCERTHASH pPropertyValue パラメーターには、認証時に使用される証明書 (存在する場合) のハッシュが格納されます。ENUM_CEPSETUPPROP_AUTHENTICATION は X509AuthCertificate に設定されている必要があります。
ENUM_CEPSETUPPROP_KEYBASED_RENEWAL pPropertyValue パラメーターは、KeyBasedRenewal テンプレートのポリシーのみを返すモードで登録ポリシー サーバーをセットアップするかどうかを指定します。
ENUM_CEPSETUPPROP_URL この値は指定できません。
pPropertyValueVARIANT*in

プロパティ値を格納する VARIANT 変数へのポインターです。

propertyId パラメーターに ENUM_CEPSETUPPROP_AUTHENTICATION を指定する場合、VARIANT のサブタイプは VT_I2、VT_I4、または VT_UII4 である必要があり、pPropertyValue 引数は次のいずれかの定数である必要があります。

  • X509AuthKerberos
  • X509AuthUsername
  • X509AuthCertificate

propertyId パラメーターに ENUM_CEPSETUPPROP_SSLCERTHASH を指定する場合、pPropertyValue パラメーターには、認証に使用する証明書のハッシュを含む VT_BSTR サブタイプを設定する必要があります。

propertyId パラメーターに ENUM_CEPSETUPPROP_AUTHENTICATION を指定した場合、pPropertyValue パラメーターには認証手順が格納されます。

propertyId パラメーターに ENUM_CEPSETUPPROP_URL を指定した場合、pPropertyValue パラメーターには証明書登録ポリシー (CEP) Web サービスの URL が格納されます。

propertyId パラメーターに ENUM_CEPSETUPPROP_KEYBASED_RENEWAL を指定する場合、pPropertyValue パラメーターには、KeyBasedRenewal テンプレートのポリシーのみを返すモードで登録ポリシー サーバーをセットアップするかどうかを示す VT_BOOL サブタイプを設定する必要があります。

戻り値

戻り値 説明
E_INVALIDARG
 propertyId 引数が CEPSetupProperty 列挙型のメンバーではないか、ENUM_CEPSETUPPROP_URL の値を設定しようとしました。
E_POINTER
 pPropertyValue パラメーターに NULL を指定することはできません。
HRESULT_FROM_WIN32(ERROR_INVALID_STATE)
 ICertificateEnrollmentPolicyServerSetup オブジェクトが初期化されていません。

ErrorString プロパティ値には "セットアップ オブジェクトが初期化されていません。InitializeInstallDefaults メソッドでセットアップ オブジェクトを初期化してください。" が設定されます。
HRESULT_FROM_WIN32(ERROR_CLUSTER_PROPERTY_DATA_TYPE_MISMATCH)
 ENUM_CEPSETUPPROP_AUTHENTICATION プロパティを設定する場合、VARIANT のサブタイプは VT_I2、VT_I4、または VT_UI4 である必要があります。

解説(Remarks)

SetProperty メソッドを呼び出す前に、InitializeInstallDefaults を呼び出す必要があります。

vtbl 11 HRESULT Install()

ICertificateEnrollmentPolicyServerSetup オブジェクトで構成された証明書登録ポリシー (CEP) Web サービスをインストールします。

戻り値

戻り値 説明
E_UNEXPECTED
 イベント トレース ディレクトリまたはアプリケーション ディレクトリとして指定された名前は既に存在していましたが、ディレクトリではなくファイルを指していました。
HRESULT_FROM_WIN32(ERROR_ALREADY_EXISTS)
 CEP アプリケーションが既に存在します。詳細については「解説」を参照してください。
HRESULT_FROM_WIN32(ERROR_INVALID_STATE)
 ICertificateEnrollmentPolicyServerSetup オブジェクトが初期化されていません。

ErrorString プロパティ値には "セットアップ オブジェクトが初期化されていません。InitializeInstallDefaults メソッドでセットアップ オブジェクトを初期化してください。" が設定されます。

解説(Remarks)

この関数は次の処理を実行します。

vtbl 12 HRESULT UnInstall(VARIANT* pAuthKeyBasedRenewal)

証明書登録ポリシー (CEP) Web サービスを削除します。

pAuthKeyBasedRenewalVARIANT*in

認証の種類と、省略可能な KeyBasedRenewal の値を格納する VARIANT 配列へのポインターです。

配列の最初の要素には、認証の種類として次の値を設定できます。

  • X509AuthKerberos
  • X509AuthUserName
  • X509AuthCertificate
配列の 2 番目 (省略可能) の要素の値は、KeyBasedRenewal の CEP の場合は VARIANT_TRUE です。

戻り値

戻り値 説明
E_ACCESSDENIED
 ユーザーはローカル管理者である必要があります。

ErrorString プロパティ値には "このセットアップを実行するには、ローカル コンピューターの管理者である必要があります。" が設定されます。
HRESULT_FROM_WIN32(ERROR_INVALID_STATE)
 ICertificateEnrollmentPolicyServerSetup オブジェクトが初期化されています。オブジェクトは、InitializeInstallDefaults の呼び出しが成功したときに初期化されます。

ErrorString プロパティ値には "オブジェクトは初期化されています。初期化済みのオブジェクトに対して UnInstall を呼び出すことはできません。" が設定されます。

解説(Remarks)

このメソッドを呼び出して CEP サービスを削除できます。ただし、既に初期化されている ICertificateEnrollmentPolicyServerSetup オブジェクトに対して UnInstall メソッドを呼び出すことはできないため、UnInstall を呼び出す前に新しい ICertificateEnrollmentPolicyServerSetup を作成する必要があります。

pAuthKeyBasedRenewal パラメーターが NULL の場合、この関数は次の処理を実行します。

pAuthKeyBasedRenewal パラメーターに認証の種類と KeyBasedRenewal の値が格納されている場合、この関数は上記の処理を実行しますが、pAuthKeyBasedRenewal に設定された値に対応するアプリケーションのみを削除し、その他のアプリケーションはそのまま残します。
出典・ライセンス: 上記「公式ドキュメント」の内容は 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_ICertificateEnrollmentPolicyServerSetup "{859252CC-238C-4A88-B8FD-A37E7D04E68B}"
#usecom global ICertificateEnrollmentPolicyServerSetup IID_ICertificateEnrollmentPolicyServerSetup "{}"
#comfunc global ICertificateEnrollmentPolicyServerSetup_get_ErrorString            7 var
#comfunc global ICertificateEnrollmentPolicyServerSetup_InitializeInstallDefaults  8
#comfunc global ICertificateEnrollmentPolicyServerSetup_GetProperty                9 int,var
#comfunc global ICertificateEnrollmentPolicyServerSetup_SetProperty                10 int,var
#comfunc global ICertificateEnrollmentPolicyServerSetup_Install                    11
#comfunc global ICertificateEnrollmentPolicyServerSetup_UnInstall                  12 var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。