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

ICertRequest3

COMIDispatch (デュアル)
📘 Microsoft Learn (日本語) · English
✅ IDispatch を実装(デュアルインターフェース)。HSP では comobj 経由でメソッド名による遅延バインド呼び出しができます(vtableインデックス不要)。
IIDafc8f92b-33a2-4861-bf36-2933b7cd67b3継承元ICertRequest2呼び出し名前(IDispatch) または vtbl自前メソッド開始 vtbl20

公式ドキュメント

クライアントまたは中間アプリケーションと証明書サービス (Certificate Services) との間の通信を提供します。(ICertRequest3)

メソッド 4

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

vtbl 20 HRESULT SetCredential(INT hWnd, X509EnrollmentAuthFlags AuthType, LPWSTR strCredential, LPWSTR strPassword)

証明書登録 Web サービス (Certificate Enrollment Web Service) への接続に使用する資格情報を設定します。

hWndINTin

親ウィンドウのハンドルです。

資格情報を取得するための UI が表示される場合は、hWnd パラメーターを設定する必要があります。

証明書ベースの認可では、資格情報を取得するために UI プロンプトが必要な場合(たとえば、資格情報がスマートカード上にあり PIN の入力が必要な場合)にこのハンドルが使用されます。

Kerberos、匿名、またはユーザー名とパスワードによる認証を使用する場合、このパラメーターは無視されます。

AuthTypeX509EnrollmentAuthFlagsin

認証の種類を指定する X509EnrollmentAuthFlags 列挙型の値です。

値 意味
X509AuthAnonymous
 匿名認証。

strCredential パラメーターと strPassword パラメーターを NULL または空の文字列に設定します。
X509AuthCertificate
 ローカルコンピューターにインストールされたクライアント認証証明書です。この証明書には、(証明書には含まれない) 秘密キー に関連付けられた 公開キー が含まれます。この証明書は、クライアントの ID を検証するためにサーバーによって使用されます。

strCredential パラメーターには、呼び出し元を認証するために証明書登録 Web サービスに渡される、証明書のバイナリの 20 バイト SHA-1 ハッシュが含まれます。 strPassword パラメーターは NULL または空の文字列に設定します。 strCredential パラメーターは、該当する個人用の 証明書 ストアにインストールされた証明書を参照する必要があり、その証明書には呼び出し元がアクセスできる秘密キーが関連付けられていなければなりません。
X509AuthKerberos
 Kerberos 認証。

strCredential パラメーターと strPassword パラメーターを NULL または空の文字列に設定します。
X509AuthUsername
 平文のユーザー名とパスワードによる認証です。ユーザー名とパスワードは、クライアント上の資格情報コンテナー (credential vault) に保存される際に暗号化されます。

strCredential パラメーターと strPassword パラメーターには、呼び出し元を認証するために証明書登録 Web サービスでサポートされる、ユーザー名文字列と平文パスワードが含まれます。 登録サービス接続では常に Secure Sockets Layer プロトコル (SSL) が使用されるため、パスワードはネットワーク経由で送信される際に暗号化されます。
strCredentialLPWSTRin資格情報を含む文字列です。
strPasswordLPWSTRinパスワードを含む文字列です。

戻り値

戻り値 説明
E_INVALIDARG
 AuthType パラメーターは X509AuthKerberos である必要があります。

解説(Remarks)

SetCredential メソッドは、ICertRequest2::Submit メソッドを呼び出す前に呼び出す必要があります。

strCredential 引数と strPassword 引数は、次の表に示すように、AuthType パラメーターに指定された値に応じて変わります。

AuthType パラメーター strCredential パラメーター strPassword パラメーター
X509AuthAnonymous NULL NULL
X509AuthCertificate 証明書の 20 バイト SHA-1 ハッシュ(拇印) NULL
X509AuthKerberos NULL NULL
X509AuthUsername 証明書登録 Web サービスによって認識される平文のユーザー名 ユーザー名に関連付けられた平文のパスワード
vtbl 21 HRESULT GetRequestIdString(LPWSTR* pstrRequestId)

要求とそれに続く証明書について、現在の内部要求番号を文字列形式で取得します。

pstrRequestIdLPWSTR*out要求 ID 文字列を受け取る BSTR 変数へのポインターです。

戻り値

C++

メソッドが成功した場合、メソッドは S_OK を返します。

この関数が正常に完了すると、pstrRequestId パラメーターが指す文字列に要求 ID 文字列が設定されます。

メソッドが失敗した場合は、エラーを示す HRESULT 値を返します。一般的なエラーコードの一覧については、「Common HRESULT Values」を参照してください。

VB

戻り値は、要求とそれに続く証明書についての現在の内部要求番号を文字列として指定します。
vtbl 22 HRESULT GetIssuedCertificate2(LPWSTR strConfig, LPWSTR strRequestId, LPWSTR strSerialNumber, CR_DISP* pDisposition)

要求 ID 文字列または証明書のシリアル番号のいずれかを指定して、証明書の処理状態 (disposition) を取得します。

strConfigLPWSTRin

証明書サービス サーバーの有効な構成文字列を表します。この文字列は、登録サーバーの HTTPS URL か、または ComputerName\CAName 形式のいずれかです。ここで ComputerName はサーバーのネットワーク名、CAName は証明書サービスのセットアップ時に入力された 証明機関 (CA) の共通名です。構成文字列名については、 ICertConfig を参照してください。

Windows Server 2008、Windows Vista、Windows Server 2003、Windows XP: 入力として HTTPS URL はサポートされていません。

strRequestIdLPWSTRin

証明書サービスのデータベース内の 証明書要求 ID を表す BSTR 値です。要求 ID の代わりに(strSerialNumber として渡される)シリアル番号を使用する場合は、このパラメーターを NULL に設定します。

要求 ID 文字列を取得するには、ICertRequest3::GetRequestIdString メソッドを使用します。

strSerialNumberLPWSTRin

CA によって発行された証明書のシリアル番号を表す BSTR 値です。この文字列では、シリアル番号を偶数桁の 16 進数として指定する必要があります。必要に応じて、桁数を偶数にするために番号の先頭に 0 を付加できます。ただし、先頭に付加できる 0 は 1 つまでです。

strSerialNumber の値は、strRequestId が NULL に設定されている場合にのみ使用されます。

pDispositionCR_DISP*out

証明書の処理状態を表す LONG 値へのポインターです。処理状態は次の値のいずれかです。

値 意味
CR_DISP_DENIED
 要求が拒否されました。
CR_DISP_ERROR
 要求が失敗しました。
CR_DISP_INCOMPLETE
 要求が完了しませんでした。
CR_DISP_ISSUED
 証明書が発行されました。
CR_DISP_ISSUED_OUT_OF_BAND
 証明書が別途発行されました。
CR_DISP_UNDER_SUBMISSION
 要求が提出中として受理されました。

戻り値

C++

メソッドが成功した場合、メソッドは S_OK を返します。

メソッドが失敗した場合は、エラーを示す HRESULT 値を返します。一般的なエラーコードの一覧については、「Common HRESULT Values」を参照してください。

VB

戻り値は、証明書の処理状態を表す Long です。
vtbl 23 HRESULT GetRefreshPolicy(VARIANT_BOOL* pValue)

クライアントのキャッシュされた証明書登録ポリシーが古くなっており、更新が必要かどうかを示す値を返します。

pValueVARIANT_BOOL*out更新インジケーターを受け取る VARIANT_BOOL 変数へのポインターです。

戻り値

C++

メソッドが成功した場合、メソッドは S_OK を返します。

メソッドが失敗した場合は、エラーを示す HRESULT 値を返します。一般的なエラーコードの一覧については、「Common HRESULT Values」を参照してください。

VB

戻り値は、クライアントのポリシーサービスが古くなっているかどうかを示す BOOL です。

解説(Remarks)

GetRefreshPolicy メソッドは、登録サーバーがフォルト (fault) を返した場合にのみ TRUE を返します。GetRefreshPolicy メソッドを呼び出す前に、登録サーバーに接続する必要があります。フォルトが返された場合は、同じ ICertRequest3 インスタンスから GetRefreshPolicy メソッドを呼び出して、キャッシュされたポリシーが古くなっており更新が必要かどうかを判定します。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_ICertRequest3 "{AFC8F92B-33A2-4861-BF36-2933B7CD67B3}"
#usecom global ICertRequest3 IID_ICertRequest3 "{}"
#comfunc global ICertRequest3_SetCredential          20 int,int,wstr,wstr
#comfunc global ICertRequest3_GetRequestIdString     21 var
#comfunc global ICertRequest3_GetIssuedCertificate2  22 wstr,wstr,wstr,var
#comfunc global ICertRequest3_GetRefreshPolicy       23 var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。