AdjustTokenPrivileges 関数 (securitybaseapi.h)

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: 関数は特権を削除できません。 この値はサポートされていません。

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

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

[in] BufferLength

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

[out, optional] PreviousState

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

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

[out, optional] ReturnLength

PreviousState パラメーターが指すバッファーの必要なサイズ (バイト単位) を受け取る変数へのポインター。 PreviousStateNULL の場合、このパラメーターは 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

こちらもご覧ください

アクセス制御の概要

AdjustTokenGroups

基本的なAccess Control関数

GetTokenInformation

OpenProcessToken

OpenThreadToken

SetTokenInformation

TOKEN_PRIVILEGES