Changeset 257

Timestamp:

06/16/11 20:13:13 (13 years ago)

Author:

tim

Message:

documentation fixes/additions

Location:

trunk

Files:

• lib/regfi.c (modified) (7 diffs)
• lib/winsec.c (modified) (1 diff)
• python/pyregfi/__init__.py (modified) (12 diffs)
• python/pyregfi/winsec.py (modified) (4 diffs)

trunk/lib/regfi.c

@@ -1997 +1997 @@
   cur_key = regfi_iterator_cur_key(i);
   if(cur_key == NULL)
-    /* XXX: report error */
+    regfi_log_add(REGFI_LOG_ERROR, "Current key invalid in find_subkey.");
     return ret_val;
 
@@ -2100 +2100 @@
   cur_key = regfi_iterator_cur_key(i);
   if(cur_key == NULL)
-    /* XXX: report error */
+    regfi_log_add(REGFI_LOG_ERROR, "Current key invalid in cur_subkey.");
     return NULL;
 
@@ -2129 +2129 @@
   cur_key = regfi_iterator_cur_key(i);
   if(cur_key == NULL)
-    /* XXX: report error */
+    regfi_log_add(REGFI_LOG_ERROR, "Current key invalid in find_value.");
     return ret_val;
 
@@ -2161 +2161 @@
   cur_key = regfi_iterator_cur_key(i);
   if(cur_key == NULL)
-    /* XXX: report error */
+    regfi_log_add(REGFI_LOG_ERROR, "Current key invalid in cur_value.");
     return ret_val;
 
@@ -2523 +2523 @@
     }
 
-    /* XXX: check for NULL */
     tmp_str = talloc_realloc(NULL, tmp_str, uint8_t, tmp_size);
+    if(tmp_str == NULL)
+      return false;
     data->interpreted.string = tmp_str;
     data->interpreted_size = tmp_size;
@@ -2770 +2771 @@
   memcpy(ret_val->file_name, file_header+0x30,  REGFI_REGF_NAME_SIZE);
 
-  /* XXX: Should we add a warning if these uuid parsers fail?  Can they? */
   ret_val->rm_id = winsec_parse_uuid(ret_val, file_header+0x70, 16);
+  if(ret_val->rm_id == NULL)
+    regfi_log_add(REGFI_LOG_WARN, "Hive header's rm_id failed to parse.");
+
   ret_val->log_id = winsec_parse_uuid(ret_val, file_header+0x80, 16);
+  if(ret_val->log_id == NULL)
+    regfi_log_add(REGFI_LOG_WARN, "Hive header's log_id failed to parse.");
+
   ret_val->flags = IVAL(file_header, 0x90);
+
   ret_val->tm_id = winsec_parse_uuid(ret_val, file_header+0x94, 16);
+  if(ret_val->tm_id == NULL)
+    regfi_log_add(REGFI_LOG_WARN, "Hive header's tm_id failed to parse.");
+
   ret_val->guid_signature = IVAL(file_header, 0xa4);
 
@@ -3486 +3496 @@
 
   /* XXX: do something with unalloc? */
-
   max_size = regfi_calc_maxsize(file, offset);
   if((max_size < 0) || (num_chunks*sizeof(uint32_t) + 4 > max_size))

trunk/lib/winsec.c

@@ -62 +62 @@
   ret_val->control = SVAL(buf, 0x2);
 
+  /* XXX: should probably reject any non-self relative */
   if(!(ret_val->control & WINSEC_DESC_SELF_RELATIVE))
     fprintf(stderr, "DEBUG: NOT self-relative!\n");

trunk/python/pyregfi/__init__.py

@@ -11 +11 @@
 #
 # The library operates on registry hives, each of which is contained within a
-# single file.  To get started, one must first open the registry hive file with
-# the open() or file() Python built-in functions (or equivalent) and then pass
-# the resulting file object to pyregfi. For example:
+# single file.  The quickest way to get started, is to use the @ref openHive() 
+# function to obtain a Hive object.  For example:
 # @code
 # >>> import pyregfi
-# >>> fh = open('/mnt/win/c/WINDOWS/system32/config/system', 'rb')
-# >>> myHive = pyregfi.Hive(fh)
+# >>> myHive = pyregfi.openHive('/mnt/win/c/WINDOWS/system32/config/system')
 # @endcode
 #
@@ -300 +298 @@
 # 
 class Security(_StructureWrapper):
-    ## Number of keys referencing this SK record 
+    ## Number of registry Keys referencing this SK record
     ref_count = 1
 
@@ -306 +304 @@
     offset = 0xCAFEBABE
 
-    ## The @ref SecurityDescriptor for this SK record
+    ## The @ref winsec.SecurityDescriptor for this SK record
     descriptor = object()
 
@@ -314 +312 @@
         self.descriptor = winsec.SecurityDescriptor(base.contents.sec_desc.contents)
 
-    ## Loads the "previous" Security record in the hive
+    ## Loads the "next" Security record in the hive
     #
     # @note
@@ -337 +335 @@
 ## Abstract class for ValueList and SubkeyList
 class _GenericList(object):
+    # XXX: consider implementing keys(), values(), items() and other dictionary methods
     _hive = None
     _key_base = None
@@ -373 +372 @@
     ## Retrieves a list element by name
     #
+    # @param name The name of the subkey or value desired.  
+    #             This is case-sensitive.
+    #
+    # @note The registry format does inherently prevent multiple
+    #       subkeys or values from having the same name.  
+    #       This interface simply returns the first match.  
+    #       Lookups using this method could also fail due to incorrectly
+    #       encoded strings.
+    #       To identify any duplicates, use the iterator interface to 
+    #       check every list element.
+    #
     # @return the first element whose name matches, or None if the element
     #         could not be found
     def __getitem__(self, name):
+        # XXX: Consider interpreting integer names as offsets in the underlying list
         index = ctypes.c_uint32()
         if isinstance(name, str):
@@ -391 +402 @@
         raise KeyError('')
 
+
+    ## Fetches the requested element by name, or the default value if the lookup
+    #  fails.
+    # 
     def get(self, name, default):
         try:
@@ -426 +441 @@
 # @endcode
 #
-# @note SubkeyLists should never be accessed directly and only exist
-#       in association with a parent Key object.  Do not retain references to 
-#       SubkeyLists.  Instead, access them via their parent Key at all times.
+# You may also request the len() of a subkeys list. 
+# However keys(), values(), items() and similar methods are not currently 
+# implemented.
 class SubkeyList(_GenericList):
     _fetch_num = regfi.regfi_fetch_num_subkeys
@@ -447 +462 @@
 # @endcode
 #
-# @note ValueLists should never be accessed directly and only exist
-#       in association with a parent Key object.  Do not retain references to 
-#       ValueLists.  Instead, access them via their parent Key at all times.
+# You may also request the len() of a values list. 
+# However keys(), values(), items() and similar methods are not currently 
+# implemented.
 class ValueList(_GenericList):
     _fetch_num = regfi.regfi_fetch_num_values
@@ -460 +475 @@
 # access to their subkeys, values, and other metadata.
 #
-# @note Value instances may provide access to more than the attributes
+# @note Key instances may provide access to more attributes than are
 #       documented here.  However, undocumented attributes may change over time
 #       and are not officially supported.  If you need access to an attribute 
-#       not shown here, see pyregfi.structures.
+#       not shown here, see @ref pyregfi.structures.
 class Key(_StructureWrapper):
     ## A @ref ValueList object representing the list of Values 
@@ -558 +573 @@
         return None
 
+
+    ## Checks to see if this Key is the root of its Hive
+    #
+    #  @return True if it is, False otherwise
     def is_root(self):
         return (self._hive.root == self)
@@ -567 +586 @@
 # access to their associated data.
 #
-# @note Value instances may provide access to more than the attributes
+# @note Value instances may provide access to more attributes than are
 #       documented here.  However, undocumented attributes may change over time
 #       and are not officially supported.  If you need access to an attribute
-#       not shown here, see pyregfi.structures.
+#       not shown here, see @ref pyregfi.structures.
 class Value(_StructureWrapper):
     ## The raw Value name as an uninterpreted bytearray

trunk/python/pyregfi/winsec.py

@@ -97 +97 @@
 
 ## Represents a Microsoft access control entry, which are elements of access
-#  control lists
+#  control lists.  For more information, see: 
+#    http://msdn.microsoft.com/en-us/library/aa374868%28v=vs.85%29.aspx
 #
 #  @note
@@ -136 +137 @@
 
 
+## A Microsoft security descriptor
+# For more information, see:
+#   http://msdn.microsoft.com/en-us/library/aa379563%28v=vs.85%29.aspx
+#
 class SecurityDescriptor(object):
     ## The security descriptor's owner SID, as a string
@@ -143 +148 @@
     group = "S-1-2-..."
 
-    ## A list of @ref ACE objects which represents the System ACL
-    # May be None if a sacl isn't defined
+    ## The system access control list represented as a list of @ref ACE objects.
+    # 
+    # Is set to None if a sacl isn't defined
     sacl = []
 
-    ## A list of @ref ACE objects which represents the User ACL
-    # May be None if a dacl isn't defined
+    ## The discretionary access control list represented as a list of @ref ACE objects
+    #
+    # Is set to None if a dacl isn't defined
     dacl = []
 
@@ -160 +167 @@
         libc.free(c_str)
 
-        # XXX: add checks for NULL pointers
         self.sacl = None
         if sec_desc.sacl: