Security(n) "Security functions"
Security - Functions related to authentication and access control
package require twapi
This package provides procedures related to authentication and access
control in Windows operating systems.
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.
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.
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.
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.
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 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.
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.
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.
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.
- 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).
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 © 2003, Ashok P. Nadkarni