Moved lookup_sid to windows.utils + add Token to window.security + update doc about official Token path

Author: hakril

docs/source/security.rst

@@ -18,6 +18,17 @@ This module give access to :class:`SecurityDescriptor` and related structures (`
 
     See sample :ref:`sample_security`
 
+Token
+"""""
+
+The :mod:`windows.security` module is the official module where to retrieve the :class:`~windows.winobject.token.Token` class if ever needed.
+
+Indeed ``SecurityDescriptor`` & ``Token`` are deeply related and I may move ``token.py`` to a ``security/`` directory in the futur.
+
+
+    >>> windows.security.Token
+    <class 'windows.winobject.token.Token'>
+
 
 SecurityDescriptor
 """"""""""""""""""

docs/source/token.rst

@@ -9,6 +9,15 @@ This module expose the :class:`Token` object that can be primarily  retrieved th
     * :data:`windows.winobject.process.WinThread.token`
     * :data:`windows.current_process.token <windows.winobject.process.CurrentProcess.token>`
     * :data:`windows.current_thread.token <windows.winobject.process.CurrentThread.token>`
+    * :class:`windows.security.Token`
+
+.. note::
+
+    If you need to directly access the :class:`Token` class, please use :class:`windows.security.Token` as the
+    path of ``token.py`` may change.
+
+    Indeed ``SecurityDescriptor`` & ``Token`` are deeply related and I may move ``token.py`` to a
+    ``security/`` directory in the futur.
 
 .. note::
 

samples/security/security_descriptor.py

@@ -6,9 +6,9 @@
 print("Security descriptor is: {0}".format(sd))
 
 print("Owner: {0}".format(sd.owner))
-print("  - lookup: {0}".format(windows.security.lookup_sid(sd.owner)))
+print("  - lookup: {0}".format(windows.utils.lookup_sid(sd.owner)))
 print("Group: {0}".format(sd.group))
-print("  - lookup: {0}".format(windows.security.lookup_sid(sd.group)))
+print("  - lookup: {0}".format(windows.utils.lookup_sid(sd.group)))
 
 dacl = sd.dacl
 print("Dacl: {0}".format(dacl))

samples/token/token_demo.py

@@ -1,15 +1,14 @@
 import windows
-import windows.security
 import windows.generated_def as gdef
 
 tok = windows.current_process.token
 print("Our process token is {0}".format(tok))
 print("Retrieving some infos")
 print("Username: <{0}>".format(tok.username))
 print("User: {0!r}".format(tok.user))
-print("  - lookup : {0}".format(windows.security.lookup_sid(tok.user)))
+print("  - lookup : {0}".format(windows.utils.lookup_sid(tok.user)))
 print("Primary group: {0!r}".format(tok.primary_group))
-print("  - lookup : {0}".format(windows.security.lookup_sid(tok.primary_group)))
+print("  - lookup : {0}".format(windows.utils.lookup_sid(tok.primary_group)))
 
 print("")
 groups = tok.groups

tests/test_token.py

@@ -29,7 +29,7 @@ def test_lower_integrity(newtok):
 def test_token_user(curtok):
     user_sid = curtok.user
     assert user_sid
-    computername, username = windows.security.lookup_sid(user_sid)
+    computername, username = windows.utils.lookup_sid(user_sid)
     assert computername == windows.system.computer_name
     assert username == os.environ["USERNAME"]
 

windows/security.py

@@ -5,16 +5,8 @@
 import windows.generated_def as gdef
 from windows import winproxy
 
-# Temporary ? real API ?
-# Mov to utils ?
-def lookup_sid(psid):
-    usernamesize = gdef.DWORD(0x1000)
-    computernamesize = gdef.DWORD(0x1000)
-    username = ctypes.create_unicode_buffer(usernamesize.value)
-    computername = ctypes.create_unicode_buffer(computernamesize.value)
-    peUse = gdef.SID_NAME_USE()
-    winproxy.LookupAccountSidW(None, psid, username, usernamesize, computername, computernamesize, peUse)
-    return computername[:computernamesize.value], username[:usernamesize.value]
+from windows.winobject.token import Token
+
 
 # Specific access right
 

windows/utils/winutils.py

@@ -110,6 +110,20 @@ def lookup_privilege_name(privilege_value):
     winproxy.LookupPrivilegeNameA(None, privilege_value, buff, size)
     return buff[:size.value]
 
+
+def lookup_sid(psid):
+    """Retrieves the name of the Computer/Domain and the name of the Account for a given SID
+
+    :returns: (:class:`unicode`, :class:`unicode`) - A tuple of two unicode strings
+    """
+    usernamesize = gdef.DWORD(0x1000)
+    computernamesize = gdef.DWORD(0x1000)
+    username = ctypes.create_unicode_buffer(usernamesize.value)
+    computername = ctypes.create_unicode_buffer(computernamesize.value)
+    peUse = gdef.SID_NAME_USE()
+    winproxy.LookupAccountSidW(None, psid, username, usernamesize, computername, computernamesize, peUse)
+    return computername[:computernamesize.value], username[:usernamesize.value]
+
 def enable_privilege(lpszPrivilege, bEnablePrivilege):
     """
     Enable or disable a privilege::

windows/winobject/token.py

@@ -6,7 +6,6 @@
 from windows import utils
 from windows import winproxy
 import windows.generated_def as gdef
-import windows.security
 
 
 KNOW_INTEGRITY_LEVEL = gdef.FlagMapper(
@@ -282,7 +281,7 @@ def computername(self):
         return self._user_and_computer_name()[0]
 
     def _user_and_computer_name(self):
-        return windows.security.lookup_sid(self.user)
+        return windows.utils.lookup_sid(self.user)
 
 
     groups = TokenGroups #: Alias for TokenGroups (type may change in the future for improved struct)
@@ -309,6 +308,7 @@ def default_dacl(self):
 
         :type: :class:`windows.security.Acl`
         """
+        import window.security # Beuk move token.py & in a security/ directory ?
         return self.get_token_infomations(gdef.TokenDefaultDacl, windows.security.PAcl)[0]
 
     # def source(self): (tok.TokenSource) ??