CreateRestrictedToken

[This is preliminary documentation and subject to change.]

The CreateRestrictedToken function creates a new access token that is a restricted version of an existing access token.

BOOL CreateRestrictedToken(
  HANDLE ExistingTokenHandle,   // handle to existing token
  DWORD Flags,       // flags to delete all privileges 
                     // or apply the deny-only attribute to all SIDs
  DWORD DisableSidCount,              // number of deny-only SIDs
  PSID_AND_ATTRIBUTES SidsToDisable,  // array of deny-only SIDs
  DWORD DeletePrivilegeCount,   // number of privileges to delete
  PLUID_AND_ATTRIBUTES PrivilegesToDelete,  // privileges to delete
  DWORD RestrictedSidCount,     // number of restricting SIDs
  PSID_AND_ATTRIBUTES SidsToRestrict,  // array of restricting SIDs
  PHANDLE NewTokenHandle        // receives handle to new token
);
 

Parameters

ExistingTokenHandle

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

A set of bit flags you can use to delete all privileges or apply the deny-only attribute to all SIDs in the new token. This parameter can be zero, or it can be a combination of the following flags.

Flag	Meaning
DELETE_MAX_PRIVILEGES	Deletes all privileges in the new token. If this flag is specified, the DeletePrivilegeCount and PrivilegesToDelete parameters are ignored.
DISABLE_MAX_SIDS	Applies the deny-only attribute to the user SID and all group SIDs in the new token. The system uses a deny-only SID to deny access to a securable object, but not to allow access. If this flag is specified, the DisableSidCount and SidsToDisable parameters are ignored.

DisableSidCount

Specifies the number of entries in the SidsToDisable array.

SidsToDisable

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, but not to allow access.

You can apply the deny-only attribute to any combination of the 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 members of the SID_AND_ATTRIBUTES structures.

This parameter can be NULL if you don't want to disable any SIDs.

DeletePrivilegeCount

Specifies the number of entries in the PrivilegesToDelete array.

PrivilegesToDelete

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

You can use the GetTokenInformation function with the TokenPrivileges flag to get 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 don't want to delete any privileges.

RestrictedSidCount

Specifies the number of entries in the SidsToRestrict array.

SidsToRestrict

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.

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

This parameter can be NULL if you don't want to specify any restricting SIDs.

NewTokenHandle

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 Values

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.

QuickInfo

  Windows NT: Requires version 5.0 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in winbase.h.
  Import Library: Use advapi32.lib.

See Also

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