Commands related to authentication and access control
|append_acl_aces ACL ACELIST|
|check_enabled_privileges PRIVILEGES ?-any?|
|disable_token_privileges token PRIVLIST|
|enable_token_privileges token PRIVLIST|
|eval_with_privileges SCRIPT PRIVLIST|
|get_ace_rights ACE ?-type RESOURCETYPE? ?-raw?|
|get_ace_text ACE ?-resourcetype RESOURCETYPE?|
|get_logon_session_info SESSIONLUID ?options?|
|get_resource_security_descriptor RESTYPE NAME ?options?|
|get_security_descriptor_text SECD ?-resourcetype RESOURCETYPE?|
|get_token_groups token ?-name?|
|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?|
|map_luid_to_privilege LUID ?-system SYSTEMNAME? ?-mapunknown?|
|map_privilege_to_luid PRIVILEGE ?-system SYSTEMNAME? ?-mapunknown?|
|new_ace ACETYPE ACCOUNT ACCESSRIGHTS ?options?|
|open_process_token ?-pid PID? ?-access DESIREDACCESS?|
|open_thread_token ?-tid TID? ?-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_security_descriptor RESTYPE NAME SECD ?options?|
|set_security_descriptor_dacl SECD ACL|
|set_security_descriptor_group SECD ACCOUNT|
|set_security_descriptor_owner SECD ACCOUNT|
|set_security_descriptor_sacl SECD ACL|
This module provides procedures related to access control in Windows operating systems.
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.
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.
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.
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.
|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. 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.
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 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.
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||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. 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.|
|-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.|
|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.|
|-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.|
|-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.|
Copyright © 2003-2009, Ashok P. Nadkarni