Función AdjustTokenPrivileges (securitybaseapi.h)

Artículo
03/15/2023

La función AdjustTokenPrivileges habilita o deshabilita los privilegios en el token de acceso especificado. La habilitación o deshabilitación de privilegios en un token de acceso requiere TOKEN_ADJUST_PRIVILEGES acceso.

Sintaxis

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

Parámetros

[in] TokenHandle

Identificador del token de acceso que contiene los privilegios que se van a modificar. El identificador debe tener TOKEN_ADJUST_PRIVILEGES acceso al token. Si el parámetro PreviousState no es NULL, el identificador también debe tener TOKEN_QUERY acceso.

[in] DisableAllPrivileges

Especifica si la función deshabilita todos los privilegios del token. Si este valor es TRUE, la función deshabilita todos los privilegios y omite el parámetro NewState . Si es FALSE, la función modifica los privilegios en función de la información a la que apunta el parámetro NewState .

[in, optional] NewState

Puntero a una estructura TOKEN_PRIVILEGES que especifica una matriz de privilegios y sus atributos. Si el parámetro DisableAllPrivileges es FALSE, la función AdjustTokenPrivileges habilita, deshabilita o quita estos privilegios para el token. En la tabla siguiente se describe la acción realizada por la función AdjustTokenPrivileges , basada en el atributo privilege.

Valor	Significado
SE_PRIVILEGE_ENABLED	La función habilita el privilegio.
SE_PRIVILEGE_REMOVED	El privilegio se quita de la lista de privilegios del token. Los demás privilegios de la lista se reordenan para permanecer contiguos. SE_PRIVILEGE_REMOVED sustituye a SE_PRIVILEGE_ENABLED. Dado que el privilegio se ha quitado del token, intenta volver a habilitar el resultado del privilegio en la advertencia ERROR_NOT_ALL_ASSIGNED como si nunca hubiera existido el privilegio. Si se intenta quitar un privilegio que no existe en el token, ERROR_NOT_ALL_ASSIGNED se devuelve. Las comprobaciones de privilegios para los privilegios quitados dan lugar a STATUS_PRIVILEGE_NOT_HELD. La auditoría de comprobación de privilegios con error se produce como normal. La eliminación del privilegio es irreversible, por lo que el nombre del privilegio quitado no se incluye en el parámetro PreviousState después de una llamada a AdjustTokenPrivileges. Windows XP con SP1: La función no puede quitar privilegios. Este valor no se admite.
None	La función deshabilita el privilegio.

Valor

Significado

SE_PRIVILEGE_ENABLED

La función habilita el privilegio.

SE_PRIVILEGE_REMOVED

El privilegio se quita de la lista de privilegios del token. Los demás privilegios de la lista se reordenan para permanecer contiguos.

SE_PRIVILEGE_REMOVED sustituye a SE_PRIVILEGE_ENABLED.

Dado que el privilegio se ha quitado del token, intenta volver a habilitar el resultado del privilegio en la advertencia ERROR_NOT_ALL_ASSIGNED como si nunca hubiera existido el privilegio.

Si se intenta quitar un privilegio que no existe en el token, ERROR_NOT_ALL_ASSIGNED se devuelve.

Las comprobaciones de privilegios para los privilegios quitados dan lugar a STATUS_PRIVILEGE_NOT_HELD. La auditoría de comprobación de privilegios con error se produce como normal.

La eliminación del privilegio es irreversible, por lo que el nombre del privilegio quitado no se incluye en el parámetro PreviousState después de una llamada a AdjustTokenPrivileges.

Windows XP con SP1: La función no puede quitar privilegios. Este valor no se admite.

None

La función deshabilita el privilegio.

Si DisableAllPrivileges es TRUE, la función omite este parámetro.

[in] BufferLength

Especifica el tamaño, en bytes, del búfer al que apunta el parámetro PreviousState . Este parámetro puede ser cero si el parámetro PreviousState es NULL.

[out, optional] PreviousState

Puntero a un búfer que la función rellena con una estructura de TOKEN_PRIVILEGES que contiene el estado anterior de los privilegios que modifica la función. Es decir, si esta función ha modificado un privilegio, el privilegio y su estado anterior se encuentran en la estructura TOKEN_PRIVILEGES a la que hace referencia PreviousState. Si el miembro PrivilegeCount de TOKEN_PRIVILEGES es cero, esta función no ha cambiado ningún privilegio. Este parámetro puede ser NULL.

Si especifica un búfer demasiado pequeño para recibir la lista completa de privilegios modificados, se produce un error en la función y no ajusta ningún privilegio. En este caso, la función establece la variable a la que apunta el parámetro ReturnLength en el número de bytes necesarios para contener la lista completa de privilegios modificados.

[out, optional] ReturnLength

Puntero a una variable que recibe el tamaño necesario, en bytes, del búfer al que apunta el parámetro PreviousState . Este parámetro puede ser NULL si PreviousState es NULL.

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es distinto de cero. Para determinar si la función ha ajustado todos los privilegios especificados, llame a GetLastError, que devuelve uno de los siguientes valores cuando la función se realiza correctamente:

Código devuelto	Descripción
ERROR_SUCCESS	La función ajustó todos los privilegios especificados.
ERROR_NOT_ALL_ASSIGNED	El token no tiene uno o varios de los privilegios especificados en el parámetro NewState . La función puede tener éxito con este valor de error incluso si no se ajustaron privilegios. El parámetro PreviousState indica los privilegios que se ajustaron.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Comentarios

La función AdjustTokenPrivileges no puede agregar nuevos privilegios al token de acceso. Solo puede habilitar o deshabilitar los privilegios existentes del token. Para determinar los privilegios del token, llame a la función GetTokenInformation .

El parámetro NewState puede especificar privilegios que el token no tiene, sin provocar un error en la función. En este caso, la función ajusta los privilegios que tiene el token y omite los demás privilegios para que la función se realice correctamente. Llame a la función GetLastError para determinar si la función ha ajustado todos los privilegios especificados. El parámetro PreviousState indica los privilegios que se ajustaron.

El parámetro PreviousState recupera una estructura de TOKEN_PRIVILEGES que contiene el estado original de los privilegios ajustados. Para restaurar el estado original, pase el puntero PreviousState como parámetro NewState en una llamada posterior a la función AdjustTokenPrivileges .

Ejemplos

Para ver un ejemplo que usa esta función, consulte Habilitación y deshabilitación de privilegios.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2003 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	securitybaseapi.h (incluya Windows.h)
Library	Advapi32.lib
Archivo DLL	Advapi32.dll