Navigation

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.

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:

fromwinsysimportsecuritys=security.security("c:/windows")s.dump()

Parameters:

obj – any of None, a Security object, a pywin32 PyHANDLE,
a pywin32 PySECURITY_DESCRIPTOR, or a string

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:

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”

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.

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: