This module provides procedures related to security and access
control in Windows operating systems.

This documentation is reference material that assumes
familiarity with Windows security terms and concepts. For more
introductory material and guide, see the Windows
Security chapter in the Tcl on Windows online
book.

Each trustee (user, group, logon session etc.) is identified by
a security identifier (SID). equal_sids compares two SIDs
for equality while sids_from_same_domain checks if two SIDs belong to
the same domain. well_known_sid returns well known SIDs as defined by
Microsoft and is_well_known_sid checks if a given SID is one of
these well known SIDs. get_sid_domain returns the SID of the domain
containing a specified SID.

A Locally Unique Identifier (LUID) is a
string generated by the command new_luid that is guaranteed to be unique on that
system for that boot session. Unique means it will not be generated
by some other call to that command.

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

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

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

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

anonymous

The impersonating process cannot obtain
identification information about the client or impersonate it.

identification

The impersonating process cannot impersonate the
client (ie. access resources using the client's credentials) but
can obtain identity and privilege information about the client.
This can be used for controlling access to its own objects (as
opposed to operating system resources).

impersonation

The impersonating process can impersonate the
client only on the local system. The client credentials cannot be
used to access other resources on the network.

delegation

The impersonating process can use the client's
credentials for accessing network resources.

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

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

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

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

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

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

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

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.

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

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

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

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

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

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.

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

The Windows credentials manager maintains a cache of credentials
for a user account or logon session. The twapi_security package provides some additional commands
to those already present in the twapi_base
package.

The credentials returns a list of credentials for the
calling process.

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

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

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

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.

Returns a list of current credentials from the user's
credential set. If TARGETPATTERN is not
specified, all credentials are returned. Otherwise, only those with
targets matching TARGETPATTERN are returned.
TARGETPATERN is a name prefix optionally
terminating in a wildcard *
character.

The returned list elements are dictionaries with the following
keys:

comment

Any associated descriptive comment for the
credential that might be added by the user.

One of the values session, local_machine
or enterprise depending on whether the
credentials are persisted for the current logon session only, or
are persisted on the local system and are visible to future logon
session for the user on that system, or are persisted on the local
system and are visible to logon session for that user from other
systems.

target

The name of the target for which the credential is
applicable.

targetalias

An alias for the target.

type

The credential type which is one of generic, domain_password, domain_certificate, domain_visible_passwordgeneric_certificate, domain_extended.

username

The user name associated with the target
credential.

The dictionary may contain other elements. These should be ignored
and are liable to change.

For more information, see the description of the
CREDENTIALS structure in the Windows SDK.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

-userACCOUNT

Only returns logon sessions for the specified user.
ACCOUNT may be either the account name or the
SID for the user.

-typeSESSIONTYPELIST

Only returns logon sessions that match one of the
specified types. SESSIONTYPELIST is a list of
integer logon session types defined in the Windows SDK or the
following equivalent tokens: interactive, network,
batch, service, proxy,
unlockworkstation, networkclear, newcredentials, remoteinteractive, cachedinteractive, cachedremoteinteractive or cachedunlockworkstation.

-tssessionTSSESSION

Only returns those logon sessions belonging to the
terminal services session identified by TSSESSION.

Returns a flat list of "optionvalue" 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.

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

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

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

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

-fullyqualifieddn

Fully qualified Active Directory distinguished
name.

-samcompatible

NT 4.0 SAM account name (default).

-display

Active Directory human-friendly display name.

-uniqueid

Active Directory GUID format name. This is NOT the
same as the SID.

-canonical

Active Directory canonical format.

-userprincipal

User principal format.

-canonicalex

Active Directory canonical format except that the
rightmost / is replaced by a
newline.

-serviceprincipal

Generalized service principal name.

-dnsdomain

DNS domain followed by the SAM user name.

-sid

User SID instead of name.

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

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

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

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

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

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

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

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

-all

Includes all fields in the security descriptor.
This requires the caller to have the SeSecurityPrivilege privilege enabled.

-dacl

Includes the DACL in the returned security
descriptor.

-group

Includes the group information in the returned
security descriptor.

-owner

Includes the owner information in the returned
security descriptor.

-sacl

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

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

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

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

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

Returns a dictionary whose keys are group SID's
contained in the token, with the corresponding value being a list
of attributes for the group.

-groups

Returns the list of the names of groups included in
the token. For domain accounts, an error is raised if the domain is
unreachable or if an SID has no corresponding name. Use -groupsids to avoid this.

Returns the primary group for the token. For domain
accounts, an error is raised if the domain is unreachable. Use
-primarygroupsid to avoid this.

-primarygroupsid

Returns the SID of primary group for the
token.

-privileges

Returns the list of enabled and disabled process
privileges in the same format as get_token_privileges. Deprecated, use -enabledprivileges and -disabledprivileges instead.

-restrictedgroupattrs

Returns a dictionary whose keys are SID's for the
restricted groups contained in the token, with the corresponding
value being a list of attributes for the group. See get_token_groups_and_attrs for details.

-restrictedgroups

Returns the list of restricted groups in the token.
For domain accounts, an error is raised if the domain is
unreachable. Use -restrictedgroupattrs to avoid
this.

-tssession

Returns the terminal server session id of the
process.

-usersid

Returns the SID of the user account associated with
the token.

-virtualized

Returns true if the process associated with the
token is virtualized and false otherwise. See virtualized_process.

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

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

Returns the LUID of the logon session that created the logon
session containing token TOKEN except if the
token's logon resulted from network authentication in which case
the command returns a zero LUID.

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

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.

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

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

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

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.

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.

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.

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.

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:

-auditsuccessBOOLEAN

Specified that the ACE should log permitted
accesses to a resource. Ignored if the ACE type is not audit. Defaults to true.

-auditfailureBOOLEAN

Specified that the ACE should log failed accesses
to a resource. Ignored if the ACE type is not audit. Defaults to true.

-recursecontainersBOOLEAN

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.

-recurseobjectsBOOLEAN

If the specified value is 1, the ACE is also
applied to all descendents of the object to which the ACE is
attached that are not themselves
containers. For example, in the case of a file ACE, this would
indicate that the ACE also apply to all files under all
subdirectories below a directory but not to the subdirectories
themselves. If 0 (default), the ACE does not apply to descendents
that are not containers.

-recurseonelevelonlyBOOLEAN

If the specified value is 0 (default), the
-recursecontainers and -recurseobjects options have effect at all levels below
the container object to which the ACE is applied. If the value is
1, the ACE is only applied to the immediate children of the
container object. This option has no effect if neither -recurseobjects nor -recursecontainers
is specified.

-selfBOOLEAN

If the specified value is 1 (default), the ACE
applies to the object to which it is attached. If the specified
value is 0, then the created ACE does not apply to the object with
which it is attached. In this case, it only applies to the
descendents of that object as indicated by the other options.

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

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

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

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

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

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

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

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

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
[email protected]_domain_name.

The following options may be specified:

-domainDOMAIN

Specifies the domain for the user. This option must
not be specified if USERNAME is in UPN format
[email protected]_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.

-typeLOGONTYPE

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.

-providerPROVIDER

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.

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.

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.

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

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

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

-all

All fields in the security descriptor are modified.
This requires the caller to have the SeSecurityPrivilege privilege enabled.

-owner

The resource's owner is modified.

-group

The resource's group is modified.

-dacl

Changes the DACL attached to the resource.

-sacl

Changes the SACL attached to the resource. This
requires the caller to have the SeSecurityPrivilege privilege enabled.

-protect_dacl

If this option is specified, the resource will not
inherit any DACL's from its parent. Otherwise, the parent's DACL's
flow down to the resource. This option only has effect if the
-dacl option is specified. This option
cannot be specified with -unprotect_dacl. If neither is specified, the
current DACL inherit settings are preserved.

-protect_sacl

If this option is specified, the resource will not
inherit any SACL's from its parent. Otherwise, the parent's SACL's
flow down to the resource. This option only has effect if the
-sacl option is specified. This option
cannot be specified with -unprotect_sacl. If neither is specified, the
current SACL inherit settings are preserved.

-unprotect_dacl

If this option is specified, the resource will
inherit any DACL's from its parent. This option only has effect if
the -dacl option is specified. This
option cannot be specified with -protect_dacl. If neither is specified, the current
DACL inherit settings are preserved.

-unprotect_sacl

If this option is specified, the resource will
inherit any SACL's from its parent. This option only has effect if
the -sacl option is specified. This
option cannot be specified with -protect_sacl. If neither is specified, the current
SACL inherit settings are preserved.

Returns a security descriptor identical to SECD except for the DACL field which is set to ACL. If ACL is the string "null", the security descriptor is set to have no
DACL. If ACL is an empty list, the security
descriptor has an empty DACL, which is not
the same not having a DACL. The boolean argument DEFAULTED (default false)
should be true if the DACL is to marked
as having been set by a default mechanism as opposed to being
explicitly set.

Returns a security descriptor identical to SECD except for the group field which is set to the SID
for account ACCOUNT. ACCOUNT
may be the SID itself or the name of the group. The boolean
argument DEFAULTED (default false) should be true
if the group is to marked as having been set by a default mechanism
as opposed to being explicitly set.

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

The following options may also be specified with the command:

-recursecontainersBOOLEAN

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

-recurseobjectsBOOLEAN

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

Returns a security descriptor identical to SECD except for the owner field which is set to the SID
for account ACCOUNT. ACCOUNT
may be the SID itself or the name of the user or group. The boolean
argument DEFAULTED (default false) should be true
if the owner is to marked as having been set by a default mechanism
as opposed to being explicitly set.

Returns a security descriptor identical to SECD except for the SACL field which is set to ACL. If ACL is the string "null", the security descriptor is set to have no
SACL. The boolean argument DEFAULTED (default
false) should be true if the SACL is to marked as having been set by
a default mechanism as opposed to being explicitly set.

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

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

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

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.