ZwDuplicateToken 関数 (ntifs.h)
ZwDuplicateToken 関数は、既存のトークンを複製する新しいアクセス トークンへのハンドルを作成します。 この関数は、プライマリ トークンまたは偽装トークンを作成できます。
構文
NTSYSAPI NTSTATUS ZwDuplicateToken(
[in] HANDLE ExistingTokenHandle,
[in] ACCESS_MASK DesiredAccess,
[in] POBJECT_ATTRIBUTES ObjectAttributes,
[in] BOOLEAN EffectiveOnly,
[in] TOKEN_TYPE TokenType,
[out] PHANDLE NewTokenHandle
);
パラメーター
[in] ExistingTokenHandle
TOKEN_DUPLICATEアクセス権で開かれた既存のアクセス トークンへのハンドル。 このパラメーターは必須であり、NULL にすることはできません。
[in] DesiredAccess
新しいトークンに対して要求されたアクセス権を指定するビットマスク。 ZwDuplicateToken は 、要求されたアクセス権を既存のトークンの随意アクセス制御リスト (DACL) と比較して、新しいトークンに対して許可または拒否される権限を決定します。 既存のトークンと同じアクセス権を要求するには、0 を指定します。 呼び出し元に対して有効なすべてのアクセス権を要求するには、MAXIMUM_ALLOWEDを指定します。 このパラメーターは省略可能であり、0、MAXIMUM_ALLOWED、または次の 1 つ以上の値のビットごとの OR の組み合わせを指定できます。
| 値 | 意味 |
|---|---|
| DELETE | オブジェクトを削除するために必要です。 |
| READ_CONTROL | オブジェクトの DACL と所有権の情報を読み取るために必要です。 システム アクセス制御リスト (SACL) へのアクセスについては、この表の後半の「ACCESS_SYSTEM_SECURITY」を参照してください。 |
| WRITE_DAC | オブジェクトの DACL 情報を変更するために必要です。 |
| WRITE_OWNER | オブジェクトのセキュリティ記述子 (SECURITY_DESCRIPTOR) の所有権情報を変更するために必要です。 |
| ACCESS_SYSTEM_SECURITY | オブジェクトの ACL で SACL を取得または設定するために必要です。 オペレーティング システムは、呼び出し元スレッドのアクセス トークンでSE_SECURITY_NAME特権が有効になっている場合にのみ、この権限を新しいトークンに付与します。 |
| STANDARD_RIGHTS_READ | 現在、等しいREAD_CONTROLに定義されています。 |
| STANDARD_RIGHTS_WRITE | 現在、等しいREAD_CONTROLに定義されています。 |
| STANDARD_RIGHTS_EXECUTE | 現在、等しいREAD_CONTROLに定義されています。 |
| STANDARD_RIGHTS_REQUIRED | DELETE、READ_CONTROL、WRITE_DAC、WRITE_OWNERアクセスを組み合わせます。 |
| STANDARD_RIGHTS_ALL | DELETE、READ_CONTROL、WRITE_DAC、WRITE_OWNER、SYNCHRONIZE アクセスを組み合わせます。 ただし、SYNCHRONIZE 値はトークン オブジェクトには適用できません。 したがって、STANDARD_RIGHTS_ALLには、STANDARD_RIGHTS_REQUIREDと機能的に同等の機能があります。 |
| TOKEN_ADJUST_DEFAULT | アクセス トークンの既定の所有者、プライマリ グループ、または DACL を変更するために必要です。 |
| TOKEN_ADJUST_GROUPS | アクセス トークン内のグループの属性を調整するために必要です。 |
| TOKEN_ADJUST_PRIVILEGES | アクセス トークンの特権を有効または無効にするために必要です。 |
| TOKEN_ADJUST_SESSIONID | アクセス トークンのセッション ID (SID) を調整するために必要です。 オペレーティング システムは、呼び出し元スレッドのアクセス トークンでSE_TCB_NAME特権が有効になっている場合にのみ、この権限を新しいトークンに付与します。 |
| TOKEN_ASSIGN_PRIMARY | プライマリ トークンをプロセスにアタッチするために必要です。 オペレーティング システムは、呼び出し元スレッドのアクセス トークンでSE_ASSIGNPRIMARYTOKEN_NAME特権が有効になっている場合にのみ、この権限を新しいトークンに付与します。 |
| TOKEN_DUPLICATE | アクセス トークンを複製するために必要です。 このルーチンを正常に使用するには、指定された ExistingTokenHandle トークンにこの権限が含まれている必要があることに注意してください。 |
| TOKEN_EXECUTE | STANDARD_RIGHTS_EXECUTEとTOKEN_IMPERSONATEを結合します。 |
| TOKEN_IMPERSONATE | 偽装アクセス トークンをプロセスにアタッチするために必要です。 |
| TOKEN_QUERY | アクセス トークンのクエリを実行するために必要です。 |
| TOKEN_QUERY_SOURCE | アクセス トークンのソースに対してクエリを実行するために必要です。 |
| TOKEN_READ | STANDARD_RIGHTS_READとTOKEN_QUERYを組み合わせます。 |
| TOKEN_WRITE | STANDARD_RIGHTS_WRITE、TOKEN_ADJUST_PRIVILEGES、TOKEN_ADJUST_GROUPS、TOKEN_ADJUST_DEFAULTを結合します。 |
| TOKEN_ALL_ACCESS | トークンに対して使用可能なすべてのトークン アクセス許可を組み合わせます。 |
詳細については、「Windows SDKの Access-Token オブジェクトのアクセス権」を参照してください。 アクセス トークンは SYNCHRONIZE 権限をサポートしないことに注意してください。
[in] ObjectAttributes
新しいトークンの要求されたプロパティを記述する OBJECT_ATTRIBUTES 構造体へのポインター。 ObjectAttributes パラメーターは省略可能であり、NULL にすることができます。 ObjectAttributes パラメーターが NULL の場合、または ObjectAttributes パラメーターが指す構造体の SecurityDescriptor メンバーが NULL の場合、新しいトークンは既定のセキュリティ記述子を受け取り、新しいトークン ハンドルを継承できません。 その場合、この既定のセキュリティ記述子は、呼び出し元のトークンに格納されているユーザー グループ、プライマリ グループ、DACL 情報から作成されます。
TokenType パラメーターが TokenImpersonation に設定されている場合:
ObjectAttributes パラメーターを使用して、新しいトークンの偽装レベルを指定できます。 これは、ObjectAttributes-SecurityQualityOfService.ImpersonationLevel >を適切なSECURITY_IMPERSONATION_LEVEL列挙値に設定することで実現できます。 詳細については、「 SECURITY_QUALITY_OF_SERVICE」を参照してください。
既存のトークンが偽装トークンであり、 ObjectAttributes パラメーターに偽装情報が提供されない場合、新しいトークンの偽装レベルは既存のトークンの偽装レベルに設定されます。
既存のトークンがプライマリ トークンであり、偽装レベルの情報が指定されていない場合、新しい偽装トークンには SECURITY_IMPERSONATION_LEVEL 偽装レベルが設定されます。
[in] EffectiveOnly
既存のトークン全体を新しいトークンに複製するか、トークンの有効な (現在有効な) 部分だけに複製するかを示すブール値。 TRUE に設定すると、ソース トークンの現在有効な部分のみが複製されます。 FALSE に設定すると、既存のトークン全体が複製されます。 これにより、保護されたサブシステムの呼び出し元が、保護されたサブシステムで使用可能になるオプションのグループと特権を制限する手段が提供されます。 たとえば、 EffectiveOnly が TRUE の場合、呼び出し元はトークンを複製できますが、Administrators グループと SeTcbPrivilege 権限を削除できます。 その後、結果のトークンを子プロセス (CreateProcessAsUser) に渡すことができます。これにより、子プロセスで実行できる処理が制限されます。 このパラメーターは必須です。
[in] TokenType
TOKEN_TYPE列挙体から次のいずれかの値を指定します。
| 値 | 意味 |
|---|---|
| TokenPrimary | 新しいトークンはプライマリ トークンです。 既存のトークンが偽装トークンの場合、既存の偽装トークンには、SecurityImpersonation または SecurityDelegation の偽装レベル (ObjectAttributes パラメーターによって提供される) が必要です。 それ以外の場合、 ZwDuplicateToken はSTATUS_BAD_IMPERSONATION_LEVELを返します。 |
| TokenImpersonation | 新しいトークンは偽装トークンです。 既存のトークンが偽装トークンの場合、新しいトークンの要求された偽装レベル ( ObjectAttributes パラメーターによって提供される) は、既存のトークンの偽装レベルより大きくすることはできません。 それ以外の場合、 ZwDuplicateToken はSTATUS_BAD_IMPERSONATION_LEVELを返します。 |
TokenType パラメーターは必須であり、NULL にすることはできません。
[out] NewTokenHandle
新しいトークンへのハンドルを受け取る HANDLE 型の呼び出し元によって割り当てられた変数へのポインター。 このパラメーターは必須であり、NULL にすることはできません。
戻り値
ZwDuplicateToken は、呼び出しが成功した場合にSTATUS_SUCCESSを返します。 考えられるエラー リターン コードは次のとおりです。
| リターン コード | 説明 |
|---|---|
| STATUS_ACCESS_VIOLATION | メモリ アクセス違反が発生しました たとえば、前のモードがユーザー モードで、無効なユーザー モード メモリが指定されている場合、 ZwDuplicateToken はSTATUS_ACCESS_VIOLATIONを返します。 |
| STATUS_INSUFFICIENT_RESOURCES | 新しいトークンを複製するために十分なメモリを割り当てませんでした。 |
| STATUS_INVALID_PARAMETER | 無効なパラメーターが検出されました。 |
| STATUS_BAD_IMPERSONATION_LEVEL | 新しいトークンに対して要求された偽装レベルが、既存のトークンの偽装レベルを超えています。 |
| STATUS_ACCESS_DENIED | ZwDuplicateToken は 、ExistingTokenHandle にアクセスできなかった場合にSTATUS_ACCESS_DENIEDを返します。 これは、既存のトークンにTOKEN_DUPLICATEアクセス権がない場合に発生します。 |
| STATUS_INVALID_HANDLE | ExistingTokenHandle が無効なハンドルを参照している場合、ZwDuplicateToken はSTATUS_INVALID_HANDLEを返します。 |
注釈
ObjectAttributes パラメーターによって偽装レベルの情報が提供されなかった場合、既存のトークンの偽装レベルが新しいトークンに使用されます。
省略可能な ObjectAttributes パラメーターが指す構造体に関して、OBJECT_ATTRIBUTES の SecurityQualityOfService メンバー は 、 SECURITY_QUALITY_OF_SERVICE型の構造体を指します。 この構造体のメンバーについては、「 SECURITY_QUALITY_OF_SERVICE 」を参照してください。
InitializeObjectAttributes は現在 SecurityQualityOfService を NULL に設定しているため、InitializeObjectAttributes マクロを呼び出した後にSecurityQualityOfService メンバーを設定する必要があります。
ZwDuplicateToken のユーザー モード アナログの詳細については、「DuplicateTokenEx」を参照してください。
新しいトークンの使用が完了したら、 ZwClose 関数を呼び出してトークン ハンドルを閉じます。
ZwDuplicateToken 関数の呼び出しがユーザー モードで発生する場合は、"ZwDuplicateToken" ではなく"NtDuplicateToken" という名前を使用する必要があります。
カーネル モード ドライバーからの呼び出しの場合、Windows ネイティブ システム サービス ルーチンの NtXxx および ZwXxx バージョンは、入力パラメーターを処理および解釈する方法で動作が異なります。 ルーチンの NtXxx バージョンと ZwXxx バージョン間の関係の詳細については、「Using Nt and Zw Versions of the Native System Services Routines」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 2000 |
| 対象プラットフォーム | ユニバーサル |
| Header | ntifs.h (Ntifs.h、FltKernel.h を含む) |
| Library | NtosKrnl.lib |
| [DLL] | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| DDI コンプライアンス規則 | HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm) |