Função CreateRestrictedToken (securitybaseapi.h)

Artigo
11/08/2024

A função CreateRestrictedToken cria um novo token de acesso que é uma versão restrita de um token de acesso existente. O token restrito pode ter desabilitado SIDs (identificadores de segurança), privilégios excluídos e uma lista de SIDs restrinjantes. Para obter mais informações, consulte tokens restritos.

Sintaxe

BOOL CreateRestrictedToken(
  [in]           HANDLE               ExistingTokenHandle,
  [in]           DWORD                Flags,
  [in]           DWORD                DisableSidCount,
  [in, optional] PSID_AND_ATTRIBUTES  SidsToDisable,
  [in]           DWORD                DeletePrivilegeCount,
  [in, optional] PLUID_AND_ATTRIBUTES PrivilegesToDelete,
  [in]           DWORD                RestrictedSidCount,
  [in, optional] PSID_AND_ATTRIBUTES  SidsToRestrict,
  [out]          PHANDLE              NewTokenHandle
);

Parâmetros

[in] ExistingTokenHandle

Um identificador para uma primária ou token de representação. O token também pode ser um token restrito. O identificador deve ter acesso TOKEN_DUPLICATE ao token.

[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 `0x1`	Desabilita todos os privilégios no novo token, exceto o privilégio SeChangeNotifyPrivilege. Se esse valor for especificado, os parâmetros DeletePrivilegeCount e PrivilegesToDelete serão ignorados.
SANDBOX_INERT `0x2`	Se esse valor for usado, o sistema não verificará regras de do AppLocker ou aplicará políticas de restrição de software. Para AppLocker, esse sinalizador desabilita as verificações de todas as quatro coleções de regras: Executável, Windows Installer, Script e DLL. Ao criar um programa de instalação que deve executar DLLs extraídas durante a instalação, use o sinalizador SAFER_TOKEN_MAKE_INERT na função SaferComputeTokenFromLevel. Um token pode ser consultado quanto à existência desse sinalizador usando GetTokenInformation. Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Em sistemas com KB2532445 instalados, o chamador deve estar em execução como LocalSystem ou TrustedInstaller ou o sistema ignora esse sinalizador. Para obter mais informações, consulte Você pode contornar as regras do AppLocker usando uma macro do Office em um computador que esteja executando o Windows 7 ou o Windows Server 2008 R2. Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: AppLocker não tem suporte. O AppLocker foi introduzido no Windows 7 e no Windows Server 2008 R2.
LUA_TOKEN `0x4`	O novo token é um token LUA. Windows Server 2003 e Windows XP: Não há suporte para esse valor.
WRITE_RESTRICTED `0x8`	O novo token contém SIDs restritos que são considerados somente ao avaliar o acesso de gravação. Windows XP com SP2 e posterior: O valor dessa constante é `0x4`. Para que um aplicativo seja compatível com o Windows XP com sistemas operacionais SP2 e posteriores, o aplicativo deve consultar o sistema operacional chamando a função GetVersionEx para determinar qual valor deve ser usado. Windows Server 2003 e Windows XP com SP1 e anteriores: Esse valor não tem suporte.

[in] DisableSidCount

Especifica o número de entradas na matriz de sidsToDisable .

[in, optional] SidsToDisable

Um ponteiro para 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, use a função GetTokenInformation com os sinalizadores TokenUser e TokenGroups. A função ignora os SIDs na matriz que também não são encontrados no token existente.

A função ignora o Attributes membro da estrutura SID_AND_ATTRIBUTES.

Esse parâmetro pode ser NULL se nenhum SID deve ser desabilitado.

[in] DeletePrivilegeCount

Especifica o número de entradas na matriz PrivilegesToDelete .

[in, optional] PrivilegesToDelete

Um ponteiro para uma matriz de estruturas de LUID_AND_ATTRIBUTES que especificam os privilégios a serem excluídos no token restrito.

A função GetTokenInformation pode ser usada com o sinalizador TokenPrivileges para recuperar os privilégios mantidos pelo token existente. A função ignora todos os privilégios na matriz que não são mantidos pelo token existente.

A função ignora os atributos membros das estruturas de LUID_AND_ATTRIBUTES.

Esse parâmetro pode ser NULL se você não quiser excluir nenhum privilégio.

Se o programa de chamada passar muitos privilégios nessa matriz, CreateRestrictedToken retornará ERROR_INVALID_PARAMETER.

[in] RestrictedSidCount

Especifica o número de entradas na matriz de SidsToRestrict.

[in, optional] SidsToRestrict

Um ponteiro para 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 restrições de SIDs para o novo token será a interseção dessa matriz e a lista de SIDs de restrição para o token existente. Nenhuma verificação é executada para remover SIDs duplicados que foram colocados no parâmetro SidsToRestrict. SIDs duplicados permitem que um token restrito tenha informações redundantes na lista de SID restritiva.

O membro atributos da estrutura SID_AND_ATTRIBUTES deve ser zero. A restrição de SIDs sempre está habilitada para verificações de acesso.

Esse parâmetro pode ser NULL se você não quiser especificar sids restrinjantes.

[out] NewTokenHandle

Um ponteiro para uma variável que recebe um identificador para o novo token restrito. Esse identificador tem os mesmos direitos de acesso que ExistingTokenHandle. O novo token é do mesmo tipo, primário ou de representação, como o token existente. O identificador retornado em NewTokenHandle pode ser duplicado.

Valor de retorno

Se a função for bem-sucedida, o valor retornado não será zero.

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

Observações

A função CreateRestrictedToken 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.
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 habilitadas para o 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.

Você pode usar o token restrito na função CreateProcessAsUser para criar um processo que tenha privilégios e direitos de acesso restritos. Se um processo chamar CreateProcessAsUser usando uma versão restrita de seu próprio token, o processo de chamada não precisará ter o privilégio SE_ASSIGNPRIMARYTOKEN_NAME.

Você pode usar o token restrito na função ImpersonateLoggedOnUser.

Aviso

Os aplicativos que usam tokens restritos devem executar o aplicativo restrito em áreas de trabalho diferentes da área de trabalho padrão. Isso é necessário para evitar um ataque de um aplicativo restrito, usando SendMessage ou PostMessage, para aplicativos irrestritos na área de trabalho padrão. Se necessário, alterne entre áreas de trabalho para fins de aplicativo.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows XP [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows Server 2003 [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	securitybaseapi.h (inclua Windows.h)
biblioteca	Advapi32.lib
de DLL	Advapi32.dll