Função CreateRestrictedToken (securitybaseapi.h)
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 SIDs ( identificadores de segurança ) desabilitados, privilégios excluídos e uma lista de SIDs restritos. 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 um token primário ou 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 |
|---|---|
|
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. |
|
Se esse valor for usado, o sistema não verificará as regras do AppLocker nem aplicará políticas de restrição de software. Para o 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 para a 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 o KB2532445 instalado, 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 está executando o Windows 7 ou o Windows Server 2008 R2" na Base de Dados de Conhecimento de Ajuda e Suporte em http://support.microsoft.com/kb/2532445. Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Não há suporte para AppLocker. O AppLocker foi introduzido no Windows 7 e no Windows Server 2008 R2. |
|
O novo token é um token LUA.
Windows Server 2003 e Windows XP: Não há suporte para esse valor. |
|
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: Não há suporte para esse valor. |
[in] DisableSidCount
Especifica o número de entradas na matriz 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 membro Atributos da estrutura SID_AND_ATTRIBUTES .
Esse parâmetro poderá ser NULL se nenhum SIDs for 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 membros de Atributos das estruturas de LUID_AND_ATTRIBUTES .
Esse parâmetro poderá 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 SidsToRestrict .
[in, optional] SidsToRestrict
Um ponteiro para uma matriz de estruturas de SID_AND_ATTRIBUTES que especificam uma lista de RESTRIÇÕES de SIDs 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 restrincionais 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 que restringe.
O membro Attributes da estrutura SID_AND_ATTRIBUTES deve ser zero. A restrição de SIDs sempre está habilitada para verificações de acesso.
Esse parâmetro poderá ser NULL se você não quiser especificar sids restritórios.
[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 é o mesmo tipo, primário ou representação, que o token existente. O identificador retornado em NewTokenHandle pode ser duplicado.
Valor retornado
Se a função for bem-sucedida, o valor retornado será diferente de zero.
Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.
Comentários
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 habilitados 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 ImpersonateLoggedOnUser .
Requisitos
| Cliente mínimo com suporte | Windows XP [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2003 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | securitybaseapi.h (inclua Windows.h) |
| Biblioteca | Advapi32.lib |
| DLL | Advapi32.dll |
Confira também
Visão geral do Controle de Acesso