CreateRestrictedToken

The CreateRestrictedToken function creates a new access token that is a restricted version of an existing access token. For more information, see Restricted Tokens.

BOOL CreateRestrictedToken(
  HANDLE ExistingTokenHandle,              // handle to existing token
  DWORD Flags,                             // privilege options
  DWORD DisableSidCount,                   // number of deny-only SIDs
  PSID_AND_ATTRIBUTES SidsToDisable,       // deny-only SIDs
  DWORD DeletePrivilegeCount,              // number of privileges
  PLUID_AND_ATTRIBUTES PrivilegesToDelete, // privileges
  DWORD RestrictedSidCount,                // number of restricting SIDs
  PSID_AND_ATTRIBUTES SidsToRestrict,      // list of restricting SIDs
  PHANDLE NewTokenHandle                   // handle to new token
);

Parameters

ExistingTokenHandle

[in] 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 it can the following value.

Value	Meaning
DISABLE_MAX_PRIVILEGE	Disables all privileges in the new token. If this value is specified, the DeletePrivilegeCount and PrivilegesToDelete parameters are ignored.

DisableSidCount

[in] Specifies the number of entries in the SidsToDisable array.

SidsToDisable

[in] 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

[in] Specifies the number of entries in the PrivilegesToDelete array.

PrivilegesToDelete

[in] 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

[in] Specifies the number of entries in the SidsToRestrict array.

SidsToRestrict

[in] 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

[in] 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.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Header: Declared in Winbase.h; include Windows.h.
  Library: Use Advapi32.lib.

See Also

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