Commands related to authentication and access control
|append_acl_aces ACL ACELIST|
|check_enabled_privileges TOKEN PRIVILEGES ?-any?|
|disable_token_privileges TOKEN PRIVLIST|
|enable_token_privileges TOKEN PRIVLIST|
|equal_sids SIDA SIDB|
|eval_with_privileges SCRIPT PRIVLIST|
|get_ace_rights ACE ?-resourcetype RESOURCETYPE? ?-raw?|
|get_ace_text ACE ?-resourcetype RESOURCETYPE?|
|get_logon_session_info SESSIONLUID ?options?|
|get_resource_integrity RESTYPE NAME ?options?|
|get_resource_security_descriptor RESTYPE NAME ?options?|
|get_security_descriptor_integrity SECD ?-label|-raw?|
|get_security_descriptor_text SECD ?-resourcetype RESOURCETYPE?|
|get_token_groups TOKEN ?-name?|
|get_token_info TOKEN ?options?|
|get_token_integrity TOKEN ?-raw | -label?|
|get_token_owner TOKEN ?-name?|
|get_token_primary_group TOKEN ?-name?|
|get_token_privileges TOKEN ?-all?|
|get_token_user TOKEN ?-name?|
|impersonate_user USERNAME PASSWORD ?options?|
|is_well_known_sid SID KNOWNSIDNAME|
|map_luid_to_privilege LUID ?-system SYSTEMNAME? ?-mapunknown?|
|map_privilege_to_luid PRIVILEGE ?-system SYSTEMNAME? ?-mapunknown?|
|new_ace ACETYPE ACCOUNT ACCESSRIGHTS ?options?|
|new_restricted_dacl ACCOUNTS RIGHTS ?options?|
|open_process_token ?-pid PID | -hprocess HPROCESS? ?-access DESIREDACCESS?|
|open_thread_token ?-tid TID | -hthread HTHREAD? ?-access DESIREDACCESS? ?-self BOOLEAN?|
|open_user_token USERNAME PASSWORD ?options?|
|prepend_acl_aces ACL ACELIST|
|set_ace_inheritance ACE ?options?|
|set_ace_rights ACE ACCESSRIGHTS|
|set_ace_sid ACE ACCOUNT|
|set_ace_type ACE ACETYPE|
|set_acl_aces ACL ACELIST|
|set_resource_integrity RESTYPE NAME INTEGRITYLEVEL INTEGRITYPOLICY ?options?|
|set_resource_security_descriptor RESTYPE NAME SECD ?options?|
|set_security_descriptor_dacl SECD ACL|
|set_security_descriptor_group SECD ACCOUNT|
|set_security_descriptor_integrity SECD INTEGRITYLEVEL INTEGRITYPOLICY ?options?|
|set_security_descriptor_owner SECD ACCOUNT|
|set_security_descriptor_sacl SECD ACL|
|set_token_integrity TOKEN INTEGRITYLEVEL|
|set_token_integrity_policy TOKEN ?no_write_up? ?new_process_min?|
|set_token_virtualization TOKEN ENABLE|
|sids_from_same_domain SIDA SIDB|
|well_known_sid KNOWNSIDNAME ?-domainsid DOMAINSID?|
This module provides procedures related to security and access control in Windows operating systems.
This documentation is reference material that assumes familiarity with Windows security terms and concepts. For more introductory material and guide, see the Windows Security chapter in the Tcl on Windows online book.
Each trustee (user, group, logon session etc.) is identified by a security identifier (SID). equal_sids compares two SIDs for equality while sids_from_same_domain checks if two SIDs belong to the same domain. well_known_sid returns well known SIDs as defined by Microsoft and is_well_known_sid checks if a given SID is one of these well known SIDs. get_sid_domain returns the SID of the domain containing a specified SID.
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. Unique means it will not be generated by some other call to that command.
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 command get_token_info retrieves information from a token. Individual pieces of the token can also be retrieved via commands get_token_user, get_token_default_dacl, get_token_origin, get_token_groups, get_token_primary_group, get_token_owner, get_token_tssession, get_token_groups_and_attrs and get_token_restricted_groups_and_attrs.
The commands get_token_privileges, check_enabled_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.
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, set_thread_token and revert_to_self. For impersonating named pipe clients, use the impersonate_namedpipe_client command from the twapi_namedpipe package.
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 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.
|COM||com_rights_execute, com_rights_execute_local, com_rights_execute_remote, com_rights_activate_local, com_rights_activate_remote|
|Desktops||desktop_readobjects, desktop_createwindow, desktop_createmenu, desktop_hookcontrol, desktop_journalrecord, desktop_journalplayback, desktop_enumerate, desktop_writeobjects, desktop_switchdesktop|
|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|
|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|
|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.
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.
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.
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.
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 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. Commands encode_security_descriptor and decode_security_descriptor encode and decode security descriptors to and from self-relative binary formats. This is useful in cases where security descriptors need to be stored in that format, for example in the registry.
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.
The Windows credentials manager maintains a cache of credentials for a user account or logon session. The twapi_security package provides some additional commands to those already present in the twapi_base package.
The credentials returns a list of credentials for the calling process.
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 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.
|comment||Any associated descriptive comment for the credential that might be added by the user.|
|lastwritten||The last time the credentials were written as the number of 100ns since Jan 1, 1601 (see large_system_time_to_secs_since_1970).|
|persist||One of the values session, local_machine or enterprise depending on whether the credentials are persisted for the current logon session only, or are persisted on the local system and are visible to future logon session for the user on that system, or are persisted on the local system and are visible to logon session for that user from other systems.|
|target||The name of the target for which the credential is applicable.|
|targetalias||An alias for the target.|
|type||The credential type which is one of generic, domain_password, domain_certificate, domain_visible_password generic_certificate, domain_extended.|
|username||The user name associated with the target credential.|
|-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.|
|-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.|
|-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.|
|-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.|
|-logontime||Returns the time session owner logged on.|
|-type||Returns the logon session type (see find_logon_sessions).|
|-usersid||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.|
|-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.|
|-disabledprivileges||Returns the list of privileges in the token that are currently disabled.|
|-elevation||Returns the elevation level for the token (see get_process_elevation).|
|-enabledprivileges||Returns the list of privileges that are enabled in the token.|
|-groupattrs||Returns a dictionary whose keys are group SID's contained in the token, with the corresponding value being a list of attributes for the group.|
|-groups||Returns the list of groups included in the token. For domain accounts, an error is raised if the domain is unreachable. Use -groupattrs to avoid this.|
|-integrity||Returns the numeric integrity level associated with the token (see get_process_integrity).|
|-integritylabel||Returns the label for the range for the integrity level associated with the token (see get_process_integrity).|
|-linkedtoken||If TOKEN is an elevated or limited token, this command returns the corresponding limited or elevated token linked to it.|
|-logonsession||Returns the LUID of the logon session associated with the token.|
|-logonsessionsid||Returns the SID of the logon session associated with the token.|
|-primarygroup||Returns the primary group for the token. For domain accounts, an error is raised if the domain is unreachable. Use -primarygroupsid to avoid this.|
|-primarygroupsid||Returns the SID of primary group for the token.|
|-privileges||Returns the list of enabled and disabled process privileges in the same format as get_token_privileges. Deprecated, use -enabledprivileges and -disabledprivileges instead.|
|-restrictedgroupattrs||Returns a dictionary whose keys are SID's for the restricted groups contained in the token, with the corresponding value being a list of attributes for the group. See get_token_groups_and_attrs for details.|
|-restrictedgroups||Returns the list of restricted groups in the token. For domain accounts, an error is raised if the domain is unreachable. Use -restrictedgroupattrs to avoid this.|
|-tssession||Returns the terminal server session id of the process.|
|-usersid||Returns the SID of the user account associated with the token.|
|-virtualized||Returns true if the process associated with the token is virtualized and false otherwise. See virtualized_process.|
|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.|
|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.|
|-auditsuccess BOOLEAN||Specified that the ACE should log permitted accesses to a resource. Ignored if the ACE type is not audit. Defaults to true.|
|-auditfailure BOOLEAN||Specified that the ACE should log failed accesses to a resource. Ignored if the ACE type is not audit. Defaults to true.|
|-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.|
|-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.|
|-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.|
|-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.|
|-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.|
|-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.|
Copyright © 2003-2010, Ashok P. Nadkarni