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

IX509SCEPEnrollment

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

公式ドキュメント

X.509 Simple Computer Enrollment Protocol インターフェイス

メソッド 22

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

vtbl 7 HRESULT Initialize(IX509CertificateRequestPkcs10* pRequest, LPWSTR strThumbprint, EncodingType ThumprintEncoding, LPWSTR strServerCertificates, EncodingType Encoding)

新しい要求に備えてインスタンスを初期化します。

pRequestIX509CertificateRequestPkcs10*inoptionalすでに初期化済みの要求のインスタンス。
strThumbprintLPWSTRinCA 証明書の拇印(サムプリント)。
ThumprintEncodingEncodingTypeinCA 証明書の拇印のエンコード。
strServerCertificatesLPWSTRinCA 証明書および SCEP RA 証明書を含む PKCS7 要求。
EncodingEncodingTypein要求のエンコードの種類。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

このメソッドは、いずれも CA 証明書によって署名された、SCEP サーバー署名 EA 証明書と SCEP サーバー暗号化 EA 証明書を必要とします。

必要な証明書のいずれかが欠けている場合、または拇印が CA 証明書と一致しない場合、このメソッドは失敗します。

vtbl 8 HRESULT InitializeForPending(X509CertificateEnrollmentContext Context)

発行済みの証明書を取得するメッセージ、または発行者による以前の要求への応答をインストールするメッセージを生成できるように、インスタンスを初期化します。

ContextX509CertificateEnrollmentContextin保留中の SCEP 要求を扱う登録コンテキストを指定する X509CertificateEnrollmentContext 列挙値である。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 9 HRESULT CreateRequestMessage(EncodingType Encoding, LPWSTR* pValue)

チャレンジパスワードを含む PKCS10 要求メッセージを作成します。要求メッセージは、SCEP サーバー暗号化証明書で暗号化され、サーバー署名証明書で署名された、エンベロープ化された PKCS7 に格納されます。

EncodingEncodingTypein生成する要求メッセージ文字列のエンコーディング種別を指定する EncodingType 列挙値である。
pValueLPWSTR*out生成された SCEP 要求(PKICertReq)メッセージを指定エンコーディングの文字列として受け取るポインタである。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

このメソッドを呼び出す前に、Initialize メソッドを呼び出す必要があります。

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

証明書のポーリング(手動登録(エンロール))用のメッセージを作成します。

EncodingEncodingTypein生成するメッセージ文字列のエンコーディング種別を指定する EncodingType 列挙値である。
pValueLPWSTR*out保留中要求の状態を問い合わせる SCEP メッセージを指定エンコーディングの文字列として受け取るポインタである。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

このメソッドを呼び出す前に、InitializeForPending メソッドを呼び出す必要があります。

vtbl 11 HRESULT CreateRetrieveCertificateMessage(X509CertificateEnrollmentContext Context, LPWSTR strIssuer, EncodingType IssuerEncoding, LPWSTR strSerialNumber, EncodingType SerialNumberEncoding, EncodingType Encoding, LPWSTR* pValue)

以前に発行された証明書を取得します。

ContextX509CertificateEnrollmentContextinメッセージ作成時の登録コンテキストを指定する X509CertificateEnrollmentContext 列挙値である。
strIssuerLPWSTRinASN.1 でエンコードされた発行者名。
IssuerEncodingEncodingTypeinstrIssuer のエンコーディング種別を指定する EncodingType 列挙値である。
strSerialNumberLPWSTRin取得対象証明書のシリアル番号を指定エンコーディングの文字列で指定する。
SerialNumberEncodingEncodingTypeinstrSerialNumber のエンコーディング種別を指定する EncodingType 列挙値である。
EncodingEncodingTypein生成するメッセージ文字列のエンコーディング種別を指定する EncodingType 列挙値である。
pValueLPWSTR*out発行済み証明書を取得する SCEP メッセージを指定エンコーディングの文字列として受け取るポインタである。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

このメソッドを呼び出す前に、InitializeForPending メソッドを呼び出す必要があります。

vtbl 12 HRESULT ProcessResponseMessage(LPWSTR strResponse, EncodingType Encoding, X509SCEPDisposition* pDisposition)

応答メッセージを処理し、メッセージの処理結果(disposition)を返します。

strResponseLPWSTRinSCEP サーバーから受け取った応答メッセージを指定エンコーディングの文字列で渡す。
EncodingEncodingTypeinstrResponse のエンコーディング種別を指定する EncodingType 列挙値である。
pDispositionX509SCEPDisposition*out応答処理の結果(成功/保留/失敗)を表す X509SCEPDisposition 値を受け取るポインタである。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

このメソッドを呼び出す前に、Initialize メソッドおよび CreateRequestMessage メソッド、または InitializeForPending メソッドを呼び出す必要があります。

vtbl 13 HRESULT put_ServerCapabilities(LPWSTR Value)

要求に対して優先されるハッシュアルゴリズムと暗号化アルゴリズムを設定します。

ValueLPWSTRinSCEP サーバーがサポートする機能(GetCACaps の応答)を文字列で指定する。

解説(Remarks)

このプロパティを設定しない場合は、既定のハッシュアルゴリズムと暗号化アルゴリズムが使用されます。

このプロパティは、CreateRequestMessageCreateRetrievePendingMessage、または CreateRetrieveCertificateMessage メソッドを呼び出す前に設定する必要があります。

vtbl 14 HRESULT get_FailInfo(X509SCEPFailInfo* pValue)

ProcessResponseMessage メソッドが失敗した環境を検出したときの情報を取得します。

pValueX509SCEPFailInfo*outSCEP 要求が失敗した場合の理由を表す X509SCEPFailInfo 値を受け取るポインタである。
vtbl 15 HRESULT get_SignerCertificate(ISignerCertificate** ppValue)

要求の署名者証明書を取得または設定します。(Get)

ppValueISignerCertificate**outSCEP メッセージの署名に使用する署名証明書を表す ISignerCertificate オブジェクトを受け取るポインタである。

解説(Remarks)

更新(renewal)要求を作成するには、CreateRequestMessage メソッドを呼び出す前にこのプロパティを設定する必要があります。設定しない場合、CreateRequestMessage メソッドは新しい要求を作成し、内側の PKCSV10 要求と同じ秘密キーを使用して自己署名証明書を生成します。

vtbl 16 HRESULT put_SignerCertificate(ISignerCertificate* pValue)

要求の署名者証明書を取得または設定します。(Put)

pValueISignerCertificate*inoptionalSCEP メッセージの署名に使用する署名証明書を表す ISignerCertificate オブジェクトを渡す。

解説(Remarks)

更新(renewal)要求を作成するには、CreateRequestMessage メソッドを呼び出す前にこのプロパティを設定する必要があります。設定しない場合、CreateRequestMessage メソッドは新しい要求を作成し、内側の PKCSV10 要求と同じ秘密キーを使用して自己署名証明書を生成します。

vtbl 17 HRESULT get_OldCertificate(ISignerCertificate** ppValue)

要求が置き換える対象となる古い証明書を取得または設定します。(Get)

ppValueISignerCertificate**out更新元となる旧証明書を表す ISignerCertificate オブジェクトを受け取るポインタである。

解説(Remarks)

このプロパティは、CreateRequestMessage メソッドを呼び出す前に設定する必要があります。

vtbl 18 HRESULT put_OldCertificate(ISignerCertificate* pValue)

要求が置き換える対象となる古い証明書を取得または設定します。(Put)

pValueISignerCertificate*inoptional更新元となる旧証明書を表す ISignerCertificate オブジェクトを渡す。

解説(Remarks)

このプロパティは、CreateRequestMessage メソッドを呼び出す前に設定する必要があります。

vtbl 19 HRESULT get_TransactionId(EncodingType Encoding, LPWSTR* pValue)

要求のトランザクション ID を取得または設定します。(Get)

EncodingEncodingTypein取得するトランザクション ID 文字列のエンコーディング種別を指定する EncodingType 列挙値である。
pValueLPWSTR*outSCEP トランザクション ID を指定エンコーディングの文字列として受け取るポインタである。

解説(Remarks)

トランザクション ID を指定しない場合は、CreateRequestMessage メソッドが 1 つ作成します。トランザクション ID が設定されていない場合、または CreateRequestMessage メソッドが呼び出されていない場合、このプロパティは CERTSRV_E_PROPERTY_EMPTY を返します。

保留中の要求を処理した後、呼び出し元はこの値を保存しておく必要があります。これは、後で CreateRetrievePendingMessage メソッドを呼び出し、発行された証明書をポーリングするために SCEP サーバーへ送信するメッセージを整形する際に使用します。

応答をインストールするために IX509SCEPEnrollment インターフェイスの新しいインスタンスを使用する場合は、ProcessResponseMessage メソッドを呼び出す前にこのプロパティを設定してください。

取得メッセージを作成するために IX509SCEPEnrollment インターフェイスの新しいインスタンスを使用する場合は、CreateRetrievePendingMessage メソッドを呼び出す前にこのプロパティを設定してください。

vtbl 20 HRESULT put_TransactionId(EncodingType Encoding, LPWSTR Value)

要求のトランザクション ID を取得または設定します。(Put)

EncodingEncodingTypein渡すトランザクション ID 文字列のエンコーディング種別を指定する EncodingType 列挙値である。
ValueLPWSTRinSCEP トランザクション ID を指定エンコーディングの文字列として渡す。

解説(Remarks)

トランザクション ID を指定しない場合は、CreateRequestMessage メソッドが 1 つ作成します。トランザクション ID が設定されていない場合、または CreateRequestMessage メソッドが呼び出されていない場合、このプロパティは CERTSRV_E_PROPERTY_EMPTY を返します。

保留中の要求を処理した後、呼び出し元はこの値を保存しておく必要があります。これは、後で CreateRetrievePendingMessage メソッドを呼び出し、発行された証明書をポーリングするために SCEP サーバーへ送信するメッセージを整形する際に使用します。

応答をインストールするために IX509SCEPEnrollment インターフェイスの新しいインスタンスを使用する場合は、ProcessResponseMessage メソッドを呼び出す前にこのプロパティを設定してください。

取得メッセージを作成するために IX509SCEPEnrollment インターフェイスの新しいインスタンスを使用する場合は、CreateRetrievePendingMessage メソッドを呼び出す前にこのプロパティを設定してください。

vtbl 21 HRESULT get_Request(IX509CertificateRequestPkcs10** ppValue)

内側の PKCS10 要求を取得します。

ppValueIX509CertificateRequestPkcs10**outこの SCEP 登録に関連付けられた PKCS#10 証明書要求 IX509CertificateRequestPkcs10 オブジェクトを受け取るポインタである。

解説(Remarks)

内側の PKCS10 要求インスタンスを使用すると、CreateRequestMessage メソッドを呼び出す前に、サブジェクト、拡張、秘密キーのプロパティ、暗号化アルゴリズムとその強度、およびハッシュアルゴリズムを設定できます。

vtbl 22 HRESULT get_CertificateFriendlyName(LPWSTR* pValue)

証明書のフレンドリ名を取得または設定します。(Get)

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

証明書のフレンドリ名を取得または設定します。(Put)

ValueLPWSTRin発行された証明書に設定する表示名(フレンドリ名)を文字列で指定する。
vtbl 24 HRESULT get_Status(IX509EnrollmentStatus** ppValue)

要求の状態を取得します。

ppValueIX509EnrollmentStatus**outSCEP 登録の処理状態を表す IX509EnrollmentStatus オブジェクトを受け取るポインタである。
vtbl 25 HRESULT get_Certificate(EncodingType Encoding, LPWSTR* pValue)

要求の証明書を取得します。

EncodingEncodingTypein取得する証明書文字列のエンコーディング種別を指定する EncodingType 列挙値である。
pValueLPWSTR*outSCEP 登録で発行された証明書を指定エンコーディングの文字列として受け取るポインタである。
vtbl 26 HRESULT get_Silent(VARIANT_BOOL* pValue)
pValueVARIANT_BOOL*outサイレント(UI を抑制する)モードが有効かどうかを表す VARIANT_BOOL を受け取るポインタである。
vtbl 27 HRESULT put_Silent(VARIANT_BOOL Value)

要求中に UI を許可するかどうかを取得または設定します。

ValueVARIANT_BOOLinUI を表示しないサイレントモードの有効・無効を VARIANT_BOOL で指定する。
vtbl 28 HRESULT DeleteRequest()

要求のために作成された証明書やキーをすべて削除します。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

このメソッドを呼び出す前に、TransactionId プロパティを設定し、InitializeForPending メソッドを呼び出す必要があります。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IX509SCEPEnrollment "{728AB361-217D-11DA-B2A4-000E7BBB2B09}"
#usecom global IX509SCEPEnrollment IID_IX509SCEPEnrollment "{}"
#comfunc global IX509SCEPEnrollment_Initialize                        7 sptr,wstr,int,wstr,int
#comfunc global IX509SCEPEnrollment_InitializeForPending              8 int
#comfunc global IX509SCEPEnrollment_CreateRequestMessage              9 int,var
#comfunc global IX509SCEPEnrollment_CreateRetrievePendingMessage      10 int,var
#comfunc global IX509SCEPEnrollment_CreateRetrieveCertificateMessage  11 int,wstr,int,wstr,int,int,var
#comfunc global IX509SCEPEnrollment_ProcessResponseMessage            12 wstr,int,var
#comfunc global IX509SCEPEnrollment_put_ServerCapabilities            13 wstr
#comfunc global IX509SCEPEnrollment_get_FailInfo                      14 var
#comfunc global IX509SCEPEnrollment_get_SignerCertificate             15 sptr
#comfunc global IX509SCEPEnrollment_put_SignerCertificate             16 sptr
#comfunc global IX509SCEPEnrollment_get_OldCertificate                17 sptr
#comfunc global IX509SCEPEnrollment_put_OldCertificate                18 sptr
#comfunc global IX509SCEPEnrollment_get_TransactionId                 19 int,var
#comfunc global IX509SCEPEnrollment_put_TransactionId                 20 int,wstr
#comfunc global IX509SCEPEnrollment_get_Request                       21 sptr
#comfunc global IX509SCEPEnrollment_get_CertificateFriendlyName       22 var
#comfunc global IX509SCEPEnrollment_put_CertificateFriendlyName       23 wstr
#comfunc global IX509SCEPEnrollment_get_Status                        24 sptr
#comfunc global IX509SCEPEnrollment_get_Certificate                   25 int,var
#comfunc global IX509SCEPEnrollment_get_Silent                        26 var
#comfunc global IX509SCEPEnrollment_put_Silent                        27 int
#comfunc global IX509SCEPEnrollment_DeleteRequest                     28
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。
; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。