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 TOKEN_DUPLICATE acesso 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 marcar 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 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, confira "Você pode contornar as regras do AppLocker usando uma macro do Office em um computador que executa 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 todos 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 SID 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 atributos das estruturas 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 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. Nenhuma marcar é 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 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 poderá ser NULL se você não quiser especificar sids restricionais.
[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 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 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.
Você pode usar o token restrito na função ImpersonateLoggedOnUser .
Requisitos
| Requisito | Valor |
|---|---|
| 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
Comentários
Em breve: ao longo de 2024, vamos eliminar problemas do GitHub como o mecanismo de comentários para conteúdo e substituí-lo por um novo sistema de comentários. Para obter mais informações, consulte: https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de