AdjustTokenPrivileges 関数 (securitybaseapi.h)

[アーティクル]
03/13/2024

AdjustTokenPrivileges 関数は、指定されたアクセストークンの特権を有効または無効にします。アクセストークンで特権を有効または無効にするには、TOKEN_ADJUST_PRIVILEGESアクセスが必要です。

構文

BOOL AdjustTokenPrivileges(
  [in]            HANDLE            TokenHandle,
  [in]            BOOL              DisableAllPrivileges,
  [in, optional]  PTOKEN_PRIVILEGES NewState,
  [in]            DWORD             BufferLength,
  [out, optional] PTOKEN_PRIVILEGES PreviousState,
  [out, optional] PDWORD            ReturnLength
);

パラメーター

[in] TokenHandle

変更する特権を含むアクセストークンへのハンドル。ハンドルには、トークンへのTOKEN_ADJUST_PRIVILEGESアクセス権が必要です。 PreviousState パラメーターが NULL でない場合、ハンドルにはTOKEN_QUERYアクセス権も必要です。

[in] DisableAllPrivileges

関数がトークンのすべての特権を無効にするかどうかを指定します。この値が TRUE の場合、関数はすべての特権を無効にし、 NewState パラメーターを無視します。 FALSE の場合、関数は NewState パラメーターが指す情報に基づいて特権を変更します。

[in, optional] NewState

特権とその属性の配列を指定する TOKEN_PRIVILEGES 構造体へのポインター。 DisableAllPrivileges パラメーターが FALSE の場合、AdjustTokenPrivileges 関数はトークンに対するこれらの特権を有効、無効、または削除します。次の表では、 AdjustTokenPrivileges 関数によって実行されるアクションについて、特権属性に基づいて説明します。

値	意味
SE_PRIVILEGE_ENABLED	関数は特権を有効にします。
SE_PRIVILEGE_REMOVED	特権は、トークン内の特権の一覧から削除されます。リスト内の他の特権は、連続した状態を維持するように並べ替えられます。 SE_PRIVILEGE_REMOVEDは、SE_PRIVILEGE_ENABLEDよりも優先されます。特権はトークンから削除されているため、特権を再び適用しようとすると、特権が存在しなかったかのように警告ERROR_NOT_ALL_ASSIGNEDされます。トークンに存在しない特権を削除しようとすると、ERROR_NOT_ALL_ASSIGNEDが返されます。削除された特権の特権チェックを行うと、STATUS_PRIVILEGE_NOT_HELD。失敗した特権チェック監査は通常どおりに行われます。特権の削除は元に戻すことができないため、AdjustTokenPrivileges を呼び出した後、削除された特権の名前は PreviousState パラメーターに含まれません。 WINDOWS XP と SP1: 関数は特権を削除できません。この値はサポートされていません。
なし	関数は特権を無効にします。

値

意味

SE_PRIVILEGE_ENABLED

関数は特権を有効にします。

SE_PRIVILEGE_REMOVED

特権は、トークン内の特権の一覧から削除されます。リスト内の他の特権は、連続した状態を維持するように並べ替えられます。

SE_PRIVILEGE_REMOVEDは、SE_PRIVILEGE_ENABLEDよりも優先されます。

特権はトークンから削除されているため、特権を再び適用しようとすると、特権が存在しなかったかのように警告ERROR_NOT_ALL_ASSIGNEDされます。

トークンに存在しない特権を削除しようとすると、ERROR_NOT_ALL_ASSIGNEDが返されます。

削除された特権の特権チェックを行うと、STATUS_PRIVILEGE_NOT_HELD。失敗した特権チェック監査は通常どおりに行われます。

特権の削除は元に戻すことができないため、AdjustTokenPrivileges を呼び出した後、削除された特権の名前は PreviousState パラメーターに含まれません。

WINDOWS XP と SP1: 関数は特権を削除できません。この値はサポートされていません。

なし

関数は特権を無効にします。

DisableAllPrivileges が TRUE の場合、関数はこのパラメーターを無視します。

[in] BufferLength

PreviousState パラメーターが指すバッファーのサイズをバイト単位で指定します。 PreviousState パラメーターが NULL の場合、このパラメーターは 0 にすることができます。

[out, optional] PreviousState

関数が変更する特権の以前の状態を含む TOKEN_PRIVILEGES 構造体で関数が埋めるバッファーへのポインター。つまり、この関数によって特権が変更された場合、特権とその以前の状態は、PreviousState によって参照されるTOKEN_PRIVILEGES構造に含まれます。 TOKEN_PRIVILEGES の PrivilegeCount メンバーが 0 の場合、この関数によって特権は変更されていません。このパラメーターは、NULL でもかまいません。

変更された特権の完全な一覧を受け取るために小さすぎるバッファーを指定すると、関数は失敗し、特権は調整されません。この場合、関数は ReturnLength パラメーターが指す変数を、変更された特権の完全な一覧を保持するために必要なバイト数に設定します。

[out, optional] ReturnLength

PreviousState パラメーターが指すバッファーの必要なサイズ (バイト単位) を受け取る変数へのポインター。 PreviousState が NULL の場合、このパラメーターは NULL にすることができます。

戻り値

関数が成功すると、戻り値は 0 以外になります。関数が指定されたすべての特権を調整したかどうかを判断するには、 GetLastError を呼び出します。この呼び出しは、関数が成功したときに次のいずれかの値を返します。

リターンコード	説明
ERROR_SUCCESS	関数は、指定されたすべての特権を調整しました。
ERROR_NOT_ALL_ASSIGNED	トークンには、 NewState パラメーターで指定された 1 つ以上の特権がありません。特権が調整されていない場合でも、このエラー値で関数が成功する可能性があります。 PreviousState パラメーターは、調整された特権を示します。

関数が失敗した場合は、0 を返します。詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

AdjustTokenPrivileges 関数は、アクセストークンに新しい特権を追加できません。トークンの既存の特権のみを有効または無効にすることができます。トークンの特権を確認するには、 GetTokenInformation 関数を呼び出します。

NewState パラメーターは、関数を失敗させることなく、トークンに含まれない特権を指定できます。この場合、関数はトークンが持つ特権を調整し、関数が成功するように他の特権を無視します。 GetLastError 関数を呼び出して、関数が指定されたすべての特権を調整したかどうかを判断します。 PreviousState パラメーターは、調整された特権を示します。

PreviousState パラメーターは、調整された特権の元の状態を含むTOKEN_PRIVILEGES構造体を取得します。元の状態を復元するには、以降の AdjustTokenPrivileges 関数の呼び出しで PreviousState ポインターを NewState パラメーターとして渡します。

例

この関数を使用する例については、「特権の有効化と無効化」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows XP [デスクトップアプリ \| UWP アプリ]
サポートされている最小のサーバー	Windows Server 2003 [デスクトップアプリのみ \| UWP アプリ]
対象プラットフォーム	Windows
ヘッダー	securitybaseapi.h (Windows.h を含む)
Library	Advapi32.lib
[DLL]	Advapi32.dll