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)

こちらもご覧ください

ACCESS_MASK

InitializeObjectAttributes

OBJECT_ATTRIBUTES

SECURITY_IMPERSONATION_LEVEL