Edit

SaferComputeTokenFromLevel function (winsafer.h)

  • Article

The SaferComputeTokenFromLevel function restricts a token using restrictions specified by a SAFER_LEVEL_HANDLE.

Syntax

BOOL SaferComputeTokenFromLevel(
  [in]                SAFER_LEVEL_HANDLE LevelHandle,
  [in, optional]      HANDLE             InAccessToken,
  [out]               PHANDLE            OutAccessToken,
  [in]                DWORD              dwFlags,
  [in, out, optional] LPVOID             lpReserved
);

Parameters

[in] LevelHandle

SAFER_LEVEL_HANDLE that contains the restrictions to place on the input token. Do not pass handles with a LevelId of SAFER_LEVELID_FULLYTRUSTED or SAFER_LEVELID_DISALLOWED to this function. This is because SAFER_LEVELID_FULLYTRUSTED is unrestricted and SAFER_LEVELID_DISALLOWED does not contain a token.

[in, optional] InAccessToken

Token to be restricted. If this parameter is NULL, the token of the current thread will be used. If the current thread does not contain a token, the token of the current process is used.

[out] OutAccessToken

The resulting restricted token.

[in] dwFlags

Specifies the behavior of the method. The value can be NULL or one or more of the following values combined by using a bitwise-OR operation.

Value Meaning
SAFER_TOKEN_NULL_IF_EQUAL
1 (0x1)
 If the OutAccessToken parameter is not more restrictive than the InAccessToken parameter, the OutAccessToken parameter returns NULL.
SAFER_TOKEN_COMPARE_ONLY
2 (0x2)
 The token specified by the InAccessToken parameter is compared with the token that would be created if the restrictions specified by the LevelHandle parameter were applied. The restricted token is not actually created.

On output, the value of the lpReserved parameter specifies the result of the comparison.
SAFER_TOKEN_MAKE_INERT
4 (0x4)
 If this flag is set, 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.

Set this flag when creating a setup program that must run extracted DLLs during installation.

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

Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP:  AppLocker is not supported.
SAFER_TOKEN_WANT_FLAGS
8 (0x8)
 On output, the value of the lpReserved parameter specifies the set of flags used to create the restricted token.

[in, out, optional] lpReserved

If the SAFER_TOKEN_COMPARE_ONLY flag is set, this parameter, on output, specifies the result of the token comparison. The output value is an LPDWORD. A value of –1 indicates that the resulting token would be less privileged than the token specified by the InAccessToken parameter.

If the SAFER_TOKEN_WANT_FLAGS flag is set, and the SAFER_TOKEN_COMPARE_ONLY flag is not set, this parameter is an LPDWORD value that specifies the flags used to create the restricted token.

Return value

TRUE if the function succeeds; otherwise, FALSE. For extended information, call GetLastError.

Requirements

Requirement Value
Minimum supported client Windows XP [desktop apps only]
Minimum supported server Windows Server 2003 [desktop apps only]
Target Platform Windows
Header winsafer.h
Library Advapi32.lib
DLL Advapi32.dll
API set ext-ms-win-advapi32-safer-l1-1-0 (introduced in Windows 8)