Função AdjustTokenPrivileges (securitybaseapi.h)

Artigo
08/25/2023

A função AdjustTokenPrivileges habilita ou desabilita privilégios no token de acesso especificado. Habilitar ou desabilitar privilégios em um token de acesso requer acesso TOKEN_ADJUST_PRIVILEGES.

Sintaxe

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

Um identificador para o token de acesso que contém os privilégios a serem modificados. O identificador deve ter TOKEN_ADJUST_PRIVILEGES acesso ao token. Se o parâmetro PreviousState não for NULL, o identificador também deverá ter acesso TOKEN_QUERY.

[in] DisableAllPrivileges

Especifica se a função desabilita todos os privilégios do token. Se esse valor for TRUE, a função desabilitará todos os privilégios e ignorará o parâmetro NewState . Se for FALSE, a função modificará privilégios com base nas informações apontadas pelo parâmetro NewState .

[in, optional] NewState

Um ponteiro para uma estrutura TOKEN_PRIVILEGES que especifica uma matriz de privilégios e seus atributos. Se o parâmetro DisableAllPrivileges for FALSE, a função AdjustTokenPrivileges habilitará, desabilitará ou removerá esses privilégios para o token. A tabela a seguir descreve a ação executada pela função AdjustTokenPrivileges , com base no atributo privilege.

Valor	Significado
SE_PRIVILEGE_ENABLED	A função habilita o privilégio.
SE_PRIVILEGE_REMOVED	O privilégio é removido da lista de privilégios no token. Os outros privilégios na lista são reordenados para permanecer contíguos. SE_PRIVILEGE_REMOVED substitui SE_PRIVILEGE_ENABLED. Como o privilégio foi removido do token, as tentativas de reabilitar o privilégio resultam no aviso ERROR_NOT_ALL_ASSIGNED como se o privilégio nunca tivesse existido. Tentar remover um privilégio que não existe no token resulta em ERROR_NOT_ALL_ASSIGNED sendo retornado. Verificações de privilégios para privilégios removidos resultam em STATUS_PRIVILEGE_NOT_HELD. Falha no privilégio marcar auditoria ocorre normalmente. A remoção do privilégio é irreversível, portanto, o nome do privilégio removido não é incluído no parâmetro PreviousState após uma chamada para AdjustTokenPrivileges. Windows XP com SP1: A função não pode remover privilégios. Não há suporte para esse valor.
Nenhuma	A função desabilita o privilégio.

Valor

Significado

SE_PRIVILEGE_ENABLED

A função habilita o privilégio.

SE_PRIVILEGE_REMOVED

O privilégio é removido da lista de privilégios no token. Os outros privilégios na lista são reordenados para permanecer contíguos.

SE_PRIVILEGE_REMOVED substitui SE_PRIVILEGE_ENABLED.

Como o privilégio foi removido do token, as tentativas de reabilitar o privilégio resultam no aviso ERROR_NOT_ALL_ASSIGNED como se o privilégio nunca tivesse existido.

Tentar remover um privilégio que não existe no token resulta em ERROR_NOT_ALL_ASSIGNED sendo retornado.

Verificações de privilégios para privilégios removidos resultam em STATUS_PRIVILEGE_NOT_HELD. Falha no privilégio marcar auditoria ocorre normalmente.

A remoção do privilégio é irreversível, portanto, o nome do privilégio removido não é incluído no parâmetro PreviousState após uma chamada para AdjustTokenPrivileges.

Windows XP com SP1: A função não pode remover privilégios. Não há suporte para esse valor.

Nenhuma

A função desabilita o privilégio.

Se DisableAllPrivileges for TRUE, a função ignorará esse parâmetro.

[in] BufferLength

Especifica o tamanho, em bytes, do buffer apontado pelo parâmetro PreviousState . Esse parâmetro poderá ser zero se o parâmetro PreviousState for NULL.

[out, optional] PreviousState

Um ponteiro para um buffer que a função preenche com uma estrutura TOKEN_PRIVILEGES que contém o estado anterior de quaisquer privilégios modificados pela função. Ou seja, se um privilégio tiver sido modificado por essa função, o privilégio e seu estado anterior estarão contidos na estrutura TOKEN_PRIVILEGES referenciada por PreviousState. Se o membro PrivilegeCount de TOKEN_PRIVILEGES for zero, nenhum privilégio foi alterado por essa função. Este parâmetro pode ser NULL.

Se você especificar um buffer muito pequeno para receber a lista completa de privilégios modificados, a função falhará e não ajustará nenhum privilégio. Nesse caso, a função define a variável apontada pelo parâmetro ReturnLength como o número de bytes necessários para manter a lista completa de privilégios modificados.

[out, optional] ReturnLength

Um ponteiro para uma variável que recebe o tamanho necessário, em bytes, do buffer apontado pelo parâmetro PreviousState . Esse parâmetro poderá ser NULL se PreviousState for NULL.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero. Para determinar se a função ajustou todos os privilégios especificados, chame GetLastError, que retorna um dos seguintes valores quando a função é bem-sucedida:

Código de retorno	Descrição
ERROR_SUCCESS	A função ajustou todos os privilégios especificados.
ERROR_NOT_ALL_ASSIGNED	O token não tem um ou mais dos privilégios especificados no parâmetro NewState . A função pode ter êxito com esse valor de erro mesmo que nenhum privilégio tenha sido ajustado. O parâmetro PreviousState indica os privilégios que foram ajustados.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

A função AdjustTokenPrivileges não pode adicionar novos privilégios ao token de acesso. Ele só pode habilitar ou desabilitar os privilégios existentes do token. Para determinar os privilégios do token, chame a função GetTokenInformation .

O parâmetro NewState pode especificar privilégios que o token não tem, sem causar falha na função. Nesse caso, a função ajusta os privilégios que o token tem e ignora os outros privilégios para que a função seja bem-sucedida. Chame a função GetLastError para determinar se a função ajustou todos os privilégios especificados. O parâmetro PreviousState indica os privilégios que foram ajustados.

O parâmetro PreviousState recupera uma estrutura TOKEN_PRIVILEGES que contém o estado original dos privilégios ajustados. Para restaurar o estado original, passe o ponteiro PreviousState como o parâmetro NewState em uma chamada subsequente para a função AdjustTokenPrivileges .

Exemplos

Para obter um exemplo que usa essa função, consulte Habilitando e desabilitando privilégios.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [aplicativos da área de trabalho \| aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	securitybaseapi.h (inclua Windows.h)
Biblioteca	Advapi32.lib
DLL	Advapi32.dll