Tcl Windows API extension

A Locally Unique Identifier (LUID) is a string generated by the command new_luid that is guaranteed to be unique on that system for that boot session.

A Universally Unique Identifier (UUID) is a string generated by the command new_uuid that is guaranteed to be unique on any system at any time.

In both instances, unique means it will not be generated by some other call to that command.

Access Tokens and Privileges

An access token is associated with a process or a thread and contains various elements that determine the security context for the process or thread.

The commands open_process_token and open_thread_token retrieve the access tokens associated with a process and thread respectively. An access token for a specific user account may be obtained using open_user_token. The returned tokens can be passed to other functions to retrieve or set information for the process or thread's privileges and other security related information. When no longer required, the tokens must be passed to close_token in order to release resources.

The commands get_token_user, get_token_groups, get_token_primary_group, get_token_owner and get_token_group_sids_and_attrs retrieve information related to the user and group accounts associated with a token.

The commands get_token_privileges, check_enabled_token_privileges and get_token_privileges_and_attrs retrieve information related to the privileges associated with a token. The commands enable_token_privileges, disable_token_privileges and disable_all_token_privileges allow manipulation of the same. Similarly, enable_privileges and disable_privileges can be used to enable and disable privileges for the current process. eval_with_privileges evaluates a script after enabling specified privileges.

The command get_privilege_description returns a description of a privilege. An empty string is returned if the specified privilege is not a known privilege.

The commands get_token_type and get_token_impersonation_level return information related to impersonation.

get_token_source returns the source of a token. get_token_statistics returns various other pieces of information, such as expiration, memory usage etc.

The commands map_luid_to_privilege and map_privilge_to_luid map LUID's to privilege names. The command is_valid_luid_syntax can be used to check the syntactic validity of a LUID.

Impersonation

Windows allows a thread or process to impersonate a user different from the account in which it was started (given the proper privileges). The functions for impersonation and reverting back are impersonate_token, impersonate_user, impersonate_self, impersonate_namedpipe_client, set_thread_token and revert_to_self.

The command get_current_user returns the user account for the thread taking into consideration any ongoing impersonation.

Impersonation may be done at several levels. These levels control the degree to which the impersonator takes on the identity of the impersonated client. The following constants define the different levels:

anonymous	The impersonating process cannot obtain identification information about the client or impersonate it.
identification	The impersonating process cannot impersonate the client (ie. access resources using the client's credentials) but can obtain identity and privilege information about the client. This can be used for controlling access to its own objects (as opposed to operating system resources).
impersonation	The impersonating process can impersonate the client only on the local system. The client credentials cannot be used to access other resources on the network.
delegation	The impersonating process can use the client's credentials for accessing network resources.

Access Rights

Access rights in the Windows API take the form of a bit mask with each bit signifying a specific desired or granted right. Access rights may be specified to TWAPI functions in the form of a single element or list of elements, each of which is an integer or a symbolic constant. The access rights bit mask passed to the underlying function is formed by OR'ing together the individual elements in the list. In the case of a symbolic constant, the access right is mapped to the appropriate bits before being OR'ed with the other elements.

The following symbolic constants define generic access rights that are mapped by each object type into its own specific rights: generic_read, generic_write, generic_execute and generic_all.

The following symbolic constants define access rights that are common to all securable object types: delete, read_control, write_dac, write_owner, synchronize, standard_rights_read, standard_rights_write, standard_rights_execute, standard_rights_required and standard_rights_all. Refer to the Windows SDK for a definition of these access rights.

In addition to the standard rights, specific object types may have other access rights associated with them as described in the following table.

Desktops	desktop_readobjects, desktop_createwindow, desktop_createmenu, desktop_hookcontrol, desktop_journalrecord, desktop_journalplayback, desktop_enumerate, desktop_writeobjects, desktop_switchdesktop.
Events	event_all_access, event_modify_state.
Files	file_all_access, file_generic_read, file_generic_write, file_generic_execute, file_read_data, file_write_data, file_append_data, file_read_ea, file_write_ea, file_execute, file_delete_child, file_read_attributes, file_write_attributes
Mutexes	mutex_all_access, mutex_modify_state
Named pipes	file_all_access, file_read_data, file_write_data, file_create_pipe_instance, file_read_attributes, file_write_attributes
Processes	process_all_access, process_terminate, process_create_thread, process_set_sessionid, process_vm_operation, process_vm_read, process_vm_write, process_dup_handle, process_create_process, process_set_quota, process_set_information, process_query_information, process_suspend_resume
Registry	key_all_access, key_read, key_write, key_execute, key_query_value, key_set_value, key_create_sub_key, key_enumerate_sub_keys, key_notify, key_create_link, key_wow64_32key, key_wow64_64key, key_wow64_res
Semaphores	semaphore_all_access, semaphore_modify_state
Services	service_all_access, service_query_config, service_change_config, service_query_status, service_enumerate_dependents, service_start, service_stop, service_pause_continue, service_interrogate, service_user_defined_control
Threads	thread_all_access, thread_terminate, thread_suspend_resume, thread_get_context, thread_set_context, thread_set_information, thread_query_information, thread_set_thread_token, thread_impersonate, thread_direct_impersonation
Timers	timer_all_access, timer_query_state, timer_modify_state.
Tokens	token_all_access, token_assign_primary, token_duplicate, token_impersonate, token_query, token_query_source, token_adjust_privileges, token_adjust_groups, token_adjust_default, token_adjust_sessionid.
Window stations	winsta_enumdesktops, winsta_readattributes, winsta_accessclipboard, winsta_createdesktop, winsta_writeattributes, winsta_accessglobalatoms, winsta_exitwindows, winsta_enumerate, winsta_readscreen, winsta_all.

Note that some of the symbolic access rights are a combination of other access rights. For example, file_all_access includes all other rights associated with a file object. When an access rights list is returned from a command, it includes both the individual symbolic rights as well as all valid symbols for combined rights.

Access Control Entries

Several functions deal with access control entries (ACE) either directly or as part of the more complex structures. A new ACE may be created through the new_ace command. The structure of an ACE should be treated as opaque and the fields should be manipulated only through the access control entry functions. An access control entry contains the fields described below.

The type of an ACE may be one of the following values: allow, deny, audit, alarm, allow_compound, allow_object, deny_object, audit_object, alarm_object, allow_callback, deny_callback, allow_callback_object, deny_callback_object, audit_callback, alarm_callback, audit_callback_object, alarm_callback_object, mandatory_label. Currently, only the allow, deny and audit type ACE's are supported. The type of an ACE may be manipulated through the get_ace_type and set_ace_type commands.

Each ACE has an SID associated with it that indicates the user or group that the ACE applies to. This may be retrieved or set using the get_ace_sid and set_ace_sid functions.

The access rights granted or restricted by an ACE can be manipulated through the get_ace_rights and set_ace_rights functions.

An ACE may be recursively applied to objects within a container. This is controlled through the get_ace_inheritance and set_ace_inheritance commands.

The command sort_aces may be used to sort a list of ACE elements into the order recommended by Windows.

The command get_ace_text returns a textual description of an ACE.

Access Control List

An access control list (ACL) is an ordered list of access control entries that is applied to a resource. The command new_acl creates a new ACL with an optional set of ACE elements. For the common case of granting access only specific accounts, new_restricted_dacl provides a simpler and more convenient interface.

The commands get_acl_aces and set_acl_aces may be used to retrieve or set the access control entries in the ACL. Alternatively, the commands prepend_acl_aces and append_acl_aces may be used to place additional ACEs in front of or after, respectively, of the current entries in an ACL.

Access control lists are of two types - a discretionary access control list (DACL) controls the operations that may be invoked on a resource based on the identity of the accessor, while a system access control list (SACL) controls the audit events that are generated when the resource is accessed. A SACL should contain only ACE elements of types prefixed with audit or mandatory_label while a DACL should only contain ACE elements of other types.

The list of ACE elements in an ACL may be resorted to conform to the Windows recommended order through the sort_acl_aces command.

Security Descriptors

A security descriptor is associated with a resource and ties together various information that controls access to the resource including the SID of the owner of the resource, the SID of the primary group, a discretionary access control list (DACL) and a system access control list (SACL).

A new security descriptor may be created through the command new_security_descriptor.

The commands get_security_descriptor_owner, get_security_descriptor_group, set_security_descriptor_owner and set_security_descriptor_group retrieve and set the owner and group attributes of a security descriptor.

The commands get_security_descriptor_dacl, get_security_descriptor_sacl, set_security_descriptor_dacl and set_security_descriptor_sacl retrieve and set the DACL and SACL fields of a security descriptor. It is important to distinguish between the absence of a DACL (or SACL) in a security descriptor and an empty DACL (or SACL). The former results in everyone being allowed to access the object whereas the latter results in no one being allowed to access the object. When modifying or creating a security descriptor, pass the literal string null to indicate that the security descriptor has no DACL (or SACL). An empty DACL (or SACL) on the other hand is indicated simply by passing an ACL that does not contain any ACEs.

The command get_security_descriptor_control returns the control flags associated with the security descriptor.

Note that not all fields in a security descriptor need to be initialized. For example, to change the owner of a resource, you only need to create a descriptor with the owner field initialized either at creation time or through a subsequent call to set_security_descriptor_owner. Then this can be passed to the appropriate function to set a resource's security with an option indicating that only the owner field should be changed.

The security information associated with each resource type can be retrieved and modified through functions get_resource_security_descriptor and set_resource_security_descriptor.

The command get_security_descriptor_text returns a textual description of a security descriptor. Commands security_descriptor_to_sddl and sddl_to_security_descriptor can be used to convert security descriptors to SDDL format.

Logon Sessions

A logon session is identified by an LUID and provides the context for a particular instance of an authenticated security principal where the principal may be a user, a computer, a service etc. A single principal, for example a user, may have multiple logon sessions concurrently present at any time. The command find_logon_sessions allows enumeration of logon sessions. The details associated with each can be obtained through the get_logon_session_info command.

User Account Control

Windows Vista and later versions include the User Account Control (UAC) feature that runs even adminstrator account processes with reduced privileges unless explicitly elevated by the user. The command get_token_elevation checks whether a particular process token is elevated or not. The command get_token_linked_token returns the token handle for the token that is linked to an elevated or limited token.

Similarly, the Windows Integrity mechanism attempts to distinguish between applications at different levels of trust and control access to resources accordingly. The commands get_token_integrity and set_token_integrity allow retrieving and setting the integrity level associated with a process token. Alternatively, the higher level commands get_process_integrity and set_process_integrity can also be used for this purpose.

The associated policy for maintaining integrity levels can be read and modified using get_token_integrity_policy and set_token_integrity_policy.

The integrity level associated with a resource can be retrieved and set using the commands get_resource_integrity and set_resource_integrity respectively. The integrity level stored in a security descriptor can be retrieved and set using get_security_descriptor_integrity and set_security_descriptor_integrity.

The above security mechanims also introduced compatibility issues for applications written for older versions of Windows which expected to be able to write to resources at higher integrity levels, such as the system directory, that were now restricted. To allow these applications to run, Windows silently virtualizes protected resources and redirects reads and writes to these resources from such applications. The get_token_virtualization can be used to detect if a process is virtualized in this fashion and set_token_virtualization can be used to enable or disable the state.

For a tutorial and discussion of these issues, refer to the MSDN article.

Commands

append_acl_aces ACL ACELIST

Appends the list of ACEs in ACELIST to the entries in the given ACL. Returns the modified ACL.

check_enabled_privileges PRIVILEGES ?-any?

Without the -any option, the command returns 1 if the given list of privileges is enabled in the token, and 0 otherwise. If the option -any is specified, the command returns 1 if at least one of the privileges is enabled, and 0 otherwise. PRIVLIST is a list of privilege names or LUIDs.

close_token TOKEN

Frees resources associated with an access token.

disable_all_token_privileges TOKEN

This command disables all privileges in the token. An error will be raised if the privilege does not exist or cannot be disabled because of lack of rights to the token handle.

The command returns a list of privileges that were modified by the command because they were not previously disabled. This list can be passed to enable_token_privileges to undo the privilege modifications made by this call.

disable_privileges PRIVLIST

This command disables one or more privileges in the current process. PRIVLIST is a list of privileges each of which may be either a symbolic privilege such as SeLoadDriverPrivilege or a LUID corresponding to a privilege.

An error will be raised if the privilege does not exist or cannot be disabled because of lack of rights to the token handle.

The command returns a list of privileges that were modified by the command because they were not previously disabled. This list can be passed to enable_privileges to undo the privilege modifications made by this call.

disable_token_privileges TOKEN PRIVLIST

This command disables one or more privileges in the token. PRIVLIST is a list of privileges each of which may be either a symbolic privilege such as SeLoadDriverPrivilege or a LUID corresponding to a privilege.

An error will be raised if the privilege does not exist or cannot be disabled because of lack of rights to the token handle.

The command returns a list of privileges that were modified by the command because they were not previously disabled. This list can be passed to enable_token_privileges to restore the token privileges to their original value.

enable_privileges PRIVLIST

This command enables one or more privileges in the current process. PRIVLIST is a list of privileges each of which may be either a symbolic privilege such as SeLoadDriverPrivilege or a LUID corresponding to a privilege.

An error will be raised if a privilege does not exist or cannot be enabled because of lack of rights to the token handle.

The command returns a list of privileges that were modified by the command because they were not previously enabled. This list can be passed to disable_privileges to undo the privilege modifications made by this call.

enable_token_privileges TOKEN PRIVLIST

This command enables one or more privileges in the token. PRIVLIST is a list of privileges each of which may be either a symbolic privilege such as SeLoadDriverPrivilege or a LUID corresponding to a privilege.

An error will be raised if a privilege does not exist or cannot be enabled because of lack of rights to the token handle.

The command returns a list of privileges that were modified by the command because they were not previously enabled. This list can be passed to disable_token_privileges to undo the privilege modifications made by this call.

eval_with_privileges SCRIPT PRIVLIST

The command enables the privileges specified in PRIVLIST, if they were not already enabled, and then evaluates SCRIPT in the caller's context. The command returns the result of SCRIPT after restoring the privileges in effect when the command was called.

find_logon_sessions ?options?

Returns a list of LUID values that identify the logon sessions on the system. By default, all logon sessions are returned. One or more of the following options may be specified to restrict the set of logon sessions that are returned.

-user ACCOUNT	Only returns logon sessions for the specified user. ACCOUNT may be either the account name or the SID for the user.
-type SESSIONTYPELIST	Only returns logon sessions that match one of the specified types. SESSIONTYPELIST is a list of integer logon session types defined in the Windows SDK or the following equivalent tokens: interactive, network, batch, service, proxy, unlockworkstation, networkclear, newcredentials, remoteinteractive, cachedinteractive, cachedremoteinteractive or cachedunlockworkstation.
-tssession TSSESSION	Only returns those logon sessions belonging to the terminal services session identified by TSSESSION.

get_ace_inheritance ACE

Returns a flat list of "option value" pairs that indicate the inheritance characteristics of the ACE. The option elements are -self, -recursecontainers, -recurseobjects and -recurseonelevelonly as described in the documentation for new_ace. In addition, the read-only option -inherited indicates whether the ACE has been inherited from an ancestor or not.

get_ace_rights ACE ?-resourcetype RESOURCETYPE? ?-raw?

Returns a list of access rights contained within an ACE. This is a list of symbolic constants and bit masks as described in Access Rights. The option -resourcetype may be used to map the access rights to symbolic constants for a specific type of resource. RESOURCETYPE must be one of file, pipe, service, registry, process, thread or token.

If the -raw option is specified, the access rights are returned as a single hex bitmask.

get_ace_sid ACE

Returns the SID of the given ACE.

get_ace_text ACE ?-resourcetype RESOURCETYPE?

Returns a textual description of the specified ACE. The option -resourcetype may be specified to indicate that the ACE is for a particular resource type. RESOURCETYPE must be one of the resource type values defined for the get_ace_rights command. This command is primarily useful for debugging and troubleshooting purposes.

get_ace_type ACE

Returns the type of the given ACE. See Access Control Entries for the possible types.

get_acl_aces ACL

Returns the ordered list of ACE elements in the given ACL.

get_acl_rev ACL

Returns the revision level of an ACL. Note that this is controlled by the ACEs in the ACL and cannot be set directly.

get_current_user ?FORMATOPTION?

Returns the user account for the current thread. If the thread is impersonating, this command returns the account being impersonated. Note this is not the same as the $::env(USERNAME) variable as the latter does not take impersonation into account. By default, the command returns the name of the user account in NT 4.0 SAM-compatible format. One of the following options may be specified to return the name in a different format:

-fullyqualifieddn	Fully qualified Active Directory distinguished name.
-samcompatible	NT 4.0 SAM account name (default).
-display	Active Directory human-friendly display name.
-uniqueid	Active Directory GUID format name. This is NOT the same as the SID.
-canonical	Active Directory canonical format.
-userprincipal	User principal format.
-canonicalex	Active Directory canonical format except that the rightmost / is replaced by a newline.
-serviceprincipal	Generalized service principal name.
-dnsdomain	DNS domain followed by the SAM user name.
-sid	User SID instead of name.

Note that all options except -samcompatible and -sid require that the system be part of a Active Directory domain, else an error is raised that no mapping to that format exists.

get_logon_session_info SESSIONLUID ?options?

Returns details for the logon session identified by SESSIONLUID. The information is returned as a flat list of option value pairs and depends on the specified options:

-all	Returns the values for all options.
-authpackage	Returns the name of the package that authenticated the session.
-dnsdomain	Returns the DNS name for the owner of the logon session. This is always empty on Windows 2000.
-logondomain	Returns the name of the domain used to authenticate the session.
-logonid	Returns the LUID for the session (same as SESSIONLUID).
-logonserver	Returns the name of the server used to authenticate the session. This is always an empty string on Windows 2000.
-logontime	Returns the time session owner logged on.
-type	Returns the logon session type (see find_logon_sessions).
-sid	Returns the SID for the session owner.
-tssession	Returns the terminal session identifier for the logon session.
-user	Returns the user name for the session owner.
-userprincipal	Returns the user principal name for the session owner. This is always an empty string on Windows 2000.

get_privilege_description PRIVILEGE

Returns a string description of the specified privilege.

get_resource_integrity RESTYPE NAME ?options?

Retrieves the integrity level associated with a resource. RESTYPE specifies the resource type and if option -handle is not specified, must be one of file, service (Windows service), printer, registry, share (Network shares) or kernelobj (kernel objects such as mutexes, semaphores and events). If option -handle is specified, then RESTYPE may also be one of windowstation, directoryservice, directoryserviceall, providerdefined, wmiguid or registrywow6432key but not share.

NAME specifies the name of the resource, for example, the path of a file unless option -handle is specified in which case it is the handle to the resource.

On systems that do not support integrity levels, the command returns an empty list. Otherwise, a list with two elements is returned. The first element of the list is the integrity value associated with the resource, by default represented as an integer value between 0 and 65535. If the option -raw is specified, the integrity level is returned as the raw SID value as stored internally by Windows in the token. Alternatively, if the -label option is specified the corresponding integrity level range label is returned which is one of untrusted (0-4095), low (4096-8191), medium (8192-12287, high (12288-16383) or system (anything higher).

The second element of the returned list is a list containing zero or or more of the following values: system_mandatory_label_no_write_up, system_mandatory_label_no_read_up, system_mandatory_label_no_execute_up. These control the operations allowed on the resource by processes with lower integrity levels. Refer to the Windows SDK for more details.

get_resource_security_descriptor RESTYPE NAME ?options?

Retrieves the security descriptor attached to a operating system resource. RESTYPE specifies the resource type and if option -handle is not specified, must be one of file, service (Windows service), printer, registry, share (Network shares) or kernelobj (kernel objects such as mutexes, semaphores and events). If option -handle is specified, then RESTYPE may also be one of windowstation, directoryservice, directoryserviceall, providerdefined, wmiguid or registrywow6432key but not share.

NAME specifies the name of the resource, for example, the path of a file unless option -handle is specified in which case it is the handle to the resource.

Without any options being specified, the returned security descriptor will contain only the owner, group and DACL fields. The SACL field will not contain valid data. The following options may be specified to control which fields are returned in the security descriptor:

-all	Includes all fields in the security descriptor. This requires the caller to have the SeSecurityPrivilege privilege enabled.
-dacl	Includes the DACL in the returned security descriptor.
-group	Includes the group information in the returned security descriptor.
-owner	Includes the owner information in the returned security descriptor.
-sacl	Includes the SACL in the returned security descriptor. This requires the caller to have the SeSecurityPrivilege privilege enabled.

get_security_descriptor_control SECD

Returns the control flags contained in the given security descriptor SECD. The flags are returned as a list of zero or more tokens from the following: owner_defaulted, group_defaulted, dacl_present, dacl_defaulted, sacl_present, sacl_defaulted, dacl_auto_inherit_req, sacl_auto_inherit_req, dacl_auto_inherited, sacl_auto_inherited, dacl_protected, sacl_protected, rm_control_valid, self_relative. Refer to the Windows Platform SDK for details.

get_security_descriptor_dacl SECD

Returns the DACL contained in the given security descriptor SECD.

get_security_descriptor_group SECD

Returns the group SID for the given security descriptor SECD.

get_security_descriptor_integrity SECD ?-label|-raw?

Returns the integrity level stored in the given security descriptor SECD. Refer to get_resource_integrity for the option description and format of the returned value.

get_security_descriptor_owner SECD

Returns the owner SID for the given security descriptor SECD.

get_security_descriptor_sacl SECD

Returns the SACL contained in the given security descriptor SECD.

get_security_descriptor_text SECD ?-resourcetype RESOURCETYPE?

Returns a textual description of the specified security descriptor SECD. The option -resourcetype may be specified to indicate that the security descriptor is for a particular resource type. RESOURCETYPE must be one of the resource type values defined for the get_ace_rights command. This command is primarily useful for debugging and troubleshooting purposes.

get_token_elevation TOKEN

On systems that support Windows UAC, this command returns one of default, full or limited depending on whether the token corresponds to a process is running with default privileges for the account, full (elevated) privileges for the account or limited (filtered) privileges. On systems that do not support UAC, the command always returns default.

To directly access the elevation level of a process, you can also use the get_process_elevation command or the -elevation option of the get_process_info command.

get_token_groups TOKEN ?-name?

Returns the list of group SID's for the token. If -name is specified, returns the group names instead of the SID's.

get_token_groups_and_attrs TOKEN

Returns the list of group SID's for the token together with the attributes for each group. The returned list is of the form SID ATTRIBUTELIST SID ATTRIBUTELIST... where ATTRIBUTELIST is a list of zero or more of the following attributes: enabled, enabled_by_default, logon_id, mandatory, owner, resource, integrity, integrity_enabled and use_for_deny_only. Refer to the Windows Platform SDK for details.

get_token_impersonation_level TOKEN

Gets the current impersonation level for the token. This may have one of the following values: anonymous, identification, impersonation, or delegation. See Impersonation for details.

get_token_integrity TOKEN ?-raw | -label?

On systems that support Windows UAC, this command returns the integrity level associated with the token. The integrity value is an integer value between 0 and 65535. If the option -raw is specified, the integrity level is returned as the raw SID value as stored internally by Windows in the token. Alternatively, if the -label is specified the corresponding integrity level range label is returned which is one of untrusted (0-4095), low (4096-8191), medium (8192-12287, high (12288-16383) or system (anything higher).

On systems that do not support integrity levels, this command always returns an appropriately formatted value corresponding to the medium integrity level.

To directly access the integrity level of a process, you can also use the get_process_integrity command or the -integrity option of the get_process_info command.

get_token_integrity_policy TOKEN

On systems that support Windows UAC, this command returns the integrity policy associated with the token. The integrity policy is a list containing zero or more values from table below.

no_write_up	If present, writes to objects at a higher integrity level are denied.
new_process_min	If present, new processes will be created at an integrity level that is the minimum of the integrity level of the token and the integrity level associated with the executable file of the new process.

On systems that do not support integrity levels, this command always returns an empty list indicating no integrity policy is in effect.

get_token_linked_token TOKEN

If TOKEN is an elevated or limited token, this command returns the corresponding limited or elevated token linked to it.

get_token_owner TOKEN ?-name?

Returns the SID of the entity (user, group, etc.) that will be used as the owner for objects created using this token. If -name is specified, the name of the entity is returned instead of the SID.

get_token_primary_group TOKEN ?-name?

Returns the SID of the group that will be used as the primary group for objects created using this token. If -name is specified, the name of the group is returned instead of the SID.

get_token_privileges TOKEN ?-all?

Returns the list of enabled privileges in the token. If the option -all is specified, returns a list of two sublists. The first containing the enabled privileges and the second the disabled privileges.

get_token_privileges_and_attrs TOKEN

Returns the list of privileges in the token together with the attributes for each. The returned list is of the form PRIVILEGE ATTRIBUTELIST PRIVILEGE ATTRIBUTELIST... where ATTRIBUTELIST is a list of zero or more of the following attributes: enabled, enabled_by_default and used_for_access.

get_token_source TOKEN

Returns the source of an access token.

get_token_statistics TOKEN

Returns various token statistics as a list of field value pairs. The following fields are returned:

authluid	The LUID for the session represented by the token.
expiration	Expiration time for the token. Windows does not currently support expiration for access tokens.
dynamicavailable	Number of free bytes available for storing default protection and primary group identifier for the token.
dynamiccharged	Number of bytes allocated for storing default protection and primary group identifier for the token.
groupcount	Number of group SID's included in the token.
impersonationlevel	The impersonation level of the token. This value is only valid if the field type has the value impersonation.
luid	An LUID that identifies the instance of the token.
modificationluid	An LUID that changes every time the token is modified.
privilegecount	The number of privileges (including disabled ones) that are included in the token.
type	The type of the token - primary or impersonation.

get_token_type TOKEN

Returns the type of the token: either primary, or impersonation.

get_token_user TOKEN ?-name?

Returns the SID of the user account associated with the token. If -name is specified, returns the name of the account instead of its SID.

get_token_virtualization TOKEN

Returns true if the token indicates a virtualized process where the system redirects writes to protected file and registry locations and false otherwise. On systems that do not support UAC, the command will always return false.

To directly retrieve the virtualization status of a process, you can also use the virtualized_process command or the -virtualized option of the get_process_info command.

impersonate_namedpipe_client CHANNEL

Changes the security context of the calling thread to that of the client of a named pipe. CHANNEL is a Tcl channel identifier for the server end of a named pipe. This call will fail unless some data is first read from the channel.

The caller must be careful that exceptions raised by this command are handled correctly. It should not continue with normal processing as though the security context was changed to that of the named pipe client.

impersonate_self IMPERSONATIONLEVEL

Assigns an impersonation token to the current thread based on the security context of the process. The security characteristics of the thread can then be changed (for example by modifying the privileges of its token) without impacting the security context of the remaining threads in the process.

IMPERSONATIONLEVEL may have any of the values allowed for impersonation levels (see Impersonation).

impersonate_token TOKEN

Changes the security context of the calling thread to that of the user account associated with the specified token. TOKEN is a token returned from a command such as open_user_token, open_process_token or open_thread_token.

The caller must be careful that exceptions raised by this command are handled correctly. It should not continue with normal processing as though the security context was changed to that of the token.

impersonate_user USERNAME PASSWORD ?options?

Changes the security context of the calling thread to that of the specified user account. This is essentially a wrapper around open_user_token and impersonate_token. Refer to the documentation of open_user_token for a description of the arguments.

The caller must be careful that exceptions raised by this command are handled correctly. It should not continue with normal processing as though the security context was changed to that of the user.

is_valid_luid_syntax LUID

Returns if LUID is a syntactically valid LUID, else 0.

is_valid_sid_syntax sid

Returns true or false depending on whether sid is a valid SID or not. Note this only checks the syntax of the SID, not whether it corresponds to a real account.

map_luid_to_privilege LUID ?-system SYSTEMNAME? ?-mapunknown?

Returns the privilege name corresponding to the given LUID. If LUID does not correspond to a system defined privilege, an exception is raised unless the -mapunknown option is specified. In this case, the command will return a string of the form Privilege-LUID. As a special case, if LUID is a privilege name (and not a LUID), returns it as is. The option -system may be used to specify a system as described in Standard Options.

map_privilege_to_luid PRIVILEGE ?-system SYSTEMNAME? ?-mapunknown?

Returns the LUID corresponding to the given privilege name. If PRIVILEGE does not correspond to a system defined privilege name or a constructed privilege name of the form Privilege-LUID, an exception is raised. As a special case, if PRIVILEGE is itself a LUID, it is returned. The option -system may be used to specify a system as described in Standard Options.

new_ace ACETYPE ACCOUNT ACCESSRIGHTS ?options?

Creates and returns a new ACE. ACETYPE is the type of the ACE and should be one of supported values described in Access Control Entries. The user or group that the ACE pertains to is given by ACCOUNT which may be either a name or a SID. ACCESSRIGHTS determines the rights to be granted or denied by the ACE and should be a list of one or more constants described in Access Rights.

The following options may be specified when creating an ACE:

-self BOOLEAN	If the specified value is 1 (default), the ACE applies to the object to which it is attached. If the specified value is 0, then the created ACE does not apply to the object with which it is attached. In this case, it only applies to the descendents of that object as indicated by the other options.
-recursecontainers BOOLEAN	If the specified value is 1, the ACE is also applied to all descendents of the object to which the ACE is attached that are themselves containers. For example, in the case of a file ACE, this would indicate that the ACE also apply to all subdirectories. If 0 (default), the ACE does not apply to descendents that are containers.
-recurseobjects BOOLEAN	If the specified value is 1, the ACE is also applied to all descendents of the object to which the ACE is attached that are not themselves containers. For example, in the case of a file ACE, this would indicate that the ACE also apply to all files under all subdirectories below a directory but not to the subdirectories themselves. If 0 (default), the ACE does not apply to descendents that are not containers.
-recurseonelevelonly BOOLEAN	If the specified value is 0 (default), the -recursecontainers and -recurseobjects options have effect at all levels below the container object to which the ACE is applied. If the value is 1, the ACE is only applied to the immediate children of the container object. This option has no effect if neither -recurseobjects nor -recursecontainers is specified.

new_acl ?ACELIST?

Returns a new ACL initialized. ACELIST may be optionally specified to prepopulate the ACL with a list of ACE elements.

new_luid

Returns a LUID.

new_restricted_dacl ACCOUNTS RIGHTS

Returns a new DACL where the access rights specified by RIGHTS are granted to the accounts included in ACCOUNTS. Other accounts are implicitly denied. Accounts may be specified using either the account names or SID's. RIGHTS is a list of symbolic constants and bit masks as described in Access Rights.

new_security_descriptor ?options?

Returns a new security descriptor. The following options may be specified to initialize various fields of the security descriptor:

-owner ACCOUNT	The owner field of the security descriptor is set to the SID for the specified account. ACCOUNT may be the SID itself or the name of the user or group account.
-group ACCOUNT	The primary group field of the security descriptor is set to the SID for the specified account. ACCOUNT may be the SID itself or the name of the group.
-dacl ACL	The DACL field of the security descriptor is set to ACL. If ACL is the string "null", no DACL will be present in the security descriptor.
-sacl ACL	The SACL field of the security descriptor is set to ACL. If ACL is the string "null", no SACL will be present in the security descriptor.

new_uuid ?-localok?

Returns a UUID. If the system does not contain a network card, the operating system may return an error as it cannot guarantee uniqueness across systems. Specifying the -localok option causes this to be ignored and a identifier value to be returned anyways.

nil_uuid

Returns a nil UUID.

open_process_token ?-pid PID | -hprocess HPROCESS? ?-access DESIREDACCESS?

Returns a process token that can passed to other functions for querying and modifying security related data for a process. By default, the current process is assumed. The options -hprocess or -pid options may be used to retrieve the token for another process by passing a handle to it or its PID.

The -access option may be used to specify a list of desired access rights. If this option is not specified, access rights default to token_query. See Access Rights for a description of the format of this list and for a description of standard access rights.

In addition, the following symbols may be specified in the list: token_adjust_default, token_adjust_groups, token_adjust_privileges, token_adjust_sessionid, token_assign_primary, token_duplicate, token_execute, token_impersonate, token_query, token_query_source, token_read, token_write and token_all_access. See the documentation of OpenProcessToken in the Windows SDK for a description of each of these.

When no longer required, this token must be passed to close_token.

open_thread_token ?-tid TID | -hthread HTHREAD? ?-access DESIREDACCESS? ?-self BOOLEAN?

Returns a thread access token that can passed to other functions for querying and modifying security related data for a thread. By default, the current thread is assumed. The options -hthread or -tid options may be used to retrieve the token for another thread by passing a handle to it or its TID.

Note that the command will generate an error if the thread does not have a token. In this case, ::errorCode facility and code are set to WINDOWS and 1008 respectively. The caller can retrieve the process token instead.

The -access option specifies the desired access mode. See open_process_token for more details.

The -self option controls whether the access check is to be made against the security context of the thread or against the security context of the process. If specified as false, the security context of the thread is used, else that of the process.

When no longer required, this token must be passed to close_token.

open_user_token USERNAME PASSWORD ?options?

Returns a token corresponding to a logon session for the USERNAME account. This token may be used for impersonation or starting processes under a different account. When no longer required, this token must be passed to close_token.

USERNAME is the name of the account and may be specified either as just the account name, or in UPN format as user@DNS_domain_name.

The following options may be specified:

-domain DOMAIN	Specifies the domain for the user. This option must not be specified if USERNAME is in UPN format user@DNS_domain_name which includes a domain name. If USERNAME is not in UPN format and -domain is not specified, the account validation is done only using the local account database.
-type LOGONTYPE	Indicates the logon type. LOGONTYPE must be one of batch, interactive, network, network_cleartext, new_credentials, service or unlock. Refer to the Windows SDK documentation of LogonUser for details.
-provider PROVIDER	Selects a logon provider. PROVIDER must be one of winnt50, winnt40 or winnt35. If this option is not specified, the operating system picks the standard (version dependent) logon provider for the system. Specify winnt40 to select the NTLM provider and winnt50 (only valid for Windows 2000 and up) for the negotiate logon provider.

prepend_acl_aces ACL ACELIST

Prepends the list of ACEs in ACELIST to the entries in the given ACL. Returns the modified ACL.

reset_thread_token

Ends the current thread's impersonation state.

revert_to_self

Calling this function will restore the original security context for the process thereby ending any impersonation initiated by prior impersonation commands such as impersonate_user.

Any exceptions raised by this command will result in the process continuing to run in the impersonation context. This is dangerous from a security perspective and the caller should normally immediately exit.

sddl_to_security_descriptor SECD

Parses a SDDL string and returns the corresponding security descriptor.

security_descriptor_to_sddl SECD

Returns the specified security descriptor in SDDL string format.

set_ace_inheritance ACE ?options?

Returns a new ACE constructed from ACE with inheritance attributes defined by options. These may be one or more of -self, -recursecontainers, -recurseobjects and -recurseonelevelonly as described in the documentation for new_ace.

set_ace_rights ACE ACCESSRIGHTS

Returns a new ACE containing the access rights specified in ACCESSRIGHTS. This should be a list of symbolic constants and bit masks as described in Access Rights.

set_ace_sid ACE ACCOUNT

Returns a new ACE constructed from ACE but with its SID field set to be the SID for account ACCOUNT. ACCOUNT may be either the name or the SID of a user or group account.

set_ace_type ACE ACETYPE

Returns a new ACE constructed from ACE but with the type ACETYPE. See Access Control Entries for valid values of ACETYPE.

set_acl_aces ACL ACELIST

Sets the list of ACEs within an ACL to those given in ACELIST. Returns the modified ACL.

set_resource_integrity RESTYPE NAME INTEGRITYLEVEL INTEGRITYPOLICY ?options?

Sets the integrity level associated with a resource. See set_security_descriptor_integrity for a description of the INTEGRITYLEVEL and INTEGRITYPOLICY parameters and the options -recurseobjects and -recursecontainers. See set_resource_security_descriptor for description of RESTYPE, NAME and the -handle option.

set_resource_security_descriptor RESTYPE NAME SECD ?options?

Modifies the security descriptor attached to a operating system resource. RESTYPE specifies the resource type and if option -handle is not specified, must be one of file, service (Windows service), printer, registry, share (Network shares) or kernelobj (kernel objects such as mutexes, semaphores and events). If option -handle is specified, then RESTYPE may also be one of windowstation, directoryservice, directoryserviceall, providerdefined, wmiguid or registrywow6432key but must not be share.

NAME specifies the name of the resource, for example, the path of a file unless option -handle is specified in which case it is the handle to the resource.

The fields of the resource's security descriptor are modified based on the contents of SECD. At lease one of the options -all, -owner, -group, -dacl, -sacl or -mandatory_label must be specified. The specific fields modified depend on the options specified:

-all	All fields in the security descriptor are modified. This requires the caller to have the SeSecurityPrivilege privilege enabled.
-owner	The resource's owner is modified.
-group	The resource's group is modified.
-dacl	Changes the DACL attached to the resource.
-sacl	Changes the SACL attached to the resource. This requires the caller to have the SeSecurityPrivilege privilege enabled.
-protect_dacl	If this option is specified, the resource will not inherit any DACL's from its parent. Otherwise, the parent's DACL's flow down to the resource. This option only has effect if the -dacl option is specified. This option cannot be specified with -unprotect_dacl. If neither is specified, the current DACL inherit settings are preserved.
-protect_sacl	If this option is specified, the resource will not inherit any SACL's from its parent. Otherwise, the parent's SACL's flow down to the resource. This option only has effect if the -sacl option is specified. This option cannot be specified with -unprotect_sacl. If neither is specified, the current SACL inherit settings are preserved.
-unprotect_dacl	If this option is specified, the resource will inherit any DACL's from its parent. This option only has effect if the -dacl option is specified. This option cannot be specified with -protect_dacl. If neither is specified, the current DACL inherit settings are preserved.
-unprotect_sacl	If this option is specified, the resource will inherit any SACL's from its parent. This option only has effect if the -sacl option is specified. This option cannot be specified with -protect_sacl. If neither is specified, the current SACL inherit settings are preserved.

set_security_descriptor_dacl SECD ACL

Returns a security descriptor identical to SECD except for the DACL field which is set to ACL. If ACL is the string "null", the security descriptor is set to have no DACL. If ACL is an empty list, the security descriptor has an empty DACL, which is not the same not having a DACL.

set_security_descriptor_group SECD ACCOUNT

Returns a security descriptor identical to SECD except for the group field which is set to the SID for account ACCOUNT. ACCOUNT may be the SID itself or the name of the group.

set_security_descriptor_integrity SECD INTEGRITYLEVEL INTEGRITYPOLICY ?options?

Returns a new security descriptor based on SECD with the specified integrity. INTEGRITYLEVEL may be specified in one of the forms described in get_resource_integrity. INTEGRITYPOLICY is a list of one or more of the following: system_mandatory_label_no_write_up, system_mandatory_label_no_read_up, system_mandatory_label_no_execute_up. These control the operations allowed on the resource by processes with lower integrity levels. Refer to the Windows SDK for more details.

The following options may also be specified with the command:

-recursecontainers BOOLEAN	If the specified value is 1, the integrity is also applied to all descendents of the object to which the security descriptor is attached that are themselves containers. If 0 (default), the integrity is not inherited by descendents that are containers.
-recurseobjects BOOLEAN	If the specified value is 1, the integrity is also applied to all descendents of the object to which the security descriptor is attached that are not themselves containers. If 0 (default), the integrity does not apply to descendents that are not containers.

set_security_descriptor_owner SECD ACCOUNT

Returns a security descriptor identical to SECD except for the owner field which is set to the SID for account ACCOUNT. ACCOUNT may be the SID itself or the name of the user or group.

set_security_descriptor_sacl SECD ACL

Returns a security descriptor identical to SECD except for the SACL field which is set to ACL. If ACL is the string "null", the security descriptor is set to have no SACL.

set_thread_token TOKEN

Changes the security context of the current thread by associating it with the given token. This is generally used in combination with open_thread_token to implement an impersonation stack.

set_token_integrity TOKEN INTEGRITYLEVEL

On systems that support Windows UAC, this command sets the integrity level for a token. INTEGRITYLEVEL must be an integer value between 0 and 65535, a a SID value defined for a integrity level by Windows, or one of untrusted (0), low (4096), medium (8192, high (12288) or system.

On systems that do not support integrity levels, this command will raise an error unless the integrity level specified corresponds to medium integrity 8192, medium or S-1-16-8192. To directly set the integrity level of a process, you can also set_process_integrity command.

set_token_integrity_policy TOKEN ?no_write_up? ?new_process_min?

On systems that support Windows UAC, this command sets the integrity policy associated with the token. See get_token_integrity_policy for the meaning of no_write_up and new_process_min.

set_token_virtualization TOKEN ENABLE

Enables or disables virtualization of file and registry accesses depending on the boolean value of ENABLE. If this call is made on a system that does not support UAC, ENABLE must be false else an exception will be generated. The token must have been opened with token_adjust_default access.

sort_aces ACELIST

Although not enforced by the operating system, Windows has a recommended order in which multiple ACEs should be applied. The sort_aces command takes a list of ACE elements and returns a list that has been sorted as per the Windows recommendation. This sort order places all inherited ACEs after all non-inherited ACEs. Within each group, deny ACEs are placed before allow ACEs.

sort_acl_aces ACL

Rearranges the ACEs in the given ACL to conform to the Windows recommended order. Returns the modified ACL.

Security and access control

SYNOPSIS

DESCRIPTION

Unique Identifiers