IServerSecurity
COM公式ドキュメント
IServerSecurity (objidlbase.h) インターフェイスは、クライアントの認証や、クライアントの偽装(impersonation)の管理を支援するためにサーバーが使用します。
メソッド 4
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
IServerSecurity::QueryBlanket (objidlbase.h) メソッドは、サーバーのいずれかのメソッドを呼び出したクライアントに関する情報を取得します。
| pAuthnSvc | DWORD* | outoptional | 現在の認証サービスへのポインター。これは 認証サービス定数 の一覧から取得される単一の値です。呼び出し元が NULL を指定した場合、現在の認証サービスは取得されません。 |
| pAuthzSvc | DWORD* | outoptional | 現在の承認(authorization)サービスを受け取る変数へのポインター。これは 承認定数 の一覧に含まれる単一の値です。呼び出し元が NULL を指定した場合、現在の承認サービスは取得されません。 |
| pServerPrincName | WORD** | out | 現在のプリンシパル名。この文字列は呼び出される側が CoTaskMemAlloc を使用して割り当てるため、呼び出し元は CoTaskMemFree を使用して解放する必要があります。既定では、Schannel のプリンシパル名は msstd 形式になります。pCapabilities パラメーターに EOAC_MAKE_FULLSIC を指定した場合は fullsic 形式が返されます。msstd 形式および fullsic 形式の詳細については、Principal Names を参照してください。呼び出し元が NULL を指定した場合、現在のプリンシパル名は取得されません。 |
| pAuthnLevel | DWORD* | outoptional | 現在の認証レベルを受け取る変数へのポインター。これは 認証レベル定数 の一覧から取得される単一の値です。呼び出し元が NULL を指定した場合、現在の認証レベルは取得されません。 |
| pImpLevel | DWORD* | outoptional | このパラメーターは NULL でなければなりません。 |
| pPrivs | void** | out | クライアント アプリケーションの特権情報。このハンドルが参照する構造体の形式は、認証サービスによって異なります。アプリケーションはこのメモリに書き込んだり、解放したりしてはなりません。この情報は現在の呼び出しの間のみ有効です。NTLMSSP および Kerberos の場合、これは SEC_WINNT_AUTH_IDENTITY または SEC_WINNT_AUTH_IDENTITY_EX 構造体です。Schannel の場合、これはクライアントの証明書を表す CERT_CONTEXT 構造体です。クライアントが証明書を持たない場合は NULL が返されます。呼び出し元が NULL を指定した場合、現在の特権情報は取得されません。 |
| pCapabilities | DWORD* | inoutoptional | 呼び出しのケーパビリティ。認証サービスが Schannel である場合にプリンシパル名を fullsic 形式で返すよう要求するには、呼び出し元はこのパラメーターに EOAC_MAKE_FULLSIC フラグを設定できます。呼び出し元が NULL を指定した場合、現在のケーパビリティは取得されません。 |
戻り値
このメソッドは、標準の戻り値 E_INVALIDARG、E_OUTOFMEMORY、および S_OK を返すことがあります。
解説(Remarks)
QueryBlanket は、サーバーが自身のいずれかのメソッドを呼び出したクライアントについての情報を得るために使用します。現在のスレッド上の現在の呼び出しに対する IServerSecurity へのポインターを取得するには、IID_IServerSecurity を指定して CoGetCallContext を呼び出します。このインターフェイス ポインターは、呼び出しと同じアパートメント内で、かつ呼び出しの間に限り使用できます。
IServerSecurity::ImpersonateClient (objidlbase.h) メソッドは、サーバーが呼び出しの間クライアントを偽装できるようにします。
戻り値
解説(Remarks)
通常、メソッドはプロセスのアクセス トークンを使用するスレッド上で実行されます。しかし、クライアントを偽装している間、サーバーはクライアントのセキュリティ コンテキスト内で実行されるため、クライアントがアクセスできるリソースにサーバーもアクセスできるようになります。偽装が必要な場合、サーバーは ImpersonateClient メソッドを呼び出して、クライアントの資格情報を表すアクセス トークンを現在のスレッドに割り当てます。このスレッド トークンはアクセス チェックに使用されます。RevertToSelf は現在のスレッドのアクセス トークンを元に戻します。
サーバーがクライアントの代理として何を実行できるかは、クライアントが設定する偽装レベルに依存します。偽装レベルは 偽装レベル定数 のいずれか 1 つを使用して指定します。サーバーは、暗号化された呼び出しにおいて identify、impersonate、または delegate の各レベルでクライアントを偽装できます。これらの偽装レベルの詳細については、Impersonation Levels を参照してください。
偽装中に呼び出されたサーバーに提示される ID は、クライアントが設定するクローキング(cloaking)値の種類(設定されている場合)に依存します。詳細については、Cloaking を参照してください。
各メソッド呼び出しの終了時に、アプリケーションが RevertToSelf を呼び出さない場合は、COM がこれを呼び出します。
従来、偽装情報はネストされません。つまり、いずれかの偽装メカニズムに対する最後の呼び出しが、それ以前の偽装をすべて上書きします。しかし、アパートメント モデルでは、ネストされた呼び出しの間も偽装が維持されます。したがって、サーバー A が B から呼び出しを受けて偽装し、C を呼び出し、D から呼び出しを受けて偽装し、元に戻し、そして C からの応答を受け取る場合、偽装トークンは A ではなく B に戻されます。
非同期呼び出しでの偽装の使用については、Impersonation and Asynchronous Calls を参照してください。
IServerSecurity::RevertToSelf (objidlbase.h) メソッドは、スレッドの認証情報を偽装が開始される前の状態に復元します。
戻り値
解説(Remarks)
RevertToSelf は、スレッド上の認証情報を、偽装が開始される前のスレッドの認証情報に復元します。サーバーが現在の呼び出しの終了前に RevertToSelf を呼び出さない場合、COM によって自動的に呼び出されます。
現在偽装を行っていないスレッド上で ImpersonateClient が呼び出されると、COM はそのスレッド上に現在あるトークンを保存します。その後の RevertToSelf の呼び出しによって、保存されたトークンが復元され、IsImpersonating は FALSE を返すようになります。これは、異なる IServerSecurity オブジェクトを使用して一連の偽装呼び出しが行われた場合、RevertToSelf は、最初に ImpersonateClient が呼び出されたときにスレッド上にあったトークンを復元することを意味します。また、任意の回数の ImpersonateClient 呼び出しを取り消すために必要な RevertToSelf 呼び出しは 1 回だけです。
このメソッドは、ImpersonateClient によって行われた偽装の変更のみを元に戻します。スレッド トークンが他の手段(SetThreadToken または RpcImpersonateClient 関数)によって変更された場合、この関数の結果は未定義です。
RevertToSelf は現在のメソッド呼び出しにのみ影響します。ネストされたメソッド呼び出しがある場合、各呼び出しは独自の偽装トークンを持つことができ、DCOM は(CoRevertToSelf と RevertToSelf のどちらが呼び出されたかにかかわらず)それらに戻る前に偽装トークンを正しく復元します。
重要な点として、IServerSecurity のインスタンスは、その IServerSecurity が表す呼び出しが完了するまで、アパートメント内の任意のスレッド上で有効です。ただし、偽装は現在の呼び出しの間、特定のスレッドに対してローカルです。したがって、同じアパートメント内の 2 つのスレッドが同じ IServerSecurity インスタンスを使用して ImpersonateClient を呼び出す場合、一方のスレッドは他方に影響を与えずに RevertToSelf を呼び出すことができます。
IServerSecurity::IsImpersonating (objidlbase.h) メソッドは、サーバーが現在クライアントを偽装しているかどうかを示します。
戻り値
スレッドが現在偽装を行っている場合、戻り値は TRUE です。それ以外の場合は FALSE です。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IServerSecurity "{0000013E-0000-0000-C000-000000000046}" #usecom global IServerSecurity IID_IServerSecurity "{}" #comfunc global IServerSecurity_QueryBlanket 3 var,var,var,var,var,sptr,var #comfunc global IServerSecurity_ImpersonateClient 4 #comfunc global IServerSecurity_RevertToSelf 5 #comfunc global IServerSecurity_IsImpersonating 6 ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IServerSecurity "{0000013E-0000-0000-C000-000000000046}" #usecom global IServerSecurity IID_IServerSecurity "{}" #comfunc global IServerSecurity_QueryBlanket 3 sptr,sptr,sptr,sptr,sptr,sptr,sptr #comfunc global IServerSecurity_ImpersonateClient 4 #comfunc global IServerSecurity_RevertToSelf 5 #comfunc global IServerSecurity_IsImpersonating 6 ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。