security

Windows manages security by granting rights – such as the ability to read or write an object – in the form of Access Control Lists (ACLs) of Access Control Entries (ACEs) to specific security principals: users, groups or other entities. In addition, process security is managed by granting each logged-on session a Token which contains the rights associated with that session plus certain Privileges, such as the ability to take ownership of any object or to access security-related data.

ACLs and ACEs are managed through the Security object, accessed mostly by means of the security() function, or the fs.Entry.security() method on external classes. Security principals are represented by Principal objects, accessed via the principal() function. Privilege objects refer to process privileges and are reached through the principal() function, or through the Privileges attribute of a Token.

Functions

security(obj=<Unset>, obj_type=<Unset>, options=<Unset>)

Return a Security object representing the security attributes of a named object (eg a file, registry key) or a kernel object (eg a process, a pipe). With no parameters, an empty Security object is returned which can then be set up with appropriate attributes and applied to other objects via its to_object() method. None and an existing Security object are passed through unchanged. A PySECURITY_DESCRIPTOR is converted to the corresponding Security object. A pywin32 PyHANDLE, representing a kernel object finds the security attributes for that object. Finally, a string finds the security attributes for the object of that name.

The most common use is to pass a filename. The from_object() method assumes that an unqualified string represents a file. If it represents something else, you need to specify its type in the obj_type parameter:

from winsys import security
s = security.security ("c:/windows")
s.dump ()

Parameters:

• obj – any of None, a Security object, a pywin32 PyHANDLE, a pywin32 PySECURITY_DESCRIPTOR, or a string
• obj_type – an SE_OBJECT_TYPE [file_object]
• options – anything acccepted by security_options() [DEFAULT_OPTIONS]

Returns:

a Security object

impersonate(*args, **kwds)

Context-manager which impersonates a user with a password and then reverts to the current user:

from __future__ import with_statement
from winsys import security
with security.impersonate ("Administrator", "password"):
  print security.me ()

Note

A accounts.Principal object is its own context manager although it’s not then possible to pass in a password.

Parameters:

• user – any valid username
• password – username for that user; if not specified, user will be prompted

change_privileges(*args, **kwds)

Context manager which temporarily enables/disables privs within the current token, reverting when done to the previous situation:

from __future__ import with_statement
from winsys import security, fs

test = fs.file ("test")
test.touch ()
with security.change_privileges (["restore"]):
  with test.security () as s:
    print s.owner
    s.owner = security.principal ("Administrator")
    print s.owner

Parameters:

• enable_privs – list of privileges to enable; each priv is anything accepted by privilege()
• disable_privs – list of privileges to disable; each priv is anything accepted by privilege()
• _token – (internal) a token to use if not the current one

Returns:

yields re-privileged token object

Classes

class Security(control=<Unset>, owner=<Unset>, group=<Unset>, dacl=<Unset>, sacl=<Unset>, inherit_handle=True, originating_object=<Unset>, originating_object_type=<Unset>)

The heart of the security module, this class represents the security descriptor of a file, kernel object or any other securable object. It’s most commonly instantiated from an object’s security method (eg fs.File.security) or by means of the security() function which can take the name or handle of an object and return a corresponding Security object.

Key attributes are:

• owner - a Principal object representing the object owner
• group - a Principal object representing the object group
• dacl - a security.DACL object representing the DACL
• sacl - an security.SACL object representing the SACL

of which group and sacl are less likely to be used (group hardly at all). These attributes are carefully-handled properties of the Security object and are intended to make it very easy to manipulate the ACLs and ACEs of the Windows security model. The owner and group accept assignments of anything accepted by principal() while the ACL attributes accept anything accepted by acl(), in particular a list of ACE entries, themselves anything accepted by ace(). So a very simple way to add the local administrator to the DACL with full control is:

from winsys import security
with security.security ("c:/temp/blah.txt") as s:
  s.dacl.append (("Administrator", "F", "ALLOW"))

or to give only the logged-on user rights to a particular file while explicitly denying the local administrator:

from winsys import security
with security.security ("c:/temp/secret.txt") as s:
  s.dacl = [
    (security.me (), "F", "ALLOW"),
    ("Administrator", "F", "DENY")
  ]
  s.break_inheritance (copy_first=False)

By default, only Owner and Group information is populated (although this can easily by changed by passing other options when creating the object). And only those objects which are populated, or explicitly requested will be updated when the security information is written back to the underlying object or handle.

A Security object is its own context handler and this is the most straightforward way to update security information, although the Security.to_object() method will let you write the security information back to any arbitrary object, including the one it came from.

For the purposes of serialisation, the standard SDDL format is used for strings and can be round-tripped between as_string() and from_string().

Create a new Security object from its component pieces, all optional. You won’t often need to call this as you can do most useful things via the security() function, but to create a simple security descriptor for immediate use, you can instantiate it directly.

None of the parameters need be specified; with the exceptions of originating_object and originating_object_type, you can set each one later, directly or indirectly.

Parameters:

• control – any combination of SD_CONTROL. Most commonly set, if at all, to “dacl_protected”
• owner – anything accepted by principal()
• group – anything accepted by principal()
• dacl – anything accepted by dacl()
• sacl – anything accepted by sacl()
• inherit_handle – whether this handle is inherited by child processes
• originating_object – name or handle of the object this security currently applies to, if any
• originating_object_type – one of SE_OBJECT_TYPE referring to the type of object this security currently applies to, if any.

as_string()

break_inheritance(copy_first=True, break_dacl=True, break_sacl=True)

Cause this security object to start a new thread of inheritance. By default, assume that DACL & SACL inheritance are both to be broken and that existing permissions are to be retained, although uninherited.

Parameters:

• copy_first – whether to retain existing permissions [True]
• break_dacl – whether to break DACL inheritance [True]
• break_sacl – whether to break SACL inheritance [True]

Returns:

self

dump(level=0)

dumped(level)

classmethod from_object(obj, object_type=<Unset>, options=<Unset>)

Constructs a Security object from a PyHANDLE or an object name. Almost never called directly; use security().

classmethod from_security_descriptor(sd, inherit_handle=True, originating_object=<Unset>, originating_object_type=<Unset>, options=<Unset>)

Constructs a Security object from a PySECURITY_DESCRIPTOR object. Almost never called directly; use security() unless you need some slightly special handling with inherited handles.

classmethod from_string(sddl, options=<Unset>)

Constructs a Security object from an SDDL string. Useful for round-tripping, since the __str__() method produces an SDDL string.

pyobject(include_inherited=False)

restore_inheritance(copy_back=True, restore_dacl=True, restore_sacl=True)

Cause this security object to regain its inhertance from its parents. By default, assume that DACL & SACL inheritance are both to be recovered and that existing permissions are to be copied back in.

Parameters:

• copy_back – whether to copy back inherited permissions [True]
• restore_dacl – whether to restore DACL inheritance [True]
• restore_sacl – whether to restore SACL inheritance [True]

Returns:

self

classmethod security_options(options)

Accept either an integer representing a bitmask combination or SECURITY_INFORMATION values; or a string whose characters map, via OPTIONS to the same values. The following have the same result:

• SECURITY_INFORMATION.OWNER | SECURITY_INFORMATION.DACL
• “OD”
• 0x05

to_object(obj=<Unset>, object_type=<Unset>, options=<Unset>)

Write the current state of the object as the security settings on a Windows object, typically a file. This is most often called implicitly when the Security object is used as a context manager, but can be called explicitly, especially to copy one object’s security to another:

from winsys import security
s = security.security ("filea")
s.to_object ("fileb")

Parameters:

• obj – (optional) object or object name to write security to if this Security object wasn’t created from an object in the first place.
• object_type – an SE_OBJECT_TYPE [file_object]
• options – anything accepted by security_options()

OPTIONS

Mapping between characters and security info:

• O - Owner
• G - Group
• D - DACL
• S - SACL

dacl

group

owner

sacl

class Privilege(luid, attributes=0)

luid is one of the PRIVILEGE_NAME constants attributes is the result of or-ing the different PRIVILEGE_ATTRIBUTE items you want

as_string()

dump(level=0)

dumped(level=0)

classmethod from_string(string)

pyobject()

enabled

Constants

SE_OBJECT_TYPE

Types of object which can be secured

Name	Val	Win32
UNKNOWN_OBJECT_TYPE	0	SE_UNKNOWN_OBJECT_TYPE
FILE_OBJECT	1	SE_FILE_OBJECT
PROVIDER_DEFINED_OBJECT	10	SE_PROVIDER_DEFINED_OBJECT
WMIGUID_OBJECT	11	SE_WMIGUID_OBJECT
REGISTRY_WOW64_32KEY	12	SE_REGISTRY_WOW64_32KEY
SERVICE	2	SE_SERVICE
PRINTER	3	SE_PRINTER
REGISTRY_KEY	4	SE_REGISTRY_KEY
LMSHARE	5	SE_LMSHARE
KERNEL_OBJECT	6	SE_KERNEL_OBJECT
WINDOW_OBJECT	7	SE_WINDOW_OBJECT
DS_OBJECT	8	SE_DS_OBJECT
DS_OBJECT_ALL	9	SE_DS_OBJECT_ALL

SECURITY_INFORMATION

Information held with a security descriptor body

Name	Val	Win32
PROTECTED_DACL	-2147483648	PROTECTED_DACL_SECURITY_INFORMATION
OWNER	1	OWNER_SECURITY_INFORMATION
PROTECTED_SACL	1073741824	PROTECTED_SACL_SECURITY_INFORMATION
LABEL	16	LABEL_SECURITY_INFORMATION
GROUP	2	GROUP_SECURITY_INFORMATION
UNPROTECTED_SACL	268435456	UNPROTECTED_SACL_SECURITY_INFORMATION
DACL	4	DACL_SECURITY_INFORMATION
UNPROTECTED_DACL	536870912	UNPROTECTED_DACL_SECURITY_INFORMATION
SACL	8	SACL_SECURITY_INFORMATION

SD_CONTROL

Information held with a security descriptor header

Name	Val	Win32
OWNER_DEFAULTED	1	SE_OWNER_DEFAULTED
DACL_AUTO_INHERITED	1024	SE_DACL_AUTO_INHERITED
SACL_PRESENT	16	SE_SACL_PRESENT
GROUP_DEFAULTED	2	SE_GROUP_DEFAULTED
SACL_AUTO_INHERITED	2048	SE_SACL_AUTO_INHERITED
SACL_DEFAULTED	32	SE_SACL_DEFAULTED
SELF_RELATIVE	32768	SE_SELF_RELATIVE
DACL_PRESENT	4	SE_DACL_PRESENT
DACL_PROTECTED	4096	SE_DACL_PROTECTED
DACL_DEFAULTED	8	SE_DACL_DEFAULTED
SACL_PROTECTED	8192	SE_SACL_PROTECTED

Exceptions

exception x_security(errno=None, errctx=None, errmsg=None)

Base for security-related exceptions

exception x_value_not_set(errno=None, errctx=None, errmsg=None)

Raised if an attempt is made to read a security value which hasn’t been set

References

See also

Using the security module

Cookbook examples of using the security module