Fonction AdjustTokenPrivileges (securitybaseapi.h)

Article
03/01/2024

La fonction AdjustTokenPrivileges active ou désactive les privilèges dans le jeton d’accès spécifié. L’activation ou la désactivation des privilèges dans un jeton d’accès nécessite un accès TOKEN_ADJUST_PRIVILEGES.

Syntaxe

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

Paramètres

[in] TokenHandle

Handle du jeton d’accès qui contient les privilèges à modifier. Le handle doit avoir TOKEN_ADJUST_PRIVILEGES accès au jeton. Si le paramètre PreviousState n’a pas la valeur NULL, le handle doit également disposer d’un accès TOKEN_QUERY.

[in] DisableAllPrivileges

Spécifie si la fonction désactive tous les privilèges du jeton. Si cette valeur est TRUE, la fonction désactive tous les privilèges et ignore le paramètre NewState . Si elle est FALSE, la fonction modifie les privilèges en fonction des informations pointées par le paramètre NewState .

[in, optional] NewState

Pointeur vers une structure de TOKEN_PRIVILEGES qui spécifie un tableau de privilèges et leurs attributs. Si le paramètre DisableAllPrivileges a la valeur FALSE, la fonction AdjustTokenPrivileges active, désactive ou supprime ces privilèges pour le jeton. Le tableau suivant décrit l’action effectuée par la fonction AdjustTokenPrivileges , en fonction de l’attribut privilege.

Valeur	Signification
SE_PRIVILEGE_ENABLED	La fonction active le privilège.
SE_PRIVILEGE_REMOVED	Le privilège est supprimé de la liste des privilèges dans le jeton. Les autres privilèges de la liste sont réorganisés pour rester contigus. SE_PRIVILEGE_REMOVED remplace SE_PRIVILEGE_ENABLED. Étant donné que le privilège a été supprimé du jeton, les tentatives de réactiver le privilège aboutissent à l’avertissement ERROR_NOT_ALL_ASSIGNED comme si le privilège n’avait jamais existé. La tentative de suppression d’un privilège qui n’existe pas dans le jeton entraîne le retour de ERROR_NOT_ALL_ASSIGNED. Les vérifications de privilèges pour les privilèges supprimés entraînent des STATUS_PRIVILEGE_NOT_HELD. L’échec des privilèges case activée l’audit se produit normalement. La suppression du privilège étant irréversible, le nom du privilège supprimé n’est pas inclus dans le paramètre PreviousState après un appel à AdjustTokenPrivileges. Windows XP avec SP1 : La fonction ne peut pas supprimer les privilèges. Cette valeur n’est pas prise en charge.
Aucun	La fonction désactive le privilège.

Valeur

Signification

SE_PRIVILEGE_ENABLED

La fonction active le privilège.

SE_PRIVILEGE_REMOVED

Le privilège est supprimé de la liste des privilèges dans le jeton. Les autres privilèges de la liste sont réorganisés pour rester contigus.

SE_PRIVILEGE_REMOVED remplace SE_PRIVILEGE_ENABLED.

Étant donné que le privilège a été supprimé du jeton, les tentatives de réactiver le privilège aboutissent à l’avertissement ERROR_NOT_ALL_ASSIGNED comme si le privilège n’avait jamais existé.

La tentative de suppression d’un privilège qui n’existe pas dans le jeton entraîne le retour de ERROR_NOT_ALL_ASSIGNED.

Les vérifications de privilèges pour les privilèges supprimés entraînent des STATUS_PRIVILEGE_NOT_HELD. L’échec des privilèges case activée l’audit se produit normalement.

La suppression du privilège étant irréversible, le nom du privilège supprimé n’est pas inclus dans le paramètre PreviousState après un appel à AdjustTokenPrivileges.

Windows XP avec SP1 : La fonction ne peut pas supprimer les privilèges. Cette valeur n’est pas prise en charge.

Aucun

La fonction désactive le privilège.

Si DisableAllPrivileges a la valeur TRUE, la fonction ignore ce paramètre.

[in] BufferLength

Spécifie la taille, en octets, de la mémoire tampon pointée vers le paramètre PreviousState . Ce paramètre peut être égal à zéro si le paramètre PreviousState a la valeur NULL.

[out, optional] PreviousState

Pointeur vers une mémoire tampon que la fonction remplit avec une structure TOKEN_PRIVILEGES qui contient l’état précédent de tous les privilèges modifiés par la fonction. Autrement dit, si un privilège a été modifié par cette fonction, le privilège et son état précédent sont contenus dans la structure TOKEN_PRIVILEGES référencée par PreviousState. Si le membre PrivilegeCount de TOKEN_PRIVILEGES est égal à zéro, cette fonction n’a modifié aucun privilège. Ce paramètre peut être NULL.

Si vous spécifiez une mémoire tampon trop petite pour recevoir la liste complète des privilèges modifiés, la fonction échoue et n’ajuste aucun privilège. Dans ce cas, la fonction définit la variable pointée vers le paramètre ReturnLength sur le nombre d’octets requis pour contenir la liste complète des privilèges modifiés.

[out, optional] ReturnLength

Pointeur vers une variable qui reçoit la taille requise, en octets, de la mémoire tampon vers laquelle pointe le paramètre PreviousState . Ce paramètre peut avoir la valeur NULL si PreviousState a la valeur NULL.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro. Pour déterminer si la fonction a ajusté tous les privilèges spécifiés, appelez GetLastError, qui retourne l’une des valeurs suivantes lorsque la fonction réussit :

Code de retour	Description
ERROR_SUCCESS	La fonction a ajusté tous les privilèges spécifiés.
ERROR_NOT_ALL_ASSIGNED	Le jeton ne dispose pas d’un ou plusieurs des privilèges spécifiés dans le paramètre NewState . La fonction peut réussir avec cette valeur d’erreur même si aucun privilège n’a été ajusté. Le paramètre PreviousState indique les privilèges qui ont été ajustés.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

La fonction AdjustTokenPrivileges ne peut pas ajouter de nouveaux privilèges au jeton d’accès. Il peut uniquement activer ou désactiver les privilèges existants du jeton. Pour déterminer les privilèges du jeton, appelez la fonction GetTokenInformation .

Le paramètre NewState peut spécifier des privilèges que le jeton n’a pas, sans provoquer l’échec de la fonction. Dans ce cas, la fonction ajuste les privilèges dont dispose le jeton et ignore les autres privilèges afin que la fonction réussisse. Appelez la fonction GetLastError pour déterminer si la fonction a ajusté tous les privilèges spécifiés. Le paramètre PreviousState indique les privilèges qui ont été ajustés.

Le paramètre PreviousState récupère une structure TOKEN_PRIVILEGES qui contient l’état d’origine des privilèges ajustés. Pour restaurer l’état d’origine, transmettez le pointeur PreviousState comme paramètre NewState dans un appel suivant à la fonction AdjustTokenPrivileges .

Exemples

Pour obtenir un exemple qui utilise cette fonction, consultez Activation et désactivation des privilèges.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	securitybaseapi.h (inclure Windows.h)
Bibliothèque	Advapi32.lib
DLL	Advapi32.dll