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

ICertSrvSetup

COMIDispatch (デュアル)
IDispatch を実装(デュアルインターフェース)。HSP では comobj 経由でメソッド名による遅延バインド呼び出しができます(vtableインデックス不要)。
IIDb760a1bb-4784-44c0-8f12-555f0780ff25継承元IDispatch呼び出し名前(IDispatch) または vtbl自前メソッド開始 vtbl7

公式ドキュメント

証明機関 (CA) 役割および証明機関 Web 登録役割を証明書サービス コンピューターにインストールおよびアンインストールするための機能を定義します。

メソッド 20

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

vtbl 7 HRESULT get_CAErrorId(INT* pVal)

失敗した証明機関 (CA) の指定に関する追加のエラー情報の ID を取得します。

pValINT*out直近の操作で発生したエラーの ID を受け取る INT へのポインタである。
vtbl 8 HRESULT get_CAErrorString(LPWSTR* pVal)

失敗した証明機関 (CA) の指定に関する追加のエラー情報の文字列データを取得します。

pValLPWSTR*out直近の操作で発生したエラーの説明文字列を受け取る LPWSTR へのポインタである。
vtbl 9 HRESULT InitializeDefaults(VARIANT_BOOL bServer, VARIANT_BOOL bClient)

証明機関役割をインストールできるようにするため、CCertSrvSetup オブジェクトを既定値で初期化します。

bServerVARIANT_BOOLinCA をコンピューターにインストールするかどうかを示す値です。VARIANT_TRUE は役割をインストールすることを示します。証明機関役割と証明機関 Web 登録役割のいずれも、あらかじめコンピューターにインストールされていてはなりません。
bClientVARIANT_BOOLin証明機関 Web 登録役割をコンピューターにインストールするかどうかを示す値です。VARIANT_TRUE は役割をインストールすることを示します。この役割はあらかじめコンピューターにインストールされていてはなりません。

解説(Remarks)

ポリシー ステートメント ファイル "CAPolicy.inf" がインストールされている場合、InitializeDefaults はそれを処理します。

vtbl 10 HRESULT GetCASetupProperty(CASetupProperty propertyId, VARIANT* pPropertyValue)

証明機関 (CA) 構成のプロパティ値を取得します。

propertyIdCASetupPropertyin取得するプロパティの種類を指定する CASetupProperty 列挙型の値です。
pPropertyValueVARIANT*outプロパティ値を指定する VARIANT 値です。VARIANT の型はプロパティの種類によって異なります。VARIANT の型の詳細については、CASetupProperty を参照してください。
vtbl 11 HRESULT SetCASetupProperty(CASetupProperty propertyId, VARIANT* pPropertyValue)

証明機関 (CA) 構成のプロパティ値を設定します。

propertyIdCASetupPropertyin

構成するプロパティの種類を指定する CASetupProperty 定数です。

次のプロパティは他のメソッドの副作用として設定されるため、このメソッドで直接設定することはできません。

ENUM_SETUPPROP_CANAME ENUM_SETUPPROP_CADSSUFFIX ENUM_SETUPPROP_EXPIRATIONDATE ENUM_SETUPPROP_PARENTCANAME ENUM_SETUPPROP_PARENTCAMACHINE ENUM_SETUPPROP_DATABASEDIRECTORY ENUM_SETUPPROP_LOGDIRECTORY ENUM_SETUPPROP_SHAREDFOLDER ENUM_SETUPPROP_WEBCAMACHINE ENUM_SETUPPROP_WEBCANAME

pPropertyValueVARIANT*inプロパティ値を指定する VARIANT へのポインターです。VARIANT の型はプロパティの種類によって異なります。VARIANT の型の詳細については、CASetupProperty を参照してください。
vtbl 12 HRESULT IsPropertyEditable(CASetupProperty propertyId, VARIANT_BOOL* pbEditable)

指定したプロパティが編集可能かどうかを呼び出し元に示します。

propertyIdCASetupPropertyin照会するプロパティの種類を指定する CASetupProperty 定数です。
pbEditableVARIANT_BOOL*outプロパティが編集可能かどうかを示す値です。
vtbl 13 HRESULT GetSupportedCATypes(VARIANT* pCATypes)

呼び出し元のコンテキストでコンピューターにインストールできる証明機関 (CA) の種類を取得します。

pCATypesVARIANT*outサポートされる CA を示す VT_UI4 型の VARIANT 配列へのポインターです。配列に格納され得る値は ENUM_CATYPES 列挙型で規定されます。
vtbl 14 HRESULT GetProviderNameList(VARIANT* pVal)

コンピューター上で非対称鍵の署名アルゴリズムを提供する暗号化サービス プロバイダー (CSP) の一覧を取得します。

pValVARIANT*outVT_BSTR 型の VARIANT 配列へのポインターです。各文字列は CSP の名前を表します。
vtbl 15 HRESULT GetKeyLengthList(LPWSTR bstrProviderName, VARIANT* pVal)

指定した暗号化サービス プロバイダー (CSP) がサポートする鍵長の一覧を取得します。(ICertSrvSetup.GetKeyLengthList)

bstrProviderNameLPWSTRinプロバイダーの名前を格納する文字列です。キー ストレージ プロバイダーの場合は、PublicKeyAlgorithmName#KeyStorageProviderName の形式で指定する必要があります (例: "RSA#Microsoft Software Key Storage provider")。
pValVARIANT*outCSP がサポートする鍵長に対応する VT_UI4 型の VARIANT 配列へのポインターです。
vtbl 16 HRESULT GetHashAlgorithmList(LPWSTR bstrProviderName, VARIANT* pVal)

指定した暗号化サービス プロバイダー (CSP) が非対称署名鍵アルゴリズムに対してサポートするハッシュ アルゴリズムの一覧を取得します。

bstrProviderNameLPWSTRinプロバイダー名を格納する文字列です。キー ストレージ プロバイダーの場合は、PublicKeyAlgorithmName#KeyStorageProviderName の形式で指定する必要があります (例: "RSA#Microsoft Software Key Storage provider")。
pValVARIANT*outVT_BSTR 型の VARIANT 配列へのポインターです。各文字列は CSP がサポートするハッシュ アルゴリズムの名前を表します。
vtbl 17 HRESULT GetPrivateKeyContainerList(LPWSTR bstrProviderName, VARIANT* pVal)

指定した暗号化サービス プロバイダー (CSP) が非対称署名鍵アルゴリズム用に格納しているキー コンテナー名の一覧を取得します。

bstrProviderNameLPWSTRinプロバイダーの名前を格納する文字列です。キー ストレージ プロバイダーの場合は、PublicKeyAlgorithmName#KeyStorageProviderName の形式で指定する必要があります (例: "RSA#Microsoft Software Key Storage provider")。
pValVARIANT*outVT_BSTR 型の VARIANT 配列へのポインターです。各文字列は指定した CSP が使用するキー コンテナーの名前を表します。
vtbl 18 HRESULT GetExistingCACertificates(ICertSrvSetupKeyInformationCollection** ppVal)

現在コンピューターにインストールされている有効な証明機関 (CA) 証明書を表す CertSrvSetupKeyInformation オブジェクトのコレクションを取得します。

ppValICertSrvSetupKeyInformationCollection**out"LocalMachine" ストアにインストールされている有効な CA 証明書一式の情報にアクセスするために使用できる ICertSrvSetupKeyInformationCollection インターフェイスへのポインターのアドレスです。

解説(Remarks)

CertSrvSetupKeyInformationCollection オブジェクトには有効な証明書が格納されます。証明書は次の条件を満たす場合に有効と見なされます。

vtbl 19 HRESULT CAImportPFX(LPWSTR bstrFileName, LPWSTR bstrPasswd, VARIANT_BOOL bOverwriteExistingKey, ICertSrvSetupKeyInformation** ppVal)

証明機関 (CA) 証明書とそれに関連付けられた秘密キーをローカル コンピューター ストアにインポートします。

bstrFileNameLPWSTRin秘密キー のインポートに使用する PFX ファイルの名前を格納する文字列です。
bstrPasswdLPWSTRinPFX ファイルのパスワードを格納する文字列です。
bOverwriteExistingKeyVARIANT_BOOLin同じ名前の既存のキーを上書きするかどうかを示す値です。
ppValICertSrvSetupKeyInformation**outインポートされた秘密キーのプロパティを設定するために使用できる ICertSrvSetupKeyInformation インターフェイスへのポインターのアドレスです。

解説(Remarks)

CAImportPFX メソッドは、入力パラメーターを使用して PFX ファイルを復号およびデコードし、キーと証明書をローカル コンピューター ストアにインストールします。証明書が次の条件を満たす場合、キーのインストール後に、このメソッドは ICertSrvSetupKeyInformation オブジェクトを呼び出し元に返します。

PFX ファイルに複数の証明書とキーが含まれている場合、CAImportPFX はそれらすべての証明書とキーをインストールします。ただし、返される ICertSrvSetupKeyInformation オブジェクトには、ファイル内の最後の CA 証明書のプロパティのみが格納されます。呼び出し元は ICertSrvSetupKeyInformation オブジェクトの使用を終えたら、Release メソッドを使用して解放する必要があります。
vtbl 20 HRESULT SetCADistinguishedName(LPWSTR bstrCADN, VARIANT_BOOL bIgnoreUnicode, VARIANT_BOOL bOverwriteExistingKey, VARIANT_BOOL bOverwriteExistingCAInDS)

証明機関 (CA) の共通名と、省略可能な識別名サフィックスを設定します。

bstrCADNLPWSTRin

CA の名前を CommonName,DistinguishedNameSuffix の形式で格納する文字列です。カンマ (,) と DistinguishedNameSuffix は省略可能です。

次の表は、コンピューター MyServer における識別名 (省略可能な識別名サフィックスを含む) の例を示します。

意味
CN=mydomain-MyServer-CA
MyDomain ドメインに属する MyServer コンピューターの共通名。
DC=MyDomain,DC=MyCompany,DC=com
識別名サフィックス (省略可能)
CN=MyDomain-MyServer-CA,DC=MyDomain,DC=MyCompany,DC=com
省略可能なサフィックスを含む識別名
bIgnoreUnicodeVARIANT_BOOLin名前情報の Unicode エンコードを許可するかどうかを示す値です。VARIANT_TRUE を指定すると Unicode エンコードが有効になります。
bOverwriteExistingKeyVARIANT_BOOLin同じ名前の秘密キーがコンピューター上に存在していても、bstrCADN の名前を許可するかどうかを示す値です。VARIANT_TRUE を指定すると、既存のキーを上書きできます。
bOverwriteExistingCAInDSVARIANT_BOOLin同じ識別名を持つ CA がディレクトリ サービスに存在していても、bstrCADN の名前を許可するかどうかを示す値です。VARIANT_TRUE を指定すると、既存のディレクトリ サービス エントリを上書きできます。

解説(Remarks)

成功すると、SetCADistinguishedName メソッドは ENUM_SETUPPROP_CANAME および ENUM_SETUPPROP_CADSSUFFIX プロパティの値を bstrCADN の名前に合わせて変更します。セットアップ プロパティの詳細については、CASetupProperty を参照してください。

失敗した場合、SetCADistinguishedName メソッドは CAErrorId および CAErrorString プロパティに追加のエラー情報を設定することがあります。

既存のキーとそれに関連付けられた証明書を使用して CA を構成する場合、このメソッドを呼び出してはなりません。関連付けられた証明書を使用せずに既存のキーのみを使用して CA を構成する場合、bstrCADN の共通名は、そのキーのサニタイズ済み ContainerName と一致している必要があります。

bstrCADN に UTF8 エンコードが含まれる場合は、CAPolicy.inf に適切なフラグを設定し、%windir% に配置してください。

vtbl 21 HRESULT SetDatabaseInformation(LPWSTR bstrDBDirectory, LPWSTR bstrLogDirectory, LPWSTR bstrSharedFolder, VARIANT_BOOL bForceOverwrite)

証明機関 (CA) 役割に関するデータベース関連の情報を設定します。

bstrDBDirectoryLPWSTRinCA データベース ファイルを格納するディレクトリの名前を格納する文字列です。このパラメーターは NULL または空文字列であってはなりません。
bstrLogDirectoryLPWSTRinCA データベースのログ ファイルを格納するディレクトリの名前を格納する文字列です。このパラメーターは NULL または空文字列であってはなりません。
bstrSharedFolderLPWSTRinこのパラメーターは将来の使用のために予約されており、NULL または空文字列である必要があります。
bForceOverwriteVARIANT_BOOLin指定したディレクトリ内の既存のデータベース ファイルを上書きするかどうかを示す値です。VARIANT_TRUE は既存のファイルを上書きすることを指定します。

解説(Remarks)

SetDatabaseInformation メソッドは、指定されたディレクトリが存在しない場合は作成します。

失敗した場合、SetDatabaseInformation メソッドは CAErrorId および CAErrorString プロパティに追加のエラー情報を設定することがあります。

vtbl 22 HRESULT SetParentCAInformation(LPWSTR bstrCAConfiguration)

下位 CA 構成における親証明機関 (CA) の情報を設定します。

bstrCAConfigurationLPWSTRin親 CA の有効な構成を格納する文字列です。文字列は ComputerName または ComputerName\CAName の形式である必要があります。ComputerName は親 CA をホストするコンピューターのネットワーク名、CAName は親 CA の共通名です。

解説(Remarks)

SetParentCAInformation メソッドは、親 CA コンピューターに ping を送信し、ネットワーク上で利用可能であることを確認します。

成功すると、SetParentCAInformation は下位 CA 構成の ENUM_SETUPPROP_PARENTCAMACHINE および ENUM_SETUPPROP_PARENTCANAME プロパティを設定します。 セットアップ プロパティの詳細については、CASetupProperty を参照してください。

vtbl 23 HRESULT SetWebCAInformation(LPWSTR bstrCAConfiguration)

証明機関 Web 登録役割で使用する証明機関 (CA) の情報を設定します。

bstrCAConfigurationLPWSTRinCA の有効な構成を格納する文字列です。文字列は ComputerName または ComputerName\CAName の形式である必要があります。ComputerName は CA をホストするコンピューターのネットワーク名、CAName は CA の共通名です。

解説(Remarks)

SetWebCAInformation メソッドは、CA コンピューターに ping を送信し、ネットワーク上で利用可能であることを確認します。

成功すると、SetWebCAInformation は証明機関 Web 登録役割の構成における ENUM_SETUPPROP_WEBCAMACHINE および ENUM_SETUPPROP_WEBCANAME プロパティを設定します。 セットアップ プロパティの詳細については、CASetupProperty を参照してください。

vtbl 24 HRESULT Install()

CCertSrvSetup オブジェクトで構成された役割をインストールします。

解説(Remarks)

CCertSrvSetup オブジェクトのこのメソッドや他のメソッドを呼び出す前に、InitializeDefaults メソッドを呼び出す必要があります。

キーが既に存在する場合を除き、Install メソッドは証明機関 (CA) 証明書用のキーを作成します。暗号化サービス プロバイダー (CSP) が対話操作を必要とする場合は、ユーザーに入力を求めます。

vtbl 25 HRESULT PreUnInstall(VARIANT_BOOL bClientOnly)

役割固有の状態情報を一時的に保存してから、その役割をアンインストールします。

bClientOnlyVARIANT_BOOLin呼び出し元が証明機関 Web 登録役割のみをアンインストールするかどうかを示す値です。VARIANT_TRUE は証明機関 Web 登録役割のみをアンインストールすることを指定します。これは、証明機関役割と証明機関 Web 登録役割の両方がコンピューターにインストールされている場合にのみ適用されます。

解説(Remarks)

PreUnInstall メソッドは、役割固有のアンインストールを実行する前に呼び出す必要があります。

vtbl 26 HRESULT PostUnInstall()

実装されていません。将来の使用のために予約されています。

戻り値

このメソッドは値を返しません。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_ICertSrvSetup "{B760A1BB-4784-44C0-8F12-555F0780FF25}"
#usecom global ICertSrvSetup IID_ICertSrvSetup "{}"
#comfunc global ICertSrvSetup_get_CAErrorId               7 var
#comfunc global ICertSrvSetup_get_CAErrorString           8 var
#comfunc global ICertSrvSetup_InitializeDefaults          9 int,int
#comfunc global ICertSrvSetup_GetCASetupProperty          10 int,var
#comfunc global ICertSrvSetup_SetCASetupProperty          11 int,var
#comfunc global ICertSrvSetup_IsPropertyEditable          12 int,var
#comfunc global ICertSrvSetup_GetSupportedCATypes         13 var
#comfunc global ICertSrvSetup_GetProviderNameList         14 var
#comfunc global ICertSrvSetup_GetKeyLengthList            15 wstr,var
#comfunc global ICertSrvSetup_GetHashAlgorithmList        16 wstr,var
#comfunc global ICertSrvSetup_GetPrivateKeyContainerList  17 wstr,var
#comfunc global ICertSrvSetup_GetExistingCACertificates   18 sptr
#comfunc global ICertSrvSetup_CAImportPFX                 19 wstr,wstr,int,sptr
#comfunc global ICertSrvSetup_SetCADistinguishedName      20 wstr,int,int,int
#comfunc global ICertSrvSetup_SetDatabaseInformation      21 wstr,wstr,wstr,int
#comfunc global ICertSrvSetup_SetParentCAInformation      22 wstr
#comfunc global ICertSrvSetup_SetWebCAInformation         23 wstr
#comfunc global ICertSrvSetup_Install                     24
#comfunc global ICertSrvSetup_PreUnInstall                25 int
#comfunc global ICertSrvSetup_PostUnInstall               26
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。
; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。