Exportar (0) Imprimir
Expandir Todos
Expand Minimize
EN
Este conteúdo não está disponível no seu idioma mas aqui tem a versão em inglês.
0 de 1 classificaram como útil - Classificar este tópico

CreateRestrictedToken function

The CreateRestrictedToken function creates a new access token that is a restricted version of an existing access token. The restricted token can have disabled security identifiers (SIDs), deleted privileges, and a list of restricting SIDs. For more information, see Restricted Tokens.

Syntax


BOOL WINAPI CreateRestrictedToken(
  _In_      HANDLE ExistingTokenHandle,
  _In_      DWORD Flags,
  _In_      DWORD DisableSidCount,
  _In_opt_  PSID_AND_ATTRIBUTES SidsToDisable,
  _In_      DWORD DeletePrivilegeCount,
  _In_opt_  PLUID_AND_ATTRIBUTES PrivilegesToDelete,
  _In_      DWORD RestrictedSidCount,
  _In_opt_  PSID_AND_ATTRIBUTES SidsToRestrict,
  _Out_     PHANDLE NewTokenHandle
);

Parameters

ExistingTokenHandle [in]

A handle to a primary or impersonation token. The token can also be a restricted token. The handle must have TOKEN_DUPLICATE access to the token.

Flags [in]

Specifies additional privilege options. This parameter can be zero or a combination of the following values.

ValueMeaning
DISABLE_MAX_PRIVILEGE
0x1

Disables all privileges in the new token except the SeChangeNotifyPrivilege privilege. If this value is specified, the DeletePrivilegeCount and PrivilegesToDelete parameters are ignored.

SANDBOX_INERT
0x2

If this value is used, the system does not check AppLocker rules or apply Software Restriction Policies. For AppLocker, this flag disables checks for all four rule collections: Executable, Windows Installer, Script, and DLL.

When creating a setup program that must run extracted DLLs during installation, use the flag SAFER_TOKEN_MAKE_INERT in the SaferComputeTokenFromLevel function.

A token can be queried for existence of this flag by using GetTokenInformation.

Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003, and Windows XP:  On systems with KB2532445 installed, the caller must be running as LocalSystem or TrustedInstaller or the system ignores this flag. For more information, see "You can circumvent AppLocker rules by using an Office macro on a computer that is running Windows 7 or Windows Server 2008 R2" in the Help and Support Knowledge Base at http://support.microsoft.com/kb/2532445.

Windows Server 2008, Windows Vista, Windows Server 2003, and Windows XP:  AppLocker is not supported. AppLocker was introduced in Windows 7 and Windows Server 2008 R2.

LUA_TOKEN
0x4

The new token is a LUA token.

Windows Server 2003 and Windows XP:  This value is not supported.

WRITE_RESTRICTED
0x8

The new token contains restricting SIDs that are considered only when evaluating write access.

Windows XP with SP2 and later:  The value of this constant is 0x4. For an application to be compatible with Windows XP with SP2 and later operating systems, the application should query the operating system by calling the GetVersionEx function to determine which value should be used.

Windows Server 2003 and Windows XP with SP1 and earlier:  This value is not supported.

 

DisableSidCount [in]

Specifies the number of entries in the SidsToDisable array.

SidsToDisable [in, optional]

A pointer to an array of SID_AND_ATTRIBUTES structures that specify the deny-only SIDs in the restricted token. The system uses a deny-only SID to deny access to a securable object. The absence of a deny-only SID does not allow access.

Disabling a SID turns on SE_GROUP_USE_FOR_DENY_ONLY and turns off SE_GROUP_ENABLED and SE_GROUP_ENABLED_BY_DEFAULT. All other attributes are ignored.

Deny-only attributes apply to any combination of an existing token's SIDs, including the user SID and group SIDs that have the SE_GROUP_MANDATORY attribute. To get the SIDs associated with the existing token, use the GetTokenInformation function with the TokenUser and TokenGroups flags. The function ignores any SIDs in the array that are not also found in the existing token.

The function ignores the Attributes member of the SID_AND_ATTRIBUTES structure.

This parameter can be NULL if no SIDs are to be disabled.

DeletePrivilegeCount [in]

Specifies the number of entries in the PrivilegesToDelete array.

PrivilegesToDelete [in, optional]

A pointer to an array of LUID_AND_ATTRIBUTES structures that specify the privileges to delete in the restricted token.

The GetTokenInformation function can be used with the TokenPrivileges flag to retrieve the privileges held by the existing token. The function ignores any privileges in the array that are not held by the existing token.

The function ignores the Attributes members of the LUID_AND_ATTRIBUTES structures.

This parameter can be NULL if you do not want to delete any privileges.

If the calling program passes too many privileges in this array, CreateRestrictedToken returns ERROR_INVALID_PARAMETER.

RestrictedSidCount [in]

Specifies the number of entries in the SidsToRestrict array.

SidsToRestrict [in, optional]

A pointer to an array of SID_AND_ATTRIBUTES structures that specify a list of restricting SIDs for the new token. If the existing token is a restricted token, the list of restricting SIDs for the new token is the intersection of this array and the list of restricting SIDs for the existing token. No check is performed to remove duplicate SIDs that were placed on the SidsToRestrict parameter. Duplicate SIDs allow a restricted token to have redundant information in the restricting SID list.

The Attributes member of the SID_AND_ATTRIBUTES structure must be zero. Restricting SIDs are always enabled for access checks.

This parameter can be NULL if you do not want to specify any restricting SIDs.

NewTokenHandle [out]

A pointer to a variable that receives a handle to the new restricted token. This handle has the same access rights as ExistingTokenHandle. The new token is the same type, primary or impersonation, as the existing token. The handle returned in NewTokenHandle can be duplicated.

Return value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The CreateRestrictedToken function can restrict the token in the following ways:

  • Apply the deny-only attribute to SIDs in the token so they cannot be used to access secured objects. For more information about the deny-only attribute, see SID Attributes in an Access Token.
  • Remove privileges from the token.
  • Specify a list of restricting SIDs, which the system uses when it checks the token's access to a securable object. The system performs two access checks: one using the token's enabled SIDs, and another using the list of restricting SIDs. Access is granted only if both access checks allow the requested access rights.

You can use the restricted token in the CreateProcessAsUser function to create a process that has restricted access rights and privileges. If a process calls CreateProcessAsUser using a restricted version of its own token, the calling process does not need to have the SE_ASSIGNPRIMARYTOKEN_NAME privilege.

You can use the restricted token in the ImpersonateLoggedOnUser function.

Caution  Applications that use restricted tokens should run the restricted application on desktops other than the default desktop. This is necessary to prevent an attack by a restricted application, using SendMessage or PostMessage, to unrestricted applications on the default desktop. If necessary, switch between desktops for your application purposes.

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Winbase.h (include Windows.h)

Library

Advapi32.lib

DLL

Advapi32.dll

See also

Access Control Overview
Basic Access Control Functions
CreateProcessAsUser
GetTokenInformation
ImpersonateLoggedOnUser
IsTokenRestricted
LUID_AND_ATTRIBUTES
SID_AND_ATTRIBUTES

 

 

Considera isto útil?
(1500 caracteres restantes)
Obrigado pelos seus comentários

Conteúdo da Comunidade

Adicionar
Mostrar:
© 2014 Microsoft. Todos os direitos reservados.