ホーム › Security › AdjustTokenGroups

AdjustTokenGroups

関数

アクセストークン内のグループ情報を変更する。

DLLADVAPI32.dll呼出規約winapiSetLastErrorあり対応OSWindows XP 以降

シグネチャ

// ADVAPI32.dll
#include <windows.h>

BOOL AdjustTokenGroups(
    HANDLE TokenHandle,
    BOOL ResetToDefault,
    TOKEN_GROUPS* NewState,   // optional
    DWORD BufferLength,
    TOKEN_GROUPS* PreviousState,   // optional
    DWORD* ReturnLength   // optional
);

パラメーター

名前	型	方向	説明
TokenHandle	HANDLE	in	有効化または無効化するグループを含むアクセストークンへのハンドルです。このハンドルは、トークンに対する TOKEN_ADJUST_GROUPS アクセス権を持っている必要があります。PreviousState パラメーターが NULL でない場合は、ハンドルは TOKEN_QUERY アクセス権も持っている必要があります。
ResetToDefault	BOOL	in	グループを既定の有効/無効状態に設定するかどうかを示すブール値です。この値が TRUE の場合、グループは既定の状態に設定され、NewState パラメーターは無視されます。この値が FALSE の場合、グループは NewState パラメーターが指す情報に従って設定されます。
NewState	TOKEN_GROUPS*	inoptional	有効化または無効化するグループを含む TOKEN_GROUPS 構造体へのポインターです。ResetToDefault パラメーターが FALSE の場合、関数は各グループを TOKEN_GROUPS 構造体内のそのグループの SE_GROUP_ENABLED 属性の値に設定します。ResetToDefault が TRUE の場合、このパラメーターは無視されます。
BufferLength	DWORD	in	PreviousState パラメーターが指すバッファーのサイズ(バイト単位)です。PreviousState パラメーターが NULL の場合、このパラメーターは 0 にできます。
PreviousState	TOKEN_GROUPS*	outoptional	関数が変更するグループの以前の状態を格納する TOKEN_GROUPS 構造体を受け取るバッファーへのポインターです。つまり、グループがこの関数によって変更された場合、そのグループとその以前の状態が PreviousState が参照する TOKEN_GROUPS 構造体に格納されます。TOKEN_GROUPS の GroupCount メンバーが 0 の場合、この関数によって変更されたグループはありません。このパラメーターは NULL にできます。バッファーが指定されているが、変更されたグループの完全な一覧を受け取るのに十分な領域がない場合、グループの状態は変更されず、関数は失敗します。この場合、関数は ReturnLength パラメーターが指す変数に、変更されたグループの完全な一覧を保持するために必要なバイト数を設定します。
ReturnLength	DWORD*	outoptional	PreviousState パラメーターが指すバッファーに必要な実際のバイト数を受け取る変数へのポインターです。このパラメーターは NULL にでき、PreviousState が NULL の場合は無視されます。

戻り値の型: BOOL

公式ドキュメント

指定したアクセストークンに既に存在するグループを有効化または無効化します。アクセストークン内のグループを有効化または無効化するには、TOKEN_ADJUST_GROUPS へのアクセス権が必要です。

戻り値

関数が成功した場合、戻り値は 0 以外の値です。

関数が失敗した場合、戻り値は 0 です。拡張エラー情報を取得するには、 GetLastError を呼び出します。

解説(Remarks)

PreviousState パラメーターで取得される情報は、TOKEN_GROUPS 構造体として整形されます。これは、このバッファーへのポインターを後続の AdjustTokenGroups 関数の呼び出しで NewState パラメーターとして渡すことで、グループの元の状態を復元できることを意味します。

NewState パラメーターには、アクセストークンに存在しない変更対象のグループを列挙できます。これはトークン内のグループの正常な変更には影響しません。

AdjustTokenGroups 関数は、TOKEN_GROUPS 構造体内で SE_GROUP_MANDATORY 属性を持つグループを無効化できません。代わりに CreateRestrictedToken を使用してください。

SE_GROUP_USE_FOR_DENY_ONLY 属性を持つグループは有効化できません。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// ADVAPI32.dll
#include <windows.h>

BOOL AdjustTokenGroups(
    HANDLE TokenHandle,
    BOOL ResetToDefault,
    TOKEN_GROUPS* NewState,   // optional
    DWORD BufferLength,
    TOKEN_GROUPS* PreviousState,   // optional
    DWORD* ReturnLength   // optional
);

[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("ADVAPI32.dll", SetLastError = true, ExactSpelling = true)]
static extern bool AdjustTokenGroups(
    IntPtr TokenHandle,   // HANDLE
    bool ResetToDefault,   // BOOL
    IntPtr NewState,   // TOKEN_GROUPS* optional
    uint BufferLength,   // DWORD
    IntPtr PreviousState,   // TOKEN_GROUPS* optional, out
    IntPtr ReturnLength   // DWORD* optional, out
);

<DllImport("ADVAPI32.dll", SetLastError:=True, ExactSpelling:=True)>
Public Shared Function AdjustTokenGroups(
    TokenHandle As IntPtr,   ' HANDLE
    ResetToDefault As Boolean,   ' BOOL
    NewState As IntPtr,   ' TOKEN_GROUPS* optional
    BufferLength As UInteger,   ' DWORD
    PreviousState As IntPtr,   ' TOKEN_GROUPS* optional, out
    ReturnLength As IntPtr   ' DWORD* optional, out
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

' TokenHandle : HANDLE
' ResetToDefault : BOOL
' NewState : TOKEN_GROUPS* optional
' BufferLength : DWORD
' PreviousState : TOKEN_GROUPS* optional, out
' ReturnLength : DWORD* optional, out
Declare PtrSafe Function AdjustTokenGroups Lib "advapi32" ( _
    ByVal TokenHandle As LongPtr, _
    ByVal ResetToDefault As Long, _
    ByVal NewState As LongPtr, _
    ByVal BufferLength As Long, _
    ByVal PreviousState As LongPtr, _
    ByVal ReturnLength As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

AdjustTokenGroups = ctypes.windll.advapi32.AdjustTokenGroups
AdjustTokenGroups.restype = wintypes.BOOL
AdjustTokenGroups.argtypes = [
    wintypes.HANDLE,  # TokenHandle : HANDLE
    wintypes.BOOL,  # ResetToDefault : BOOL
    ctypes.c_void_p,  # NewState : TOKEN_GROUPS* optional
    wintypes.DWORD,  # BufferLength : DWORD
    ctypes.c_void_p,  # PreviousState : TOKEN_GROUPS* optional, out
    ctypes.POINTER(wintypes.DWORD),  # ReturnLength : DWORD* optional, out
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ADVAPI32.dll')
AdjustTokenGroups = Fiddle::Function.new(
  lib['AdjustTokenGroups'],
  [
    Fiddle::TYPE_VOIDP,  # TokenHandle : HANDLE
    Fiddle::TYPE_INT,  # ResetToDefault : BOOL
    Fiddle::TYPE_VOIDP,  # NewState : TOKEN_GROUPS* optional
    -Fiddle::TYPE_INT,  # BufferLength : DWORD
    Fiddle::TYPE_VOIDP,  # PreviousState : TOKEN_GROUPS* optional, out
    Fiddle::TYPE_VOIDP,  # ReturnLength : DWORD* optional, out
  ],
  Fiddle::TYPE_INT)

#[link(name = "advapi32")]
extern "system" {
    fn AdjustTokenGroups(
        TokenHandle: *mut core::ffi::c_void,  // HANDLE
        ResetToDefault: i32,  // BOOL
        NewState: *mut TOKEN_GROUPS,  // TOKEN_GROUPS* optional
        BufferLength: u32,  // DWORD
        PreviousState: *mut TOKEN_GROUPS,  // TOKEN_GROUPS* optional, out
        ReturnLength: *mut u32  // DWORD* optional, out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("ADVAPI32.dll", SetLastError = true)]
public static extern bool AdjustTokenGroups(IntPtr TokenHandle, bool ResetToDefault, IntPtr NewState, uint BufferLength, IntPtr PreviousState, IntPtr ReturnLength);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ADVAPI32_AdjustTokenGroups' -Namespace Win32 -PassThru
# $api::AdjustTokenGroups(TokenHandle, ResetToDefault, NewState, BufferLength, PreviousState, ReturnLength)

#uselib "ADVAPI32.dll"
#func global AdjustTokenGroups "AdjustTokenGroups" sptr, sptr, sptr, sptr, sptr, sptr
; AdjustTokenGroups TokenHandle, ResetToDefault, varptr(NewState), BufferLength, varptr(PreviousState), varptr(ReturnLength)   ; 戻り値は stat
; TokenHandle : HANDLE -> "sptr"
; ResetToDefault : BOOL -> "sptr"
; NewState : TOKEN_GROUPS* optional -> "sptr"
; BufferLength : DWORD -> "sptr"
; PreviousState : TOKEN_GROUPS* optional, out -> "sptr"
; ReturnLength : DWORD* optional, out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "ADVAPI32.dll"
#cfunc global AdjustTokenGroups "AdjustTokenGroups" sptr, int, var, int, var, var
; res = AdjustTokenGroups(TokenHandle, ResetToDefault, NewState, BufferLength, PreviousState, ReturnLength)
; TokenHandle : HANDLE -> "sptr"
; ResetToDefault : BOOL -> "int"
; NewState : TOKEN_GROUPS* optional -> "var"
; BufferLength : DWORD -> "int"
; PreviousState : TOKEN_GROUPS* optional, out -> "var"
; ReturnLength : DWORD* optional, out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "ADVAPI32.dll"
#cfunc global AdjustTokenGroups "AdjustTokenGroups" sptr, int, sptr, int, sptr, sptr
; res = AdjustTokenGroups(TokenHandle, ResetToDefault, varptr(NewState), BufferLength, varptr(PreviousState), varptr(ReturnLength))
; TokenHandle : HANDLE -> "sptr"
; ResetToDefault : BOOL -> "int"
; NewState : TOKEN_GROUPS* optional -> "sptr"
; BufferLength : DWORD -> "int"
; PreviousState : TOKEN_GROUPS* optional, out -> "sptr"
; ReturnLength : DWORD* optional, out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。