Security(n) "Security functions"

NAME

Security - Functions related to authentication and access control

SYNOPSIS

package require twapi

lookup_account_name name ?options?
lookup_account_sid sid ?options?
is_valid_sid_syntax sid
map_account_to_sid ACCOUNT ?-system SYSTEMNAME?
map_account_to_name ACCOUNT ?-system SYSTEMNAME?
get_user_account_info ACCOUNT ?-system SYSTEMNAME? ?options?
set_user_account_info account ?-system SYSTEMNAME? ?options?
set_user_name USERNAME NEWNAME ?-system SYSTEMNAME?
set_user_password USERNAME PASSWORD ?-system SYSTEMNAME?
set_user_home_dir USERNAME PATH ?-system SYSTEMNAME?
set_user_comment USERNAME STRING ?-system SYSTEMNAME?
set_user_script_path USERNAME PATH ?-system SYSTEMNAME?
set_user_full_name USERNAME STRING ?-system SYSTEMNAME?
set_user_country_code USERNAME INTEGER ?-system SYSTEMNAME?
set_user_profile USERNAME PATH ?-system SYSTEMNAME?
set_user_home_dir_drive USERNAME DRIVEPATH ?-system SYSTEMNAME?
set_user_priv_level USERNAME PRIVLEVEL ?-system SYSTEMNAME?
set_user_expiration USERNAME DATETIME ?-system SYSTEMNAME?
get_users ?-system SYSTEMNAME?
new_user USERNAME ?options?
delete_user USERNAME ?-system SYSTEMNAME?
unlock_user USERNAME ?-system SYSTEMNAME?
enable_user USERNAME ?-system SYSTEMNAME?
disable_user USERNAME ?-system SYSTEMNAME?
get_global_groups ?-system SYSTEMNAME?
get_local_groups ?-system SYSTEMNAME?
new_global_group GROUPNAME ?-system SYSTEMNAME? ?-comment COMMENT?
new_local_group GROUPNAME ?-system SYSTEMNAME? ?-comment COMMENT?
delete_global_group GROUPNAME ?-system SYSTEMNAME?
delete_local_group GROUPNAME ?-system SYSTEMNAME?
get_global_group_members GROUPNAME ?-system SYSTEMNAME?
get_local_group_members GROUPNAME ?-system SYSTEMNAME?
add_user_to_global_group GROUPNAME USERNAME ?-system SYSTEMNAME?
add_member_to_local_group GROUPNAME ACCOUNTNAME ?-system SYSTEMNAME?
remove_user_from_global_group GROUPNAME USERNAME ?-system SYSTEMNAME?
remove_member_from_local_group GROUPNAME ACCOUNTNAME ?-system SYSTEMNAME?
open_process_token pid access
open_thread_token tid access
open_user_token USERNAME PASSWORD ?options?
close_token token
get_token_user token ?-name?
get_token_groups token ?-name?
get_token_groups_and_attrs token
get_token_privileges token ?-all?
check_enabled_privileges PRIVILEGES ?-any?
get_token_privileges_and_attrs token
enable_token_privileges token PRIVLIST
disable_token_privileges token PRIVLIST
disable_all_token_privileges token
get_token_owner token ?-name?
get_token_primary_group token ?-name?
get_token_source token
get_token_type token
get_token_impersonation_level token
get_token_statistics token
map_luid_to_privilege LUID ?-system SYSTEMNAME? ?-mapunknown?
map_privilege_to_luid PRIVILEGE ?-system SYSTEMNAME? ?-mapunknown?
is_valid_luid_syntax LUID
new_ace ACETYPE ACCOUNT ACCESSRIGHTS ?options?
get_ace_type ACE
set_ace_type ACE ACETYPE
get_ace_sid ACE
set_ace_sid ACE ACCOUNT
get_ace_rights ACE
set_ace_rights ACE ACCESSRIGHTS
get_ace_inheritance ACE
set_ace_inheritance ACE ?options?
sort_aces ACELIST
new_acl ?ACELIST?
get_acl_rev ACL
get_acl_aces ACL
set_acl_aces ACL ACELIST
prepend_acl_aces ACL ACELIST
append_acl_aces ACL ACELIST
sort_acl_aces ACL
new_security_descriptor ?options?
get_security_descriptor_owner SECURITY_DESCRIPTOR
get_security_descriptor_owner SECURITY_DESCRIPTOR ACCOUNT
get_security_descriptor_group SECURITY_DESCRIPTOR
get_security_descriptor_group SECURITY_DESCRIPTOR ACCOUNT
get_security_descriptor_dacl SECURITY_DESCRIPTOR
get_security_descriptor_dacl SECURITY_DESCRIPTOR ACL
get_security_descriptor_sacl SECURITY_DESCRIPTOR
get_security_descriptor_sacl SECURITY_DESCRIPTOR ACL
get_resource_security_descriptor RESTYPE NAME ?options?
set_resource_security_descriptor RESTYPE NAME SECURITY_DESCRIPTOR ?options?
impersonate_token TOKEN
impersonate_user USERNAME PASSWORD ?options?
revert_to_self
impersonate_self IMPERSONATIONLEVEL
set_thread_token TOKEN
reset_thread_token
new_luid
new_uuid ?-localok?
nil_uuid

DESCRIPTION

This package provides procedures related to authentication and access control in Windows operating systems.

Standard Options

Most commands allow the following options to be specified:

-system SYSTEMNAME
Several commands, for example, looking up account names or adding users, may be carried out on a target system other than the local system. The -system option allows specification of the target system. This option defaults to the local system if unspecified.

Unique Identifiers

A Locally Unique Identifier 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 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.

User and Group Accounts

The command lookup_account_name, map_account_to_name, lookup_account_sid and map_account_to_sid translate between user and group account names and their SID's. The command is_valid_sid_syntax validates the syntax of an SID.

The commands get_users, get_global_groups and get_local_groups may be used to enumerate users and groups on a system.

The commands new_user and delete_user allow addition and deletion of user accounts. The commands enable_user, disable_user and unlock_user may be used to change the state of a user account. The command get_user_account_info returns various attributes and properties of a user account. These may be modified through the set_user_account_info function or alternatively, modified individually through the following set of functions: set_user_name, set_user_password, set_user_home_dir, set_user_comment, set_user_script_path, set_user_full_name, set_user_country_code, set_user_profile, set_user_home_dir_drive, set_user_priv_level, set_user_expiration.

The commands new_global_group and delete_global_group allow creation and deletion of global groups. The equivalent commands for local groups are new_local_group and delete_local_group. Users may be added and removed using the commands add_user_to_global_group, add_member_to_local_group, remove_user_from_global and remove_member_from_local_group. The commands get_local_group_members and get_global_group_members allow enumeration of the members of a group.

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.

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, set_thread_token and revert_to_self.

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. This value is not valid for Windows NT 4.0.

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 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, specific object types may have other access rights associated with them as described below.

File object-specific access rights are 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, and file_write_attributes.

Named pipe object-specific rights are file_all_access, file_read_data, file_write_data, file_create_pipe_instance, file_read_attributes and file_write_attributes.

Windows service-specific access rights are service_all_access, service_query_config, service_change_config, service_query_status, service_enumerate_dependents, service_start, service_stop, service_pause_continue, service_interrogate and service_user_defined_control.

registry-specific access rights are 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 and key_wow64_res.

Process-specific access rights are 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 and process_suspend_resume.

Thread-specific access rights are 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 and thread_direct_impersonation.

Token-specific access rights are token_all_access, token_assign_primary, token_duplicate, token_impersonate, token_query, token_query_source, token_adjust_privileges, token_adjust_groups, token_adjust_default and token_adjust_sessionid.

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. 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 rights (see 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.

Access Control List

An access control list (ACL) is an ordered list of access control entries (see Access Control Entries) that is applied to a resource. The command new_acl creates a new ACL with an optional set of ACE elements.

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.

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.

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.

Commands

lookup_account_name name ?options?
name specifies the name of the account and may be fully qualified in the form domain ame.

If no options are specified, this command returns the SID for the account. If one or more options are specified, returns a flat list of the form "option1 value1 ...". The following options may be specified:

-all
Returns all values.

-sid
Returns the SID for the account.

-domain
Returns the domain in which the account was found.

-system
Specifies the name of the system on which the account is to be looked up. If unspecified, the local system is used.

-type
Returns the account type. This may be one of user, group, domain, alias, wellknowngroup, deletedaccount, invalid, unknown, or computer.


lookup_account_sid sid ?options?
Argument sid specifies the SID of the account. If no options are specified, this command returns the name for the account. If one or more options are specified, the command returns a flat list of the form "option1 value1 ...". The following options may be specified:

-all
Returns all values.

-name
Returns the SID for the account.

-domain
Returns the domain in which the account was found.

-system
Specifies the name of the system on which the account is to be looked up. If unspecified, the local system is used.

-type
Returns the account type. This may be one of user, group, domain, alias, wellknowngroup, deletedaccount, invalid, unknown, or computer.


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_account_to_sid ACCOUNT ?-system SYSTEMNAME?
Returns the SID corresponding to an account. If ACCOUNT is a SID, it is returned as is. Otherwise, it is assumed to be an account name and the corresponding SID is returned. An exception is raised if neither of these is true. The option -system may be used to specify a system as described in Standard Options.

map_account_to_name ACCOUNT ?-system SYSTEMNAME?
Returns the name for an account. If ACCOUNT is a valid account name, it is returned as is. Otherwise, it is assumed to be a SID and the corresponding account name is returned. An exception is raised if neither of these is true. The option -system may be used to specify a system as described in Standard Options.

get_user_account_info ACCOUNT ?-system SYSTEMNAME? ?options?
Returns attributes and properties of a user account as a list of the form "option1 value1 ...". ACCOUNT specifies the user account for which the information is to be retrieved. The option -system may be used to specify the system from whose context the account lookup should be performed.

The data returned depends on which of the following options are specified:

-all
Returns all data items.

-comment
Returns the comment associated with the user account.

-password_expired
Returns a value of 1 if the account password has expired, and 0 otherwise.

-full_name
Returns the full name of the user.

-parms
Returns an application specific string.

-units_per_week
Returns an integer indicating the number of equal time units into which a week is divided (see -logon_hours).

-primary_group_id
Returns the the RID (relative id component of a SID) of the primary global group for the account.

-global_groups
Returns the global groups of which the account is a member.

-local_groups
Returns the local groups of which the account is a member. This includes indirect membership through a global group which is itself a member of a local group.

-status
Returns one of the values disabled, enabled or locked.

-logon_server
Returns the name of the server to which logon requests are sent.

-country_code
Returns an integer country/region value for the user's preferred language.

-home_dir
Returns the full path to the user's home directory.

-password_age
Returns the number of seconds since the password was last changed for the account.

-home_dir_drive
Returns the drive letter assigned to the user's home directory.

-num_logons
Returns the number of times the user has logged on. In an environment with backup domain controllers, each domain controller maintains this value independently and must be queried (using the -system option) separately. A value of -1 indicates the number is unknown.

-acct_expires
Returns the time in GMT when the account is set to expire. This value may also be never or unknown.

-last_logon
Returns the time in GMT when the user last logged in. This value may also be never or unknown. In an environment with backup domain controllers, each domain controller maintains this value independently and must be queried separately (using the -system option).

-last_logoff
Returns the time in GMT when the user last logged off. This value may also be never or unknown. In an environment with backup domain controllers, each domain controller maintains this value independently and must be queried separately (using the -system option).

-user_id
Returns RID component of the user's SID.

-usr_comment
Returns the user comment for the account.

-bad_pw_count
Returns the number of login attempts for that account that failed because of a bad password. In an environment with backup domain controllers, each domain controller maintains this value independently and must be queried separately (using the -system option).

-code_page
Returns an integer corresponding to the code page for the user's preferred language.

-logon_hours
Returns a bit string of 1's and 0's corresponding to each hour in the week that the user is allowed to log on. Note the week starts based on GMT time, not local time.

-workstations
Returns a comma-separated list of upto eight workstations from which the user can log in.

-name
Returns the name of the account.

-script_path
Returns the full path to the user's logon script.

-priv
Returns one of the values admin, user or guest corresponding to the privilege level for the account.

-profile
Returns the full path to the user's profile.

-max_storage
Returns the maximum amount of disk space the user is allowed to use.


set_user_account_info account ?-system SYSTEMNAME? ?options?
Sets attributes and properties of a user account. account specifies the user account for which the information is to be retrieved. The option -system may be used to specify the system from whose context the account lookup should be performed. The following options may be specified to set various properties of the account:

-comment STRING
Sets the comment associated with the account.

-full_name STRING
Sets the field containing the full name of the user.

-country_code INTEGER
Sets the country code associated with the user account.

-home_dir PATH
Sets the account's home directory path.

-home_dir_drive
Sets the account's home directory drive.

-acct_expires DATETIME
Sets the time at which the account will expire. DATETIME may be specified in any format accepted by the clock scan command, or may be the string never to indicate that the account should never expire.

-name STRING
Sets the name field containing the name of the account.

-script_path PATH
Sets the path to the logon script for the account.

-priv PRIVLEVEL
Sets the privilege level for the account. PRIVLEVEL should be one of the values admin, user or guest.

-profile PATH
Sets the path to the account's profile.


set_user_name USERNAME NEWNAME ?-system SYSTEMNAME?
Modifies the name of the specified user account to NEWNAME. The option -system may be used to specify a system as described in Standard Options.

set_user_password USERNAME PASSWORD ?-system SYSTEMNAME?
Sets the password of the specified user account to PASSWORD. The option -system may be used to specify a system as described in Standard Options.

set_user_home_dir USERNAME PATH ?-system SYSTEMNAME?
Sets the home directory for the specified user account to PATH. The option -system may be used to specify a system as described in Standard Options.

set_user_comment USERNAME STRING ?-system SYSTEMNAME?
Sets the comment associated with the specified user account to STRING The option -system may be used to specify a system as described in Standard Options.

set_user_script_path USERNAME PATH ?-system SYSTEMNAME?
Sets the path to the login script for the specified user account. The option -system may be used to specify a system as described in Standard Options.

set_user_full_name USERNAME STRING ?-system SYSTEMNAME?
Sets the full name for the specified user to STRING. The option -system may be used to specify a system as described in Standard Options.

set_user_country_code USERNAME INTEGER ?-system SYSTEMNAME?
Sets the country code for the specified user account. The option -system may be used to specify a system as described in Standard Options.

set_user_profile USERNAME PATH ?-system SYSTEMNAME?
Sets the location of the profile of the specified user account to PATH. The option -system may be used to specify a system as described in Standard Options.

set_user_home_dir_drive USERNAME DRIVEPATH ?-system SYSTEMNAME?
Sets the home directory drive for the specified user account. The option -system may be used to specify a system as described in Standard Options.

set_user_priv_level USERNAME PRIVLEVEL ?-system SYSTEMNAME?
Sets the privilege level of the specified user account to PRIVLEVEL. PRIVLEVEL should be one of the values admin, user or guest. The option -system may be used to specify a system as described in Standard Options.

set_user_expiration USERNAME DATETIME ?-system SYSTEMNAME?
Sets the time at which the specified user account expires. DATETIME may be specified in any format accepted by the clock scan command, or may be the string never to indicate that the account should never expire. The option -system may be used to specify a system as described in Standard Options.

get_users ?-system SYSTEMNAME?
Returns the list of user accounts on the system. See Standard Options for description of the -system option.

new_user USERNAME ?options?
Creates a new user account. The following options may be specified to set the account properties:

-system SYSTEMNAME
Indicates the system on which to create the account.

-comment STRING
Sets the comment associated with the account.

-home_dir PATH
Sets the account's home directory path.

-script_path PATH
Sets the path to the logon script for the account.

-priv PRIVLEVEL
Sets the privilege level for the account. PRIVLEVEL should be one of the values admin, user or guest. If unspecified, this defaults to user.

-password STRING
Sets the password for the account.


delete_user USERNAME ?-system SYSTEMNAME?
Delete the specified user account. The option -system may be used to specify a system as described in Standard Options.

unlock_user USERNAME ?-system SYSTEMNAME?
Unlocks a user account that has been locked out. The option -system may be used to specify a system as described in Standard Options.

enable_user USERNAME ?-system SYSTEMNAME?
Enables a user account. The option -system may be used to specify a system as described in Standard Options.

disable_user USERNAME ?-system SYSTEMNAME?
Disables a user account. The option -system may be used to specify a system as described in Standard Options.

get_global_groups ?-system SYSTEMNAME?
Returns the list of global groups on the system. See Standard Options for description of the -system option.

get_local_groups ?-system SYSTEMNAME?
Returns the list of local groups on the system. See Standard Options for description of the -system option.

new_global_group GROUPNAME ?-system SYSTEMNAME? ?-comment COMMENT?
Creates a global group GROUPNAME. If specified, the option -comment allows a comment to be associated with the group. The option -system may be used to specify a system as described in Standard Options.

new_local_group GROUPNAME ?-system SYSTEMNAME? ?-comment COMMENT?
Creates a local group GROUPNAME. If specified, the option -comment allows a comment to be associated with the group. The option -system may be used to specify a system as described in Standard Options.

delete_global_group GROUPNAME ?-system SYSTEMNAME?
Deletes a global group GROUPNAME. The option -system may be used to specify a system as described in Standard Options.

delete_local_group GROUPNAME ?-system SYSTEMNAME?
Deletes a local group GROUPNAME. The option -system may be used to specify a system as described in Standard Options.

get_global_group_members GROUPNAME ?-system SYSTEMNAME?
Returns a list of user accounts that are members of the global group GROUPNAME. The option -system may be used to specify a system as described in Standard Options.

get_local_group_members GROUPNAME ?-system SYSTEMNAME?
Returns a list of user accounts that are members of the local group GROUPNAME. The option -system may be used to specify a system as described in Standard Options.

add_user_to_global_group GROUPNAME USERNAME ?-system SYSTEMNAME?
Adds the user account specified by USERNAME to the global group GROUPNAME. The option -system may be used to specify a system as described in Standard Options.

add_member_to_local_group GROUPNAME ACCOUNTNAME ?-system SYSTEMNAME?
Adds the account specified by ACCOUNTNAME to the local group GROUPNAME. ACCOUNTNAME may be either a user name or a global group and may include a domain in the form domainname\username.

The option -system may be used to specify a system as described in Standard Options.

remove_user_from_global_group GROUPNAME USERNAME ?-system SYSTEMNAME?
Removes the user account specified by USERNAME from the global group GROUPNAME. The option -system may be used to specify a system as described in Standard Options.

remove_member_from_local_group GROUPNAME ACCOUNTNAME ?-system SYSTEMNAME?
Removes the user account or global group specified by ACCOUNTNAME from the local group GROUPNAME. ACCOUNTNAME may be a domain account in the form domainname\username.

The option -system may be used to specify a system as described in Standard Options.

open_process_token pid access
Returns a process token that can passed to other functions for querying and modifying security related data for the process with id pid. When no longer required, this token must be passed to close_token. The access argument specifies a list of access rights. 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 for a description of each of these.

open_thread_token tid access
Returns a thread access token that can passed to other functions for querying and modifying security related data for the thread with id pid. When no longer required, this token must be passed to close_token.

The access argument is an integer bit mask that specifies the desired access mode. See the documentation for open_process_token for more details.

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.


close_token token
Frees resources associated with an access token.

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_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, and use_for_deny_only. Refer to the Windows Platform SDK for details.

get_token_privileges token ?-all?
Returns the list of enabled privileges in the token. If the option -all is specified, all privileges in the token are returned including the ones that are not enabled.

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.

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.

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 the privilege does not exist or cannot be enabled because of lack of rights to the token handle.

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.

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.

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_source token
Returns the source of an access token.

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

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.

get_token_statistics token
Returns various token statistics, including expiration, memory usage etc.

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.

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

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, 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. By default, this option has the value 1.

-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 a directory. If 0 (default), the ACE does not apply to descendents that are not containers.

-recurseonelevelonly BOOLEAN
If the specified value is 0, 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.


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

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.

get_ace_sid ACE
Returns the SID of the given ACE.

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.

get_ace_rights ACE
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.

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.

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.

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.

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.

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

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_acl_aces ACL
Returns the ordered list of ACE elements in the given ACL.

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

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

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

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

new_security_descriptor ?options?
Returns a new security descriptor (see Security Descriptors). 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 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 null, no SACL will be present in the security descriptor.


get_security_descriptor_owner SECURITY_DESCRIPTOR
Returns the owner SID for the given security descriptor.

get_security_descriptor_owner SECURITY_DESCRIPTOR ACCOUNT
Returns a security descriptor identical to SECURITY_DESCRIPTOR 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.

get_security_descriptor_group SECURITY_DESCRIPTOR
Returns the group SID for the given security descriptor.

get_security_descriptor_group SECURITY_DESCRIPTOR ACCOUNT
Returns a security descriptor identical to SECURITY_DESCRIPTOR 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.

get_security_descriptor_dacl SECURITY_DESCRIPTOR
Returns the DACL contained in the given security descriptor.

get_security_descriptor_dacl SECURITY_DESCRIPTOR ACL
Returns a security descriptor identical to SECURITY_DESCRIPTOR except for the DACL field which is set to ACL. If ACL is null, the security descriptor is set to have no DACL.

get_security_descriptor_sacl SECURITY_DESCRIPTOR
Returns the SACL contained in the given security descriptor.

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

get_resource_security_descriptor RESTYPE NAME ?options?
Retrieves the security descriptor attached to a operating system resource. RESTYPE specifies the resource type and must be one of file, service (Windows service), printer, registry, share (Network shares) or kernelobj (kernel objects such as mutexes, semaphores and events). NAME specifies the name of the resource, for example, the path of a file. 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.

-owner
Includes the owner information in the returned security descriptor.

-group
Includes the group information in the returned security descriptor.

-dacl
Includes the DACL in the returned security descriptor.

-sacl
Includes the SACL in the returned security descriptor. This requires the caller to have the SeSecurityPrivilege privilege enabled.


set_resource_security_descriptor RESTYPE NAME SECURITY_DESCRIPTOR ?options?
Modifies the security descriptor attached to a operating system resource. RESTYPE specifies the resource type and must be one of file, service (Windows service), printer, registry, share (Network shares) or kernelobj (kernel objects such as mutexes, semaphores and events). NAME specifies the name of the resource, for example, the path of a file. The fields of the resource's security descriptor are modified based on the contents of SECURITY_DESCRIPTOR. 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 it 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 is ignored on Windows NT 4.0.

-protect_sacl
If this option is specified, the resource will not inherit any SACL's from it 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 is ignored on Windows NT 4.0.


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 account.

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.

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).

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.

reset_thread_token
Ends the current thread's impersonation state.

new_luid
Returns a LUID (see Unique Identifiers).

new_uuid ?-localok?
Returns an UUID (see Unique Identifiers). 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 (see Unique Identifiers).

KEYWORDS

ACE, ACL, DACL, LUID, SACL, SID, UUID, access control, access control entry, access control list, access tokens, discretionary access control list, group accounts, group members, groups, impersonation, locally unique identifiers, passwords, privileges, process privileges, process token, security, security descriptor, system access control list, universally unique identifiers, user accounts, users

COPYRIGHT

Copyright © 2003, Ashok P. Nadkarni