Funzione AdjustTokenPrivileges (securitybaseapi.h)

Articolo
03/01/2024

La funzione AdjustTokenPrivileges abilita o disabilita i privilegi nel token di accesso specificato. L'abilitazione o la disabilitazione dei privilegi in un token di accesso richiede TOKEN_ADJUST_PRIVILEGES accesso.

Sintassi

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
);

Parametri

[in] TokenHandle

Handle per il token di accesso che contiene i privilegi da modificare. L'handle deve avere TOKEN_ADJUST_PRIVILEGES accesso al token. Se il parametro PreviousState non è NULL, l'handle deve avere anche accesso TOKEN_QUERY.

[in] DisableAllPrivileges

Specifica se la funzione disabilita tutti i privilegi del token. Se questo valore è TRUE, la funzione disabilita tutti i privilegi e ignora il parametro NewState . Se è FALSE, la funzione modifica i privilegi in base alle informazioni a cui punta il parametro NewState .

[in, optional] NewState

Puntatore a una struttura TOKEN_PRIVILEGES che specifica una matrice di privilegi e i relativi attributi. Se il parametro DisableAllPrivileges è FALSE, la funzione AdjustTokenPrivileges abilita, disabilita o rimuove questi privilegi per il token. La tabella seguente descrive l'azione eseguita dalla funzione AdjustTokenPrivileges , in base all'attributo dei privilegi.

Valore	Significato
SE_PRIVILEGE_ENABLED	La funzione abilita il privilegio.
SE_PRIVILEGE_REMOVED	Il privilegio viene rimosso dall'elenco dei privilegi nel token. Gli altri privilegi nell'elenco vengono riordinati per rimanere contigui. SE_PRIVILEGE_REMOVED sostituisce SE_PRIVILEGE_ENABLED. Poiché il privilegio è stato rimosso dal token, tenta di ripristinare il privilegio genera l'avviso ERROR_NOT_ALL_ASSIGNED come se il privilegio non fosse mai stato esistente. Il tentativo di rimuovere un privilegio che non esiste nel token genera ERROR_NOT_ALL_ASSIGNED restituito. I controlli dei privilegi per i privilegi rimossi generano STATUS_PRIVILEGE_NOT_HELD. Il controllo dei privilegi non riuscito si verifica come normale. La rimozione del privilegio è irreversibile, quindi il nome del privilegio rimosso non è incluso nel parametro PreviousState dopo una chiamata a AdjustTokenPrivileges. Windows XP con SP1: La funzione non può rimuovere i privilegi. Questo valore non è supportato.
Nessuna	La funzione disabilita il privilegio.

Valore

Significato

SE_PRIVILEGE_ENABLED

La funzione abilita il privilegio.

SE_PRIVILEGE_REMOVED

Il privilegio viene rimosso dall'elenco dei privilegi nel token. Gli altri privilegi nell'elenco vengono riordinati per rimanere contigui.

SE_PRIVILEGE_REMOVED sostituisce SE_PRIVILEGE_ENABLED.

Poiché il privilegio è stato rimosso dal token, tenta di ripristinare il privilegio genera l'avviso ERROR_NOT_ALL_ASSIGNED come se il privilegio non fosse mai stato esistente.

Il tentativo di rimuovere un privilegio che non esiste nel token genera ERROR_NOT_ALL_ASSIGNED restituito.

I controlli dei privilegi per i privilegi rimossi generano STATUS_PRIVILEGE_NOT_HELD. Il controllo dei privilegi non riuscito si verifica come normale.

La rimozione del privilegio è irreversibile, quindi il nome del privilegio rimosso non è incluso nel parametro PreviousState dopo una chiamata a AdjustTokenPrivileges.

Windows XP con SP1: La funzione non può rimuovere i privilegi. Questo valore non è supportato.

Nessuna

La funzione disabilita il privilegio.

Se DisableAllPrivileges è TRUE, la funzione ignora questo parametro.

[in] BufferLength

Specifica le dimensioni, in byte, del buffer a cui fa riferimento il parametro PreviousState . Questo parametro può essere zero se il parametro PreviousState è NULL.

[out, optional] PreviousState

Puntatore a un buffer che la funzione riempie con una struttura TOKEN_PRIVILEGES contenente lo stato precedente di tutti i privilegi che la funzione modifica. Ovvero, se un privilegio è stato modificato da questa funzione, il privilegio e il relativo stato precedente sono contenuti nella struttura TOKEN_PRIVILEGES a cui fa riferimento PreviousState. Se il membro PrivilegeCount di TOKEN_PRIVILEGES è zero, non sono stati modificati privilegi da questa funzione. Questo parametro può essere NULL.

Se si specifica un buffer troppo piccolo per ricevere l'elenco completo dei privilegi modificati, la funzione non riesce e non modifica i privilegi. In questo caso, la funzione imposta la variabile puntata dal parametro ReturnLength al numero di byte necessari per contenere l'elenco completo dei privilegi modificati.

[out, optional] ReturnLength

Puntatore a una variabile che riceve le dimensioni necessarie, in byte, del buffer a cui punta il parametro PreviousState . Questo parametro può essere NULL se PreviousState è NULL.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero. Per determinare se la funzione ha modificato tutti i privilegi specificati, chiamare GetLastError, che restituisce uno dei valori seguenti quando la funzione ha esito positivo:

Codice restituito	Descrizione
ERROR_SUCCESS	La funzione ha modificato tutti i privilegi specificati.
ERROR_NOT_ALL_ASSIGNED	Il token non dispone di uno o più dei privilegi specificati nel parametro NewState . La funzione può avere esito positivo con questo valore di errore anche se non sono stati modificati privilegi. Il parametro PreviousState indica i privilegi modificati.

Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

La funzione AdjustTokenPrivileges non può aggiungere nuovi privilegi al token di accesso. Può abilitare o disabilitare solo i privilegi esistenti del token. Per determinare i privilegi del token, chiamare la funzione GetTokenInformation .

Il parametro NewState può specificare i privilegi che il token non ha, senza causare l'esito negativo della funzione. In questo caso, la funzione regola i privilegi che il token ha e ignora gli altri privilegi in modo che la funzione abbia esito positivo. Chiamare la funzione GetLastError per determinare se la funzione ha modificato tutti i privilegi specificati. Il parametro PreviousState indica i privilegi modificati.

Il parametro PreviousState recupera una struttura TOKEN_PRIVILEGES che contiene lo stato originale dei privilegi modificati. Per ripristinare lo stato originale, passare il puntatore PreviousState come parametro NewState in una chiamata successiva alla funzione AdjustTokenPrivileges .

Esempio

Per un esempio che usa questa funzione, vedere Abilitazione e disabilitazione dei privilegi.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	securitybaseapi.h (include Windows.h)
Libreria	Advapi32.lib
DLL	Advapi32.dll