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:
from winsys import security s = security.security ("c:/windows") s.dump ()
a Security object
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 ()
A accounts.Principal object is its own context manager although it’s not then possible to pass in a password.
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
yields re-privileged token object
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:
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.
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.
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.
Constructs a Security object from an SDDL string. Useful for round-tripping, since the __str__() method produces an SDDL string.
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.
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")
Mapping between characters and security info:
Types of object which can be secured
Information held with a security descriptor body
Information held with a security descriptor header
Base for security-related exceptions
Raised if an attempt is made to read a security value which hasn’t been set