Função SeFilterToken (ntifs.h)

Artigo
10/04/2023

A rotina SeFilterToken cria um novo token de acesso que é uma versão restrita de um token de acesso existente.

Sintaxe

NTSTATUS SeFilterToken(
  [in]           PACCESS_TOKEN     ExistingToken,
  [in]           ULONG             Flags,
  [in, optional] PTOKEN_GROUPS     SidsToDisable,
  [in, optional] PTOKEN_PRIVILEGES PrivilegesToDelete,
  [in, optional] PTOKEN_GROUPS     RestrictedSids,
                 PACCESS_TOKEN     *FilteredToken
);

Parâmetros

[in] ExistingToken

Ponteiro para um token primário ou de representação. O token também pode ser um token restrito. Esse token já deve estar aberto para acesso TOKEN_DUPLICATE. Esse ponteiro pode ser obtido de um identificador de token existente chamando ObReferenceObjectByHandle, especificando TOKEN_DUPLICATE como o tipo DesiredAccess .

[in] Flags

Especifica opções de privilégios adicionais. Esse parâmetro pode ser zero ou uma combinação dos valores a seguir.

Valor	Significado
DISABLE_MAX_PRIVILEGE	Desabilita todos os privilégios no novo token, exceto SE_CHANGE_NOTIFY_PRIVILEGE. Se esse valor for especificado, o parâmetro PrivilegesToDelete será ignorado.
SANDBOX_INERT	Armazena o sinalizador TOKEN_SANDBOX_INERT no token.

[in, optional] SidsToDisable

Ponteiro para uma estrutura de TOKEN_GROUPS que contém uma matriz de estruturas de SID_AND_ATTRIBUTES que especificam os SIDs somente negação no token restrito. O sistema usa um SID somente negação para negar o acesso a um objeto protegível. A ausência de um SID somente negação não permite acesso.

Desabilitar um SID ativa SE_GROUP_USE_FOR_DENY_ONLY e desativa SE_GROUP_ENABLED e SE_GROUP_ENABLED_BY_DEFAULT. Todos os outros atributos são ignorados.

Atributos somente negação se aplicam a qualquer combinação de SIDs de um token existente, incluindo o SID do usuário e SIDs de grupo que têm o atributo SE_GROUP_MANDATORY. Para obter os SIDs associados ao token existente, chame SeQueryInformationToken com os sinalizadores TokenUser e TokenGroups. SeFilterToken ignora todos os SIDs na matriz que também não são encontrados no token existente.

SeFilterToken ignora os membros atributos das estruturas SID_AND_ATTRIBUTES.

Esse parâmetro é opcional e pode ser NULL.

[in, optional] PrivilegesToDelete

Ponteiro para uma estrutura TOKEN_PRIVILEGES que contém uma matriz de estruturas de LUID_AND_ATTRIBUTES que especificam os privilégios a serem excluídos no token restrito.

Para obter os privilégios mantidos pelo token existente, chame SeQueryInformationToken com o sinalizador TokenPrivileges. SeFilterToken ignora todos os privilégios na matriz que não são mantidos pelo token existente.

SeFilterToken ignora os membros atributos das estruturas LUID_AND_ATTRIBUTES.

Esse parâmetro é opcional e pode ser NULL.

[in, optional] RestrictedSids

Ponteiro para uma estrutura de TOKEN_GROUPS que contém uma matriz de estruturas de SID_AND_ATTRIBUTES que especificam uma lista de SIDs restritos para o novo token. Se o token existente for um token restrito, a lista de SIDs de restrição para o novo token será a interseção dessa matriz e a lista de SIDs restrincionais para o token existente.

Os membros atributos das estruturas SID_AND_ATTRIBUTES devem ser zero. A restrição de SIDs sempre está habilitada para verificações de acesso.

Esse parâmetro é opcional e pode ser NULL.

FilteredToken

Ponteiro para uma variável alocada pelo chamador que recebe o endereço do novo token restrito. O novo token é do mesmo tipo, primário ou representação, que o token existente.

Retornar valor

Se um ou mais dos valores de parâmetro forem inválidos, SeFilterToken retornará STATUS_INVALID_PARAMETER. (Esse valor será retornado se o token de destino não for um token de representação.) Caso contrário, SeFilterToken retornará STATUS_SUCCESS.

Comentários

SeFilterToken pode restringir o token das seguintes maneiras:

Aplique o atributo somente negação aos SIDs no token para que eles não possam ser usados para acessar objetos protegidos. Para obter mais informações sobre o atributo somente negação, consulte Atributos sid em um token de acesso na documentação do SDK do Microsoft Windows.
Remova privilégios do token.
Especifique uma lista de SIDs restritos, que o sistema usa quando verifica o acesso do token a um objeto protegível. O sistema executa duas verificações de acesso: uma usando SIDs habilitados do token e outra usando a lista de SIDs restritos. O acesso será concedido somente se ambas as verificações de acesso permitirem os direitos de acesso solicitados.

O token restrito pode ser usado junto com SeCreateClientSecurity e SeImpersonateClientEx para criar um processo que tenha direitos e privilégios de acesso restritos.

Para obter mais informações sobre segurança e controle de acesso, consulte Modelo de segurança do Windows para desenvolvedores de driver e a documentação sobre esses tópicos no SDK do Windows.

Quando o token retornado no NewToken não for mais necessário, libere-o chamando ObDereferenceObject.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP
Plataforma de Destino	Universal
Cabeçalho	ntifs.h (inclua Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	< DISPATCH_LEVEL