Location: Symbol Reference > Classes > TJwSecurityToken Class
JWSCL Documentation
ContentsIndexHome
PreviousUpNext
TJwSecurityToken Class
Pascal
TJwSecurityToken = class(TInterfacedObject, IJwBase);

TJwSecurityToken administers a token (impersonated or primary) All token information are retrieved dynamically. The token handle is closed on instance destroying if Shared is set to false. 

A token is a security card that gives the logged on user the right to do things (like start processes a.s.o). Without a token the user would have to prove his/her security state to the system every time. 

The system creates a process token for the process that it can use to get its security constraints. A process token is also called primary token. The process can create threads and decrement their security state by copying the primary token and remove privileges and/or add restrictions. However a thread cannot use a process/primary token. Instead it can only use a impersonated token. So the token must be converted to a impersonation token. However the first process token cannot be converted. It must be duplicated and then converted. After that the thread can call SetThreadToken to change its security context. 

TJwSecurityToken does not support some of the values defined in the MSDN http://msdn2.microsoft.com/en-us/library/aa379626.aspx 

TJwSecurityToken administers a token (impersonated or not) 

TJwSecurityToken Class
 
Name 
Description 
 
This is the overview for the Create constructor overload. 
 
CreateCompatibilityQueryUserToken is a compatibility constructor for CreateWTSQueryUserToken which does not work in Windows 2000 (only Terminal Server). It creates a token of the current logged on user.
This constructor seeks a process of the user and gets its token. It only works in the same (terminal) session of the process.
 
 
This is the overview for the CreateDuplicateExistingToken constructor overload. 
 
Please refer to the MSDN documentation : http://msdn.microsoft.com/en-us/library/aa378184%28VS.85%29.aspx 
 
CreateNewToken forges a new token using ZwCreateToken. This function can only be called successfully when the CREATE_TOKEN privilege is available and the current process it the SYSTEM user. If the current process is a SYSTEM process but the CREATE_TOKEN privilege is missing, retrieve the token from the csrss.exe (session 0) impersonate it and call CreateNewToken. In this way, no restart of Windows is necessary which would be because you had to add the privilege to the SYSTEM account. 
 
This is the overview for the CreateRestrictedToken constructor overload. 
 
CreateTokenByProcess creates a new instances and opens a process token.
To open a token of another session rather than the current session the current process token must be the SYSTEM token. Only the access right TOKEN_READ can be used with an admin token.
If parameter aDesiredAccess is MAXIMUM_ALLOWED and the right READ_CONTROL is not granted the value of the property AccessMask is zero. Otherwise it contains all granted rights for the token.
If you do not specify TOKEN_DUPLICATE, you will get direct access to the target process' token. Therefore you can change the behaviour of the process by changing enabled... more 
 
CreateTokenByProcessId retrieves the token by using a ProcessID. The token of the given process will be duplicated into the current process so maximum access is granted.
If the right TOKEN_DUPLICATE is set in parameter DesiredAccess, the token is duplicated. With this option, in special situations, the new current process can have more access rights on the token than the process specified by ProcessID. If you do not specify TOKEN_DUPLICATE, you will get direct access to the target process' token. Therefore you can change the behaviour of the process by changing enabled privileges. This does not affect an impersonation of the... more 
 
CreateTokenByThread creates a new class instance and opens a thread token if available; otherwise it fails.
 
 
CreateTokenEffective opens a token of the current thread or process. If it can't open the thread token it opens the process token instead.  
 
CreateWTSQueryUserToken opens a token of a logged on user.
This constructor is only present on Windows XP/2003 or higher systems. This call fails if the thread does not have system privileges (belong to system). Enable SE_TCB_NAME privilege for none system principals.
This token can be used to get a token from the specified user in a terminal session (also Fast User Switching). For example: This token is necessary to call CreateProcessAsUser to lunch a process in the given terminal session.
 
 
CreateWTSQueryUserTokenEx opens a token of a logged on user on a local or remote server.
This constructor can be used in Windows 2000 Terminal Server in contrary to CreateWTSQueryUserToken.
 
 
This is Destroy, a member of class TJwSecurityToken. 
Name 
Description 
The following tables list the members exposed by IJwBase. 
The methods of the IJwBase class are listed here. 
TJwSecurityToken Class
Name 
Description 
The following tables list the members exposed by TJwSecurityToken. 
The methods of the TJwSecurityToken class are listed here. 
The properties of the TJwSecurityToken class are listed here. 
 
Name 
Description 
 
.$IFNDEF DELPHI2009_UP 
 
This is GetHashCode, a member of class IJwBase. 
 
This is ToString, a member of class IJwBase. 
TJwSecurityToken Class
 
Name 
Description 
 
CheckTokenMembership checks whether a given SID is member of the token. It returns true if the SID could be found in the list ignoring whether the SID is enabled or not; otherwise it returns false. 
 
ConvertToImpersonatedToken converts the token into an impersonated token. For this purpose the token will be converted and the old TokenHandle will be closed. The impersonated token will be the new TokenHandle. It does nothing if the token is already impersonated. The token instance must be opened with TOKEN_DUPLICATE access right.
Actually you can impersonate a shared token. The impersonated token will be copied into the instance property TokenHandle. The old handle will not be closed if Share is set to true. You must save the old value to close it by yourself.
Because the old handle is discarded... more 
 
ConvertToPrimaryToken converts the token into a primary (or process) token. It does nothing if the token is already a primary token. The token instance must be opened with TOKEN_DUPLICATE access right.
Actually you can impersonate a shared token. The primary token will be copied into the instance property TokenHandle. The old handle will not be closed if Share is set to true. You must save the old value to close it by yourself.
Because the old handle is discarded you must call these functions again : GetTokenPrivileges
ConvertToPrimaryToken needs the following access rights:
  • TOKEN_QUERY
  • READ_CONTROL
  • TOKEN_DUPLICATE
You can use... more 
 
CopyLUID copies a LUID and returns it 
 
Create_OBJECT_ATTRIBUTES creates and initialises a OBJECT_ATTRIBUTES structure. Some members need space on the heap so that Free_OBJECT_ATTRIBUTES must be called to free the structure. 
 
CreateDuplicateToken duplicates the instance AND token.
As the token type and impersonation level the current values of the instance are used.
 
 
overriden basic methods 
 
Free_OBJECT_ATTRIBUTES removes memory allocated by the members which were created by Create_OBJECT_ATTRIBUTES 
 
GetCurrentUserRegKey opens a registry key HKEY_CURRENT_USER of the current thread token. Use it instead of directly access HKEY_CURRENT_USER if you want to access the user registry of an impersonated user.
 
 
This is GetElevationType, a member of class TJwSecurityToken. 
 
This is GetHashCode, a member of class TJwSecurityToken. 
 
see property ImpersonationLevel 
 
This is GetIntegrityLevel, a member of class TJwSecurityToken. 
 
This is GetIntegrityLevelType, a member of class TJwSecurityToken. 
 
This is GetLinkedToken, a member of class TJwSecurityToken. 
 
This is GetMandatoryPolicy, a member of class TJwSecurityToken. 
 
TOKEN_ADJUST_DEFAULT 
 
This is GetPrivilegeAvailable, a member of class TJwSecurityToken. 
 
SE_TCB_NAME 
 
This is GetRunElevation, a member of class TJwSecurityToken. 
 
GetSecurityDescriptor gets the security descriptor. The caller is responsible to free the returned instance. See TJwSecureGeneralObject.GetSecurityInfo for more information about exceptions.
 
 
GetThreadToken returns the token of the current thread or nil if none exists. See CreateTokenByThread for more information.  
 
This is GetTokenDefaultDacl, a member of class TJwSecurityToken. 
 
This is GetTokenGroups, a member of class TJwSecurityToken. 
 
This is GetTokenGroupsAttributesInt, a member of class TJwSecurityToken. 
 
This is GetTokenGroupsAttributesSid, a member of class TJwSecurityToken. 
 
This is GetTokenGroupsEx, a member of class TJwSecurityToken. 
 
GetTokenInformation returns a buffer filled with token information.  
 
GetTokenInformationLength returns the needed memory for a token information.  
 
TOKEN_ADJUST_DEFAULT 
 
SE_TCB_NAME 
 
GetTokenPrivileges creates an instance of TJwPrivilegeSet with all defined privileges of this token. The privilege set is a readonly copy. You should prefer this function if you want to make more changes.
Every time you call this function, the resulted instance TJwPrivilegeSet will be saved into an internal list, that is cleared if the token instance is freed. Be aware that your pointers to these privileges instances are invalid afterwards. However you can free the result by yourself. In that case the privileges instance will be removed from the internal list. 
 
This is GetTokenPrivilegesEx, a member of class TJwSecurityToken. 
 
This is GetTokenRestrictedSids, a member of class TJwSecurityToken. 
 
TOKEN_ADJUST_DEFAULT 
 
This is the overview for the GetTokenSource method overload. 
 
GetTokenStatistics gets token information in a class called TJwSecurityTokenStatistics . The programmer must free the class TJwSecurityTokenStatistics 
 
see TokenType 
 
This is GetTokenUser, a member of class TJwSecurityToken. 
 
GetTokenUserName returns the username of the token user. 
 
This is GetUserName, a member of class TJwSecurityToken. 
 
This is GetVirtualizationAllowed, a member of class TJwSecurityToken. 
 
This is GetVirtualizationEnabled, a member of class TJwSecurityToken. 
 
HasThreadAToken returns whether the current thread has a token or not.  
 
see equivalent msdn function for more information 
 
The ImpersonateLoggedOnUser function lets the calling thread impersonate the security context of a logged-on user. The user is represented by a token handle. If the current instance is already a thread token (=impersonated token), the method is just impersonating it. Otherwise if the current instance is a primary token, the method is converting it to a thread token and then impersonating it. However the second case is worth mentioning because the new thread token is not related to the current token instance. That means any operations on the current instance (e.g. set privileges) don't have an effect on the token... more 
 
see equivalent msdn function for more information 
 
see equivalent msdn function for more information 
 
IsEqual compares the token instance with a second one. This function loads a function from ntdll.dll dynamically. This function is only available on XP or better  
 
This is IsTokenType, a member of class TJwSecurityToken. 
 
LoadUserProfile loads the user profile of the current token instance. It also uses the roaming profile if possible.
 
 
This is the overview for the PrivilegeCheck method overload. 
 
PrivilegeCheckEx works like PrivilegeCheck . However this function uses the winapi call PrivilegeCheck. The property Privilege_Used_For_Access in TJwPrivilege is not supported. 
 
PrivilegedServiceAuditAlarm function generates an audit message in the security event log. For a detailed information see MSDN : http://msdn2.microsoft.com/en-gb/library/aa379305.aspx
If you want to enable audit functions the calling process (not thread token!) needs the SeAuditPrivilege privilege. Per default only services have this privilege. However it can be enabled in group policy editor : "gpedit.msc" manager (under xp) Computer configuration -> Windows settings -> security settings -> local policies -> audit policy enable (success/failure) policy : audit privilege The parameter AccessGranted is linked with the type of policy - success or failiure. (http://www.nemesisblue.info/images%5Cgpedit1.gif)
The audit event can be seen in the... more 
 
RemoveThreadToken removes the token from the thread.  
 
This is RetrieveSpecificAccessRights, a member of class TJwSecurityToken. 
 
see equivalent msdn function for more information 
 
This is the overview for the SaferComputeTokenFromLevel method overload. 
 
This is the overview for the SetIntegrityLevel method overload. 
 
This is SetIntegrityLevelType, a member of class TJwSecurityToken. 
 
This is SetPrimaryGroup, a member of class TJwSecurityToken. 
 
This is SetPrivilegeEnabled, a member of class TJwSecurityToken. 
 
SetSecurityDescriptor sets the security descriptor. See TJwSecureGeneralObject.SetSecurityInfo for more information about exceptions. Warning: Changing the security descriptor's security information can lead to security holes.
 
 
SetThreadToken sets the thread token.  
 
This is SetTokenDefaultDacl, a member of class TJwSecurityToken. 
 
This is SetTokenGroups, a member of class TJwSecurityToken. 
 
This is SetTokenGroupsAttributesInt, a member of class TJwSecurityToken. 
 
This is SetTokenGroupsAttributesSid, a member of class TJwSecurityToken. 
 
This is SetTokenOrigin, a member of class TJwSecurityToken. 
 
This is SetTokenOwner, a member of class TJwSecurityToken. 
 
This is SetTokenSessionId, a member of class TJwSecurityToken. 
 
This is ToString, a member of class TJwSecurityToken. 
 
UnLoadUserProfile unloads a user profile loaded by LoadUserProfile. Member ProfileInfo.Profile will be set to INVALID_HANDLE_VALUE.  
TJwSecurityToken Class
 
Name 
Description 
 
AccessMask contains the access flags that was specified when the token was created or opened 
 
ElevationType returns the elavation type of the process on a Windows Vista system. If the system is not a supported the exception EJwsclUnsupportedWindowsVersionException will be raised 
 
ImpersonationLevel returns the impersonation level of an impersonated token. If the token is a primary token, the result is always DEFAULT_IMPERSONATION_LEVEL 
 
IsImpersonationToken returns true if the current token instance is a impersonated token; otherwise false. Same as IsThreadToken 
 
IsPrimaryToken returns true if the current token instance is a primary token; otherwise false. 
 
IsRestricted returns true if the token was created by CreateRestrictedToken (or by the equivalent winapi function); otherwise false The call just checks for deny SIDs in the token groups and if it finds any deny SID it returns true. Removed privileges are not detectable. 
 
IsThreadToken returns true if the current token instance is a thread token; otherwise false; Same as IsImpersonationToken
 
IsTokenMemberShip[aSID checks if a user is listed in the tokens user list 
 
LinkedToken returns the linked token of this token. In vista every token can have a second token that has more or less rights. The UAC uses this token to assign it to a new process with elevated rights. However this token is useless for non privileged tokens because SetThreadToken and other functions which get this token checks whether the user can use this token or not. 
 
MandatoryPolicy returns the mandatory policy of the token. This property can have one the following values (from MSDN: http://msdn2.microsoft.com/en-us/library/bb394728.aspx):
  • TOKEN_MANDATORY_POLICY_OFF No mandatory integrity policy is enforced for the token.
  • TOKEN_MANDATORY_POLICY_NO_WRITE_UP A process associated with the token cannot write to objects that have a greater mandatory integrity level.
  • TOKEN_MANDATORY_POLICY_NEW_PROCESS_MIN A process created with the token has an integrity level that is the lesser of the parent-process integrity level and the executable-file integrity level.
  • TOKEN_MANDATORY_POLICY_VALID_MASK A combination of TOKEN_MANDATORY_POLICY_NO_WRITE_UP and TOKEN_MANDATORY_POLICY_NEW_PROCESS_MIN
 
 
PrimaryGroup sets or gets the primary group. To set the value the token needs TOKEN_ADJUST_DEFAULT privilege 
 
PrivilegeAvailable[Name checks whether a defined privilege is available in the token. It returns true if the privilege was found; otherwise false. 
 
PrivilegeEnabled[Name sets or gets a privilege of the token. If you plan to use this property extensivly try GetTokenPrivileges instead.
EJwsclPrivilegeNotFoundException will be raised if you try to set a privilege that is unknown or not available in the token. If you try to read a privilege that could not be found in the privilege list the return value will be false. 
 
RunElevation returns the elavation status of the process on a Windows Vista system. If the system is not a supported the exception EJwsclUnsupportedWindowsVersionException will be raised 
 
Shared is a user defined boolean state that defines whether the token handle is used out of this instance scope. If true some methods do not work because they closes the handle which would lead to unpredictable results. 
 
TOKEN_ADJUST_DEFAULT 
 
TokenGroups contains the groups which the token belongs to. The caller is responsible to free the returned security id list. Do not use members of TokenGroups directly without using a variable. Every call of members directly will result into a new list!
The token handle must be valid otherwise EJwsclInvalidTokenHandle will be raised.
Get: see GetTokenInformation for more information about exceptions. Set: EJwsclNILParameterException is raised if the given list is nil. EJwsclWinCallFailedException is raised if a call to AdjustTokenGroups failed. 
 
TokenGroupsAttributes[Index sets or gets the token groups attributes. Through these attributes a token group can be activated to let AccessCheck use it in its checking. This property raises EListError if the Index could not be found. For further information and exceptions see TokenGroups
 
TokenGroupsAttributesBySid[Sid sets or gets the token groups attributes. Through these attributes a token group can be activated to let AccessCheck use it in its checking. This property raises EListError if the Sid could not be found. For further information and exceptions see TokenGroups
 
TokenHandle contains a handle to the opened token. It can be zero. 
 
TokenIntegrityLevel returns the integrity level of the token. 
 
TokenIntegrityLevelType sets or gets the TokenIntegrityLevel in an easier way. This property uses iltLow, iltMedium, iltHigh, iltSystem and iltProtected to get or set the integrity level. 
 
TokenOrigin sets or gets the token origin. The value can only be set if it has not been already set. The process or thread needs the SE_TCB_NAME privilege to set a value. 
 
TokenOwner sets or gets the token owner. To set the value the token needs TOKEN_ADJUST_DEFAULT privilege.
Returned Sid must be freed. 
 
TokenRestrictedSids contains all users that have restricted rights on the token. The user must free the list 
 
TokenSessionId sets or gets the Session ID of the token. To set the value the token needs SE_TCB_NAME privilege.
A write call on a Windows 2000 is ignored! A write call on needs the SE_TCB_NAME privilege.
To set the SessionID in an existing token you need to create a duplicate first and set the ID of the duplicated token. Use CreateDuplicateExistingToken for this reason.
See http://msdn2.microsoft.com/en-us/library/aa379591.aspx for more information. 
 
TokenTypes gets the token type. The result can be one of these values : TokenPrimary, TokenImpersonation 
 
TokenUser contains the user that holds the token. A read call creates a new TJwSecurityId that must be destroyed! 
 
TokenUserName returns the username stored in the token. This value may differ from the API function GetCurrentUserName 
 
UserName returns the logged on user name of the current logon session. The return value may differ from TokenUserName because it gets the username from the logon session and not from the username stored in the token. 
 
VirtualizationAllowed returns the status of allowance of virtualization of the process on a Windows Vista system. If the system is not a supported the exception EJwsclUnsupportedWindowsVersionException will be raised 
 
VirtualizationEnabled returns the status of status of virtualization. It is either on or off and only works on a Windows Vista system. If the system is not a supported the exception EJwsclUnsupportedWindowsVersionException will be raised 
Copyright (c) 2010. All rights reserved.
This help was created by Doc-O-Matic sponsored by toolsfactory software inc.
What do you think about this topic? Send feedback!