ホーム › Networking.BackgroundIntelligentTransferService › IBitsTokenOptions

IBitsTokenOptions

COM

📘 Microsoft Learn (日本語) · English

IID9a2584c3-f7d2-457a-9a5e-22b67bffc7d2継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

IBitsTokenOptions は、Background Intelligent Transfer Service (BITS) の転送ジョブに対して、一対のセキュリティトークンを関連付けて管理するために使用します。

メソッド 5

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT SetHelperTokenFlags(BG_TOKEN UsageFlags)

BITS の転送ジョブに関連付けられたトークンの使用フラグを設定します。

UsageFlags

BG_TOKEN

使用フラグを指定します。このパラメーターには、次のいずれかの値を設定する必要があります。

値

意味

BG_TOKEN_LOCAL_FILE
0x0001

このフラグを指定すると、ヘルパートークンは次の用途に使用されます。

アップロードジョブのローカルファイルを開く
ダウンロードジョブの一時ファイルを作成または名前変更する
アップロード応答 (upload-reply) ジョブの応答ファイルを作成または名前変更する

BG_TOKEN_NETWORK
0x0002

このフラグを指定すると、ヘルパートークンは次の用途に使用されます。

Server Message Block (SMB) のアップロードジョブまたはダウンロードジョブのリモートファイルを開く
暗黙的な NTLM 資格情報または Kerberos 資格情報に対する HTTP サーバーまたはプロキシからのチャレンジに応答する

HTTP 経由で資格情報を送信できるようにするには、アプリケーションが IBackgroundCopyJob2::SetCredentials (..., NULL, NULL) を呼び出す必要があります。

戻り値

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

解説(Remarks)

ヘルパートークンの使用フラグは、どのリソースにヘルパートークンのセキュリティコンテキストを使用してアクセスするかを指定します。BITS は、それ以外のすべてのリソースにはジョブ所有者のセキュリティコンテキストを使用してアクセスします。たとえば、クライアント証明書にはジョブ所有者の ID を使用してアクセスします。

クライアント証明書が指定されており、かつ BITS ジョブの所有者が LocalSystem アカウントでない場合、UsageFlag パラメーターに BG_TOKEN_NETWORK を設定すると、ジョブはエラーコード 0x80072f9a (ERROR_WINHTTP_CLIENT_CERT_NO_ACCESS_PRIVATE_KEY) で失敗します。

以前の実装では、このメソッドでヘルパートークンの使用フラグを設定するために、BITS ユーザーが実質的に管理者特権を持っている必要がありました。Windows 10 バージョン 1607 以降では、管理者以外の BITS ユーザーも、自身が所有する BITS ジョブに対して、管理者以外のヘルパートークン使用フラグをこのメソッドで設定できます。この変更により、管理者以外の BITS ユーザー (NetworkService アカウントで実行されるバックグラウンドダウンローダーサービスなど) がヘルパートークンを有効に利用できるようになります。

具体的には、IBackgroundCopyJob::QueryInterface の呼び出し時に、呼び出し元スレッドのトークンの SID がジョブ所有者のユーザーアカウントの SID と同一であり、かつ現在設定されているヘルパートークン (存在する場合) で管理者 SID (DOMAIN_ALIAS_RID_ADMINS) が有効になっていない限り、管理者特権を持たないユーザーでもヘルパートークンの使用フラグを設定できるように実装が変更されました。

vtbl 4 HRESULT GetHelperTokenFlags(BG_TOKEN* pFlags)

BITS の転送ジョブに関連付けられたトークンの使用フラグを返します。

pFlags

BG_TOKEN*

out

返される使用フラグを指定します。このパラメーターには、次のいずれかの値を設定する必要があります。

値

意味

BG_TOKEN_LOCAL_FILE
0x0001

このフラグを指定すると、ヘルパートークンは次の用途に使用されます。

アップロードジョブのローカルファイルを開く
ダウンロードジョブの一時ファイルを作成または名前変更する
アップロード応答 (upload-reply) ジョブの応答ファイルを作成または名前変更する

BG_TOKEN_NETWORK
0x0002

このフラグを指定すると、ヘルパートークンは次の用途に使用されます。

Server Message Block (SMB) のアップロードジョブまたはダウンロードジョブのリモートファイルを開く
暗黙的な NTLM 資格情報または Kerberos 資格情報に対する HTTP サーバーまたはプロキシからのチャレンジに応答する

HTTP 経由で資格情報を送信できるようにするには、アプリケーションが IBackgroundCopyJob2::SetCredentials メソッドを呼び出す必要があります。

戻り値

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

解説(Remarks)

以前の実装では、このメソッドでヘルパートークンのフラグを取得するために、BITS ユーザーが実質的に管理者特権を持っている必要がありました。Windows 10 バージョン 1607 以降では、管理者以外の BITS ユーザーも、自身が所有する BITS ジョブのヘルパートークン使用フラグをこのメソッドで取得できます。この変更により、管理者以外の BITS ユーザー (NetworkService アカウントで実行されるバックグラウンドダウンローダーサービスなど) がヘルパートークンを有効に利用できるようになります。

具体的には、IBackgroundCopyJob::QueryInterface の呼び出し時に、呼び出し元スレッドのトークンの SID がジョブ所有者のユーザーアカウントの SID と同一である限り、管理者特権を持たないユーザーでもヘルパートークンのフラグを取得できるように実装が変更されました。

vtbl 5 HRESULT SetHelperToken()

COM クライアントのトークンを偽装 (impersonate) するように、ヘルパートークンを設定します。

戻り値

次の値が返される場合があります。

戻り値のコード/値	説明
CO_E_FAILEDTOIMPERSONATE 0x80010123	クライアント側の COM の設定が、クライアントトークンへの偽装レベルのアクセスを許可していません。
E_ACCESSDENIED 0x80070005	Windows 10 バージョン 1607 より前のバージョンでは、ジョブの所有者が管理者ではありません。これらのバージョンの Windows では、管理者が所有するジョブのみがヘルパートークンを設定できます。 Windows 10 バージョン 1607 以降のバージョンでは、このエラーはヘルパートークンが管理者特権を持つ一方で、呼び出し元が管理者特権を持たないことを示します。

戻り値のコード/値

説明

CO_E_FAILEDTOIMPERSONATE
0x80010123

クライアント側の COM の設定が、クライアントトークンへの偽装レベルのアクセスを許可していません。

E_ACCESSDENIED
0x80070005

Windows 10 バージョン 1607 より前のバージョンでは、ジョブの所有者が管理者ではありません。これらのバージョンの Windows では、管理者が所有するジョブのみがヘルパートークンを設定できます。
Windows 10 バージョン 1607 以降のバージョンでは、このエラーはヘルパートークンが管理者特権を持つ一方で、呼び出し元が管理者特権を持たないことを示します。

解説(Remarks)

ヘルパートークンが管理者を表している必要はありません。

プロキシブランケットの偽装レベルは、RPC_C_IMP_LEVEL_IMPERSONATE または RPC_C_IMP_LEVEL_DELEGATE のいずれかに設定する必要があります。詳細については、Security Blanket Negotiation を参照してください。

クローキングフラグは EOAC_DYNAMIC_CLOAKING に設定してください。これにより、COM サーバーはスレッドトークンをクライアントの ID として使用できます。詳細については、Cloaking および EOLE_AUTHENTICATION_CAPABILITIES 列挙型を参照してください。

以前の実装では、ヘルパートークンを設定するために、BITS ユーザーが実質的に管理者特権を持っている必要がありました。Windows 10 バージョン 1607 以降では、管理者以外の BITS ユーザーも、IBitsTokenOptions::SetHelperToken を使用して、自身が所有する BITS ジョブに管理者以外のヘルパートークンを設定できます。この変更により、管理者以外の BITS ユーザー (NetworkService アカウントで実行されるバックグラウンドダウンローダーサービスなど) がヘルパートークンを設定できるようになります。

具体的には、IBackgroundCopyJob::QueryInterface の呼び出し時に、呼び出し元スレッドのトークンの SID がジョブ所有者のユーザーアカウントの SID と同一であり、かつ設定しようとしているヘルパートークンで管理者 SID (DOMAIN_ALIAS_RID_ADMINS) が有効になっていない限り、管理者特権を持たないユーザーでもヘルパートークンを設定できるように実装が変更されました。

vtbl 6 HRESULT ClearHelperToken()

ヘルパートークンを破棄します。使用フラグは変更しません。

戻り値

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

解説(Remarks)

以前の実装では、このメソッドでヘルパートークンをクリアするために、BITS ユーザーが実質的に管理者特権を持っている必要がありました。Windows 10 バージョン 1607 以降では、管理者以外の BITS ユーザーも、自身が所有する BITS ジョブのヘルパートークンをこのメソッドでクリアできます。この変更により、管理者以外の BITS ユーザー (NetworkService アカウントで実行されるバックグラウンドダウンローダーサービスなど) がヘルパートークンを有効に利用できるようになります。

具体的には、IBackgroundCopyJob::QueryInterface の呼び出し時に、呼び出し元スレッドのトークンの SID がジョブ所有者のユーザーアカウントの SID と同一である限り、管理者特権を持たないユーザーでもヘルパートークンをクリアできるように実装が変更されました。

vtbl 7 HRESULT GetHelperTokenSid(LPWSTR* pSid)

ヘルパートークンが設定されている場合、その SID を返します。

pSid

LPWSTR*

out

GetTokenInformation 関数の TokenInformation パラメーターから取得された SID を返します。SID が取得されない場合、このパラメーターには NULL が設定されます。

戻り値

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

解説(Remarks)

以前の実装では、このメソッドでヘルパートークンの SID を取得するために、BITS ユーザーが実質的に管理者特権を持っている必要がありました。Windows 10 バージョン 1607 以降では、管理者以外の BITS ユーザーも、自身が所有する BITS ジョブのヘルパートークン SID をこのメソッドで取得できます。この変更により、管理者以外の BITS ユーザー (NetworkService アカウントで実行されるバックグラウンドダウンローダーサービスなど) がヘルパートークンを有効に利用できるようになります。

具体的には、IBackgroundCopyJob::QueryInterface の呼び出し時に、呼び出し元スレッドのトークンの SID がジョブ所有者のユーザーアカウントの SID と同一である限り、管理者特権を持たないユーザーでもヘルパートークンの SID を取得できるように実装が変更されました。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IBitsTokenOptions "{9A2584C3-F7D2-457A-9A5E-22B67BFFC7D2}"
#usecom global IBitsTokenOptions IID_IBitsTokenOptions "{}"
#comfunc global IBitsTokenOptions_SetHelperTokenFlags  3 int
#comfunc global IBitsTokenOptions_GetHelperTokenFlags  4 var
#comfunc global IBitsTokenOptions_SetHelperToken       5
#comfunc global IBitsTokenOptions_ClearHelperToken     6
#comfunc global IBitsTokenOptions_GetHelperTokenSid    7 var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_IBitsTokenOptions "{9A2584C3-F7D2-457A-9A5E-22B67BFFC7D2}"
#usecom global IBitsTokenOptions IID_IBitsTokenOptions "{}"
#comfunc global IBitsTokenOptions_SetHelperTokenFlags  3 int
#comfunc global IBitsTokenOptions_GetHelperTokenFlags  4 sptr
#comfunc global IBitsTokenOptions_SetHelperToken       5
#comfunc global IBitsTokenOptions_ClearHelperToken     6
#comfunc global IBitsTokenOptions_GetHelperTokenSid    7 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。