Changeset 169 for trunk/include


Ignore:
Timestamp:
03/03/10 14:24:58 (15 years ago)
Author:
tim
Message:

filled in additional, minimal documentation

Location:
trunk/include
Files:
5 edited

Legend:

Unmodified
Added
Removed

  • trunk/include/lru_cache.h

    r168 r169  
    1 /**
    2  * @file
    3  *
    4  * Copyright (C) 2008-2009 Timothy D. Morgan
     1/*
     2 * Copyright (C) 2008-2010 Timothy D. Morgan
    53 *
    64 * This program is free software; you can redistribute it and/or modify
    … …  
    1917 * $Id$
    2018 */
     19
     20/**
     21 * @file
     22 *
     23 * A data structure which approximates a least recently used (LRU) cache.
     24 * Implemented as a basic randomized hash table.
     25 */
     26
    2127
    2228#ifndef LRU_CACHE_H
    … …  
    4450};
    4551
     52
     53/** XXX: document this. */
    4654typedef struct _lru_cache
    4755{
    … …  
    5765
    5866
     67/**
     68 * XXX: finish documenting.
     69 */
    5970lru_cache* lru_cache_create(uint32_t max_keys, uint32_t secret);
     71
     72
     73/**
     74 * XXX: finish documenting.
     75 */
    6076lru_cache* lru_cache_create_ctx(void* talloc_ctx, uint32_t max_keys,
    6177                                uint32_t secret, bool talloc_data);
     78
     79
     80/**
     81 * XXX: finish documenting.
     82 */
    6283void lru_cache_destroy(lru_cache* ht);
    6384
    64 /*
    65  *
     85
     86/**
     87 * XXX: finish documenting.
    6688 */
    6789bool lru_cache_update(lru_cache* ht, const void* index,
    6890                      uint32_t index_len, void* data);
    6991
    70 /* Returns pointer to data previously stored at index.
    71  * If no data was found at index, NULL is returned.
     92/**
     93 * XXX: finish documenting.
     94 *
     95 * @return A pointer to data previously stored at index.
     96 *         If no data was found at index, NULL is returned.
    7297 */
    7398void* lru_cache_find(lru_cache* ht, const void* index,
    7499                     uint32_t index_len);
    75100
    76 /* Removes entry from table at index.
    77  * Returns pointer to data that was there previously. 
    78  * Returns NULL if no entry is at index.
     101/**
     102 * XXX: finish documenting.
     103 *
     104 * Removes entry from table at index.
     105 *
     106 * @return A pointer to data that was there previously or NULL if no entry is
     107 *         at index.
    79108 */
    80109bool lru_cache_remove(lru_cache* ht, const void* index,

  • trunk/include/range_list.h

    r168 r169  
    1 /**
    2  * @file
    3  *
    4  * Copyright (C) 2008-2009 Timothy D. Morgan
     1/*
     2 * Copyright (C) 2008-2010 Timothy D. Morgan
    53 *
    64 * This program is free software; you can redistribute it and/or modify
    … …  
    1816 *
    1917 * $Id$
     18 */
     19
     20/**
     21 * @file
     22 *
     23 * A data structure which stores a list of address ranges.
     24 *
     25 * range_lists support basic in-place modifications and maintain the address
     26 * space in sorted order.  Looking up a range_list_element is implemented
     27 * through binary search.
    2028 */
    2129
    … …  
    3846
    3947
     48/** XXX: document this. */
    4049typedef struct _range_list
    4150{
    … …  
    4655
    4756
    48 /* range_list_new():
    49  *  Allocates a new range_list.
     57/** Allocates a new range_list.
    5058 *
    51  * Returns:
    52  *  A newly allocated range_list, or NULL if an error occurred.
     59 * @return A newly allocated range_list, or NULL if an error occurred.
    5360 */
    5461range_list* range_list_new();
    5562
    5663
    57 /* range_list_free():
    58  *  Frees the memory associated with a range_list, including the elements, but
    59  *  not any data parameters referenced by those elements.  If rl is NULL, does
    60  *  nothing.
     64/** Frees the memory associated with a range_list, including the elements, but
     65 *  not any data parameters referenced by those elements. 
    6166 *
    62  * Arguments:
    63  *  rl -- the range_list to be free()d.
     67 * If rl is NULL, does nothing.
     68 *
     69 * @param rl the range_list to be free()d.
    6470 */
    6571void range_list_free(range_list* rl);
    6672
    6773
    68 /* range_list_size():
    69  *  Query the current number of elements on a range_list
     74/** Query the current number of elements on a range_list
    7075 *
    71  * Arguments:
    72  *  rl -- the range_list to query
     76 * @param rl the range_list to query
    7377 *
    74  * Returns:
    75  *  The number of elements currently in the list.
     78 * @return The number of elements currently in the list.
    7679 */
    7780uint32_t range_list_size(const range_list* rl);
    7881
    7982
    80 /* range_list_add():
    81  *  Adds an element to the range_list. 
    82  *  The new element must not overlap with others.
    83  *  NOTE: this is a slow operation.
     83/** Adds an element to the range_list. 
    8484 *
    85  * Arguments:
    86  *  rl     -- the range list to update
    87  *  offset -- the starting point for the range
    88  *  length -- the length of the range
    89  *  data   -- misc data associated with this range element
    90  * Returns:
    91  *  true on success, false on failure.
    92  *  Failures can occur due to memory limitations, max_size limitations,
    93  *  or if the submitted range overlaps with an existing element.  Other
    94  *  errors may also be possible.
     85 * The new element must not overlap with others.
     86 * NOTE: this is a slow operation.
     87 *
     88 * @param rl     the range list to update
     89 * @param offset the starting point for the range
     90 * @param length the length of the range
     91 * @param data   misc data associated with this range element
     92 *
     93 * @return  true on success, false on failure.
     94 *
     95 * Failures can occur due to memory limitations, max_size limitations,
     96 * or if the submitted range overlaps with an existing element.  Other
     97 * errors may also be possible.
    9598 */
    9699bool range_list_add(range_list* rl, uint32_t offset, uint32_t length, void* data);
    97100
    98101
    99 /* range_list_remove():
    100  *  Removes an element from the list.  The element data structure will be
    101  *  freed, but the data property will not be.
     102/** Removes an element from the list. 
    102103 *
    103  * Arguments:
    104  *  rl     -- the range_list to modify
    105  *  index  -- the element index to remove
     104 * The element data structure will be freed, but the data property will not be.
    106105 *
    107  * Returns:
    108  *  true if the element was successfully removed, false otherwise.
     106 * @param rl    the range_list to modify
     107 * @param index the element index to remove
     108 *
     109 * @return true if the element was successfully removed, false otherwise.
    109110 */
    110111bool range_list_remove(range_list* rl, uint32_t index);
    111112
    112113
    113 /* range_list_get():
    114  *  Retrieves the element for a given index.
     114/** Retrieves the element for a given index.
    115115 *
    116  * Arguments:
    117  *  rl    -- the range_list being queried.
    118  *  index -- the element index desired.
     116 * @param rl    the range_list being queried.
     117 * @param index the element index desired.
    119118 *
    120  * Returns:
    121  *  The element for a given index, or NULL if the element is not available.
     119 * @return The element for a given index, or NULL if the element is not
     120 *        available.
    122121 */
    123122const range_list_element* range_list_get(const range_list* rl, uint32_t index);
    124123
    125124
    126 /* range_list_find():
    127  *  Attempts to find the unique element whose range encompasses offset.
     125/** Attempts to find the unique element whose range encompasses offset.
    128126 *
    129  * Arguments:
    130  *  rl     -- the range_list being queried.
    131  *  offset -- the location for which an element is desired.
     127 * @param rl     the range_list being queried.
     128 * @param offset the location for which an element is desired.
    132129 *
    133  * Returns:
    134  *  A matching element index or a negative value if none could be found.
     130 * @return A matching element index or a negative value if none could be found.
    135131 */
    136132int32_t range_list_find(const range_list* rl, uint32_t offset);
    137133
    138134
    139 /* range_list_find_data():
    140  *  Same as range_list_find(), but returns the data associated with an element.
     135/** Same as range_list_find(), but returns the data associated with an element.
    141136 *
    142  * Arguments:
    143  *  rl     -- the range_list being queried.
    144  *  offset -- the address to search for in the ranges
     137 * @param rl     the range_list being queried.
     138 * @param offset the address to search for in the ranges
    145139 *
    146  * Returns:
    147  *  The data element of the matching element index or NULL if none could
    148  *  be found.
     140 * @return The data element of the matching element index or NULL if none could
     141 *         be found.
    149142 *
    150  *  NOTE: May also return NULL if an element matched but if the data
     143 *  NOTE: May also return NULL if an element matched but the data
    151144 *        element was never set.
    152145 */
    … …  
    154147
    155148
    156 /* range_list_split_element():
    157  *  Splits an existing element into two elements in place.
     149/**  Splits an existing element into two elements in place.
    158150 *
    159  *  The resulting list will contain an additional element whose offset
    160  *  is the one provided and whose length extends to the end of the old element
    161  *  (the one identified by the index).  The original element's offset will
    162  *  remain the same while it's length is shortened such that it is contiguous
    163  *  with the newly created element.  The newly created element will have an index
    164  *  of one more than the current element.
     151 * The resulting list will contain an additional element whose offset
     152 * is the one provided and whose length extends to the end of the old element
     153 * (the one identified by the index).  The original element's offset will
     154 * remain the same while it's length is shortened such that it is contiguous
     155 * with the newly created element.  The newly created element will have an index
     156 * of one more than the current element.
    165157 *
    166  *  Both the original element and the newly created element will reference the
    167  *  original element's data.
     158 * Both the original element and the newly created element will reference the
     159 * original element's data.
    168160 *
    169  * Arguments:
    170  *  rl     -- the range_list to modify
    171  *  index  -- the index of the element to be split
    172  *  offset -- the at which the element will be split
     161 * @param rl     the range_list to modify
     162 * @param index  the index of the element to be split
     163 * @param offset the at which the element will be split
    173164 *
    174  * Returns:
    175  *  true if the element was successfully split, false otherwise.
    176  *   
    177  *
     165 * @return true if the element was successfully split, false otherwise.
    178166 */
    179167bool range_list_split_element(range_list* rl, uint32_t index, uint32_t offset);
    180168
    181169
    182 /* range_list_has_range():
    183  *  Determines whether or not a specified range exists contiguously within the
     170/** Determines whether or not a specified range exists contiguously within the
    184171 *  range_list.
    185172 *
    186  * Arguments:
    187  *  rl     -- the range_list to search
    188  *  start  -- the offset at the beginning of the range
    189  *  length -- the length of the range
     173 * @param rl     the range_list to search
     174 * @param start  the offset at the beginning of the range
     175 * @param length the length of the range
    190176 *
    191  * Returns:
    192  *  true if the specified range exists and is complete, false otherwise.
     177 * @return true if the specified range exists and is complete, false otherwise.
    193178 */
    194179bool range_list_has_range(range_list* rl, uint32_t start, uint32_t length);

  • trunk/include/regfi.h

    r168 r169  
    1 /** @file
    2  * Windows NT (and later) registry parsing library
    3  *
    4  * Branched from Samba project Subversion repository, version #6903:
    5  *   http://viewcvs.samba.org/cgi-bin/viewcvs.cgi/trunk/source/include/regfio.h?rev=6903&view=auto
    6  *
     1/*
    72 * Copyright (C) 2005-2010 Timothy D. Morgan
    83 * Copyright (C) 2005 Gerald (Jerry) Carter
    … …  
    2419 */
    2520
    26 /************************************************************
    27  * Most of this information was obtained from
    28  * http://www.wednesday.demon.co.uk/dosreg.html
    29  * Thanks Nigel!
    30  ***********************************************************/
     21/**
     22 * @file
     23 * Windows NT (and later) read-only registry library
     24 *
     25 * This library is intended for use in digital forensics investigations, but
     26 * is likely useful in other applications.
     27 *
     28 * Branched from Samba project Subversion repository, version #6903:
     29 *   http://viewcvs.samba.org/cgi-bin/viewcvs.cgi/trunk/source/include/regfio.h?rev=6903&view=auto
     30 *
     31 * Since then, it has been heavily rewritten, simplified, and improved.
     32 */
    3133
    3234/**
    3335 * @mainpage Home
    3436 *
    35  * See \ref regfiTopLayer
    36  */
     37 * The regfi library is a read-only NT registry library which serves as the main
     38 * engine behind the reglookup tool.  It is designed with digital forensic
     39 * analysis in mind, but it should also be useful in other tools which need to
     40 * efficiently traverse and query registry data structures.
     41 *
     42 * The library is broken down into four main parts, the
     43 * @ref regfiBase "Base Layer", which any code dependent on the library will
     44 * likely need to rely on, as well as three main functional layers:
     45 * @li @ref regfiIteratorLayer
     46 * @li @ref regfiGlueLayer
     47 * @li @ref regfiParseLayer
     48 *
     49 * Most users will find that a combination of the Base Layer and the Iterator Layer
     50 * will be sufficient for accessing registry hive files.  Those who are wiling
     51 * to dive deep into registry data structures, for instance to recover deleted
     52 * data structures or to research Windows registry behavior in detail, will
     53 * find the Parse Layer to be quite useful.
     54 */
     55
    3756
    3857#ifndef _REGFI_H
    … …  
    4261#include <stdio.h>
    4362#include <stdbool.h>
    44 #include <stdarg.h>
    4563#include <string.h>
    4664#include <errno.h>
    … …  
    5068#include <sys/types.h>
    5169#include <unistd.h>
    52 #include <assert.h>
    5370#include <iconv.h>
    5471
    … …  
    230247
    231248
    232 /* HBIN block */
     249/** HBIN block information
     250 * @ingroup regfiMiddleLayer
     251 */
    233252typedef struct _regfi_hbin
    234253{
    235   uint32_t file_off;       /* my offset in the registry file */
    236   uint32_t ref_count;      /* how many active records are pointing to this
    237                           * block (not used currently)
    238                           */
    239  
    240   uint32_t first_hbin_off; /* offset from first hbin block */
    241   uint32_t block_size;     /* block size of this block
    242                           * Should be a multiple of 4096 (0x1000)
    243                           */
    244   uint32_t next_block;     /* relative offset to next block. 
    245                           * NOTE: This value may be unreliable!
    246                           */
    247 
    248   uint8_t magic[REGFI_HBIN_MAGIC_SIZE]; /* "hbin" */
     254  /** Offset of this HBIN in the registry file */
     255  uint32_t file_off;
     256
     257  /** Number of active records pointing to this block (not used currently) */
     258  uint32_t ref_count;
     259
     260  /** Offset from first hbin block */
     261  uint32_t first_hbin_off;
     262
     263  /** Block size of this block Should be a multiple of 4096 (0x1000) */
     264  uint32_t block_size;
     265
     266  /** Relative offset to next block. 
     267   *
     268   * @note This value may be unreliable!
     269   */
     270  uint32_t next_block;
     271
     272  /** Magic number for the HBIN (should be "hbin"). */
     273  uint8_t magic[REGFI_HBIN_MAGIC_SIZE];
    249274} REGFI_HBIN;
    250275
    … …  
    262287
    263288
     289/** Subkey-list structure
     290 * @ingroup regfiMiddleLayer
     291 */
    264292typedef struct _regfi_subkey_list
    265293{
    … …  
    284312
    285313typedef uint32_t REGFI_VALUE_LIST_ELEM;
     314/** Value-list structure
     315 * @ingroup regfiMiddleLayer
     316 */
    286317typedef struct _regfi_value_list
    287318{
    … …  
    295326
    296327
     328/** Class name structure (used in storing SysKeys)
     329 * @ingroup regfiBase
     330 */
    297331typedef struct _regfi_classname
    298332{
    299   /* As converted to requested character encoding. */
     333  /** As converted to requested REGFI_ENCODING */
    300334  char* interpreted;
    301335
    302   /* Represents raw buffer read from classname cell. */
     336  /** Represents raw buffer read from classname cell.
     337   *
     338   * Length of this item is specified in the size field.
     339   */
    303340  uint8_t* raw;
    304341
    305   /* Length of the raw data. May be shorter than that indicated by parent key.*/
     342  /** Length of the raw data.
     343   *
     344   * May be shorter than that indicated by parent key.
     345   */
    306346  uint16_t size;
    307347} REGFI_CLASSNAME;
    308348
    309349
     350/** Data record structure
     351 * @ingroup regfiBase
     352 */
    310353typedef struct _regfi_data
    311354{
     355  /** Data type of this data, as indicated by the referencing VK record. */
    312356  uint32_t type;
    313357
    314   /* Length of the raw data. */
     358  /** Length of the raw data. */
    315359  uint32_t size;
    316360
    317   /* This is always present, representing the raw data cell contents. */
     361  /** This is always present, representing the raw data cell contents. */
    318362  uint8_t* raw;
    319363
    320   /* Represents the length of the interpreted value. Meaning is type-specific.*/
     364  /** Represents the length of the interpreted value. Meaning is type-specific. */
    321365  uint32_t interpreted_size;
    322366
    323   /* These items represent interpreted versions of the raw attribute above.
    324    * Only use the appropriate member according to the type field. 
    325    * In the event of an unknown type, use only the raw field.
     367  /** These items represent interpreted versions of the REGFI_DATA::raw field.
     368   *
     369   * Only use the appropriate member according to the REGFI_DATA::type field.
     370   * In the event of an unknown type, use only the REGFI_DATA::raw field.
    326371   */
    327372  union _regfi_data_interpreted
    328373  {
    329     uint8_t* none; /* */
     374    /** REG_NONE
     375     *
     376     * Stored as a raw buffer.  Use REGFI_DATA::interpreted_size to determine
     377     * length.
     378     */
     379    uint8_t* none;
     380
     381    /** REG_SZ
     382     *
     383     * Stored as a NUL terminated string.  Converted to the specified
     384     * REGFI_ENCODING.
     385     */
    330386    uint8_t* string;
     387
     388    /** REG_EXPAND_SZ
     389     *
     390     * Stored as a NUL terminated string.  Converted to the specified
     391     * REGFI_ENCODING.
     392     */
    331393    uint8_t* expand_string;
    332     uint8_t* binary; /* */
     394
     395    /** REG_BINARY
     396     *
     397     * Stored as a raw buffer.  Use REGFI_DATA::interpreted_size to determine
     398     * length.
     399     */
     400    uint8_t* binary;
     401
     402    /** REG_DWORD */
    333403    uint32_t dword;
     404
     405    /** REG_DWORD_BE */
    334406    uint32_t dword_be;
     407
     408    /** REG_LINK
     409     *
     410     * Stored as a NUL terminated string.  Converted to the specified
     411     * REGFI_ENCODING.
     412     */
    335413    uint8_t* link;
     414
     415    /** REG_MULTI_SZ
     416     *
     417     * Stored as a list of uint8_t* pointers, terminated with a NULL pointer.
     418     * Each string element in the list is NUL terminated, and the character set
     419     * is determined by the specified REGFI_ENCODING.
     420     */
    336421    uint8_t** multiple_string;
     422
     423    /** REG_QWORD */
    337424    uint64_t qword;
    338425
    … …  
    340427     * the future as the formats become better understood.
    341428     */
     429
     430    /** REG_RESOURCE_LIST
     431     *
     432     * Stored as a raw buffer.  Use REGFI_DATA::interpreted_size to determine
     433     * length.
     434     */
    342435    uint8_t* resource_list;
     436
     437    /** REG_FULL_RESOURCE_DESCRIPTOR
     438     *
     439     * Stored as a raw buffer.  Use REGFI_DATA::interpreted_size to determine
     440     * length.
     441     */
    343442    uint8_t* full_resource_descriptor;
     443
     444    /** REG_RESOURCE_REQUIREMENTS_LIST
     445     *
     446     * Stored as a raw buffer.  Use REGFI_DATA::interpreted_size to determine
     447     * length.
     448     */
    344449    uint8_t* resource_requirements_list;
    345450  } interpreted;
    … …  
    347452
    348453
    349 /* Value record */
    350 typedef struct
     454/** Value structure
     455 * @ingroup regfiBase
     456 */
     457typedef struct
    351458{
    352   uint32_t offset;      /* Real offset of this record's cell in the file */
    353   uint32_t cell_size;   /* ((start_offset - end_offset) & 0xfffffff8) */
    354 
    355   REGFI_DATA* data;     /* XXX: deprecated */
    356 
    357   char*  valuename;
     459  /** Real offset of this record's cell in the file */
     460  uint32_t offset;     
     461
     462  /** ((start_offset - end_offset) & 0xfffffff8) */
     463  uint32_t cell_size;
     464
     465  /* XXX: deprecated */
     466  REGFI_DATA* data;
     467
     468  /** The name of this value converted to desired REGFI_ENCODING. 
     469   *
     470   * This conversion typically occurs automatically through REGFI_ITERATOR
     471   * settings.  String is NUL terminated.
     472   */
     473  char*    valuename;
     474
     475  /** The raw value name
     476   *
     477   * Length of the buffer is stored in name_length.
     478   */
    358479  uint8_t* valuename_raw;
     480
     481  /** Length of valuename_raw */
    359482  uint16_t name_length;
    360   uint32_t hbin_off;    /* offset from beginning of this hbin block */
     483
     484  /** Offset from beginning of this hbin block */
     485  uint32_t hbin_off;
    361486 
    362   uint32_t data_size;     /* As reported in the VK record.  May be different than
    363                          * That obtained while parsing the data cell itself. */
    364   uint32_t data_off;      /* Offset of data cell (virtual) */
     487  /** Size of the value's data as reported in the VK record.
     488   *
     489   * May be different than that obtained while parsing the data cell itself.
     490   */
     491  uint32_t data_size;
     492
     493  /** Virtual offset of data cell */
     494  uint32_t data_off;
     495
     496  /** Value's data type */
    365497  uint32_t type;
     498
     499  /** VK record's magic number (should be "vk") */
    366500  uint8_t  magic[REGFI_CELL_MAGIC_SIZE];
     501
     502  /** VK record flags */
    367503  uint16_t flags;
     504
     505  /* XXX: A 2-byte field of unknown purpose stored in the VK record */
    368506  uint16_t unknown1;
    369   bool data_in_offset;
     507
     508  /** Whether or not the data record is stored in the VK record's data_off field.
     509   *
     510   * This information is derived from the high bit of the raw data size field.
     511   */
     512  bool     data_in_offset;
    370513} REGFI_VK_REC;
    371514
    … …  
    374517struct _regfi_sk_rec;
    375518
     519/** Security structure
     520 * @ingroup regfiBase
     521 */
    376522typedef struct _regfi_sk_rec
    377523{
    378   uint32_t offset;        /* Real file offset of this record */
    379   uint32_t cell_size;   /* ((start_offset - end_offset) & 0xfffffff8) */
    380 
     524  /** Real file offset of this record */
     525  uint32_t offset;
     526
     527  /** ((start_offset - end_offset) & 0xfffffff8) */
     528  uint32_t cell_size;
     529
     530  /** The stored Windows security descriptor for this SK record */
    381531  WINSEC_DESC* sec_desc;
    382   uint32_t hbin_off;    /* offset from beginning of this hbin block */
     532
     533  /** Offset of this record from beginning of this hbin block */
     534  uint32_t hbin_off;
    383535 
     536  /** Offset of the previous SK record in the linked list of SK records */
    384537  uint32_t prev_sk_off;
     538
     539  /** Offset of the next SK record in the linked list of SK records */
    385540  uint32_t next_sk_off;
     541
     542  /** Number of keys referencing this SK record */
    386543  uint32_t ref_count;
    387   uint32_t desc_size;     /* size of security descriptor */
     544
     545  /** Size of security descriptor (sec_desc) */
     546  uint32_t desc_size;
     547
     548  /* XXX: A 2-byte field of unknown purpose */
    388549  uint16_t unknown_tag;
     550
     551  /** The magic number for this record (should be "sk") */
    389552  uint8_t  magic[REGFI_CELL_MAGIC_SIZE];
    390553} REGFI_SK_REC;
    391554
    392555
    393 /* Key Name */
     556/** Key structure
     557 * @ingroup regfiBase
     558 */
    394559typedef struct
    395560{
    396   uint32_t offset;      /* Real offset of this record's cell in the file */
    397   uint32_t cell_size;   /* Actual or estimated length of the cell. 
    398                          * Always in multiples of 8.
    399                          */
    400 
    401   /* link in the other records here */
     561  /** Real offset of this record's cell in the file */
     562  uint32_t offset;
     563
     564  /** Actual or estimated length of the cell. 
     565   * Always in multiples of 8.
     566   */
     567  uint32_t cell_size;
     568
     569  /** Preloaded value-list for this key.
     570   * This element is loaded automatically when using the iterator interface and
     571   * possibly some lower layer interfaces.
     572   */
    402573  REGFI_VALUE_LIST* values;
     574
     575
     576  /** Preloaded subkey-list for this key.
     577   * This element is loaded automatically when using the iterator interface and
     578   * possibly some lower layer interfaces.
     579   */
    403580  REGFI_SUBKEY_LIST* subkeys;
    404581 
    405   /* header information */
     582  /** Key flags */
    406583  uint16_t flags;
     584
     585  /** Magic number of key (should be "nk") */
    407586  uint8_t  magic[REGFI_CELL_MAGIC_SIZE];
     587
     588  /** Key's last modification time */
    408589  REGFI_NTTIME mtime;
     590
     591  /** Length of keyname_raw */
    409592  uint16_t name_length;
     593
     594  /** Length of referenced classname */
    410595  uint16_t classname_length;
     596
     597  /** The name of this key converted to desired REGFI_ENCODING. 
     598   *
     599   * This conversion typically occurs automatically through REGFI_ITERATOR
     600   * settings.  String is NUL terminated.
     601   */
    411602  char* keyname;
     603
     604  /** The raw key name
     605   *
     606   * Length of the buffer is stored in name_length.
     607   */
    412608  uint8_t* keyname_raw;
    413   uint32_t parent_off;              /* pointer to parent key */
     609
     610  /** Virutal offset of parent key */
     611  uint32_t parent_off;
     612
     613  /** Virutal offset of classname key */
    414614  uint32_t classname_off;
    415615 
    416   /* max lengths */
    417   uint32_t max_bytes_subkeyname;            /* max subkey name * 2 */
    418   uint32_t max_bytes_subkeyclassname; /* max subkey classname length (as if) */
    419   uint32_t max_bytes_valuename;     /* max valuename * 2 */
    420   uint32_t max_bytes_value;           /* max value data size */
     616  /* XXX: max subkey name * 2 */
     617  uint32_t max_bytes_subkeyname;
     618
     619  /* XXX: max subkey classname length (as if) */
     620  uint32_t max_bytes_subkeyclassname;
     621
     622  /* XXX: max valuename * 2 */
     623  uint32_t max_bytes_valuename;
     624
     625  /* XXX: max value data size */
     626  uint32_t max_bytes_value;
    421627 
    422   /* unknowns */
     628  /* XXX: Fields of unknown purpose */
    423629  uint32_t unknown1;
    424630  uint32_t unknown2;
    … …  
    426632  uint32_t unk_index;               /* nigel says run time index ? */
    427633 
    428   /* children */
     634  /** Number of subkeys */
    429635  uint32_t num_subkeys;
    430   uint32_t subkeys_off; /* offset of subkey list that points to NK records */
     636
     637  /** Virtual offset of subkey-list */
     638  uint32_t subkeys_off;
     639
     640  /** Number of values for this key */
    431641  uint32_t num_values;
    432   uint32_t values_off;  /* value lists which point to VK records */
    433   uint32_t sk_off;      /* offset to SK record */
     642
     643  /** Virtual offset of value-list */
     644  uint32_t values_off;
     645
     646  /** Virtual offset of SK record */
     647  uint32_t sk_off;
    434648} REGFI_NK_REC;
    435649
    436650
    437651
    438 /* REGF block */
     652/** Registry hive file data structure
     653 *
     654 * This essential structure stores run-time information about a single open
     655 * registry hive as well as file header (REGF block) data.  This structure
     656 * also stores a list of warnings and error messages generated while parsing
     657 * the registry hive.  These can be tuned using @ref regfi_set_message_mask. 
     658 * Messages may be retrieved using @ref regfi_get_messages.
     659 *
     660 * @note If the message mask is set to record any messages, dependent code
     661 *       must use @ref regfi_get_messages periodically to clear the message
     662 *       queue. Otherwise, this structure will grow in size over time as
     663 *       messages queue up.
     664 *
     665 * @ingroup regfiBase
     666 */
    439667typedef struct
    440668{
    … …  
    513741
    514742
     743/** Registry hive iterator
     744 * @ingroup regfiIteratorLayer
     745 */
    515746typedef struct _regfi_iterator
    516747{
     748  /** The registry hive this iterator is associated with */
    517749  REGFI_FILE* f;
     750
     751  /** All current parent keys and associated iterator positions */
    518752  void_stack* key_positions;
     753
     754  /** The current key */
    519755  REGFI_NK_REC* cur_key;
     756
     757  /** The encoding that all strings are converted to as set during iterator
     758   *  creation.
     759   */
    520760  REGFI_ENCODING string_encoding;
     761
     762  /** Index of the current subkey */
    521763  uint32_t cur_subkey;
     764
     765  /** Index of the current value */
    522766  uint32_t cur_value;
    523767} REGFI_ITERATOR;
    … …  
    534778
    535779
     780/** General purpose buffer with stored length
     781 * @ingroup regfiBottomLayer
     782 */
    536783typedef struct _regfi_buffer
    537784{
    … …  
    541788
    542789
     790
    543791/******************************************************************************/
    544792/**
    545  * @defgroup regfiBase Base Functions: Usable with Any Layer
    546  *
    547  * These functions don't fit particularly well in any of the other layers or
    548  * are intended for use with any of the API layers.
     793 * @defgroup regfiBase Base Layer: Essential Functions and Data Structures
     794 *
     795 * These functions are either necessary for normal use of the regfi API or just
     796 * don't fit particularly well in any of the other layers.
    549797 */
    550798/******************************************************************************/
    551 
    552799
    553800/** Attempts to open a registry hive and allocate related data structures.
    … …  
    658905/******************************************************************************/
    659906/**
    660  * @defgroup regfiTopLayer Top Layer: Primary regfi Library Interface
     907 * @defgroup regfiIteratorLayer Iterator Layer: Primary regfi Library Interface
    661908 *
    662909 * This top layer of API functions provides an iterator interface which makes
    … …  
    681928 *         Must be free()d with regfi_iterator_free.
    682929 *
    683  * @ingroup regfiTopLayer
     930 * @ingroup regfiIteratorLayer
    684931 */
    685932REGFI_ITERATOR*       regfi_iterator_new(REGFI_FILE* file,
    … …  
    693940 * @param i the iterator to be freed
    694941 *
    695  * @ingroup regfiTopLayer
     942 * @ingroup regfiIteratorLayer
    696943 */
    697944void                  regfi_iterator_free(REGFI_ITERATOR* i);
    … …  
    709956 *          depth-first iteration particularly easy.
    710957 *
    711  * @ingroup regfiTopLayer
     958 * @ingroup regfiIteratorLayer
    712959 */
    713960bool                  regfi_iterator_down(REGFI_ITERATOR* i);
    … …  
    721968 *          associated with the current key is lost.
    722969 *
    723  * @ingroup regfiTopLayer
     970 * @ingroup regfiIteratorLayer
    724971 */
    725972bool                  regfi_iterator_up(REGFI_ITERATOR* i);
    … …  
    732979 * @return true on success, false on failure.
    733980 *
    734  * @ingroup regfiTopLayer
     981 * @ingroup regfiIteratorLayer
    735982 */
    736983bool                  regfi_iterator_to_root(REGFI_ITERATOR* i);
    … …  
    7531000 *                 in its original position.
    7541001 *
    755  * @ingroup regfiTopLayer
     1002 * @ingroup regfiIteratorLayer
    7561003 */
    7571004bool regfi_iterator_walk_path(REGFI_ITERATOR* i, const char** path);
    … …  
    7641011 * @return A read-only key structure for the current key, or NULL on failure.
    7651012 *
    766  * @ingroup regfiTopLayer
     1013 * @ingroup regfiIteratorLayer
    7671014 */
    7681015const REGFI_NK_REC*   regfi_iterator_cur_key(REGFI_ITERATOR* i);
    … …  
    7751022 * @return A read-only SK structure, or NULL on failure.
    7761023 *
    777  * @ingroup regfiTopLayer
     1024 * @ingroup regfiIteratorLayer
    7781025 */
    7791026const REGFI_SK_REC*   regfi_iterator_cur_sk(REGFI_ITERATOR* i);
    … …  
    7901037 *         regfi_free_key.
    7911038 *
    792  * @ingroup regfiTopLayer
     1039 * @ingroup regfiIteratorLayer
    7931040 */
    7941041REGFI_NK_REC*         regfi_iterator_first_subkey(REGFI_ITERATOR* i);
    … …  
    8031050 *         regfi_free_key.
    8041051 *
    805  * @ingroup regfiTopLayer
     1052 * @ingroup regfiIteratorLayer
    8061053 */
    8071054REGFI_NK_REC*         regfi_iterator_cur_subkey(REGFI_ITERATOR* i);
    … …  
    8161063 *         failure.  Newly allocated keys must be freed with regfi_free_key.
    8171064 *
    818  * @ingroup regfiTopLayer
     1065 * @ingroup regfiIteratorLayer
    8191066 */
    8201067REGFI_NK_REC*         regfi_iterator_next_subkey(REGFI_ITERATOR* i);
    … …  
    8301077 *         the subkey index remains at the same location as before the call.
    8311078 *
    832  * @ingroup regfiTopLayer
     1079 * @ingroup regfiIteratorLayer
    8331080 */
    8341081bool                  regfi_iterator_find_subkey(REGFI_ITERATOR* i,
    … …  
    8451092 *          regfi_free_value.
    8461093 *
    847  * @ingroup regfiTopLayer
     1094 * @ingroup regfiIteratorLayer
    8481095 */
    8491096REGFI_VK_REC*         regfi_iterator_first_value(REGFI_ITERATOR* i);
    … …  
    8581105 *         regfi_free_value.
    8591106 *
    860  * @ingroup regfiTopLayer
     1107 * @ingroup regfiIteratorLayer
    8611108 */
    8621109REGFI_VK_REC*         regfi_iterator_cur_value(REGFI_ITERATOR* i);
    … …  
    8711118 *          failure.  Newly allocated keys must be freed with regfi_free_value.
    8721119 *
    873  * @ingroup regfiTopLayer
     1120 * @ingroup regfiIteratorLayer
    8741121 */
    8751122REGFI_VK_REC*         regfi_iterator_next_value(REGFI_ITERATOR* i);
    … …  
    8851132 *         the value index remains at the same location as before the call.
    8861133 *
    887  * @ingroup regfiTopLayer
     1134 * @ingroup regfiIteratorLayer
    8881135 */
    8891136bool                  regfi_iterator_find_value(REGFI_ITERATOR* i,
    … …  
    8981145 *         Classname structures must be freed with regfi_free_classname.
    8991146 *
    900  * @ingroup regfiTopLayer
     1147 * @ingroup regfiIteratorLayer
    9011148 */
    9021149REGFI_CLASSNAME*      regfi_iterator_fetch_classname(REGFI_ITERATOR* i,
    … …  
    9121159 *         Data structures must be freed with regfi_free_data.
    9131160 *
    914  * @ingroup regfiTopLayer
     1161 * @ingroup regfiIteratorLayer
    9151162 */
    9161163REGFI_DATA*           regfi_iterator_fetch_data(REGFI_ITERATOR* i,
    … …  
    9211168/******************************************************************************/
    9221169/**
    923  * @defgroup regfiMiddleLayer Middle Layer: Logical Data Structure Loading
     1170 * @defgroup regfiGlueLayer Glue Layer: Logical Data Structure Loading
    9241171 */
    9251172/******************************************************************************/
    … …  
    9291176 * XXX: finish documenting
    9301177 *
    931  * @ingroup regfiMiddleLayer
     1178 * @ingroup regfiGlueLayer
    9321179 */
    9331180REGFI_NK_REC*         regfi_load_key(REGFI_FILE* file, uint32_t offset,
    … …  
    9401187 * XXX: finish documenting
    9411188 *
    942  * @ingroup regfiMiddleLayer
     1189 * @ingroup regfiGlueLayer
    9431190 */
    9441191REGFI_VK_REC*         regfi_load_value(REGFI_FILE* file, uint32_t offset,
    … …  
    9511198 * XXX: finish documenting
    9521199 *
    953  * @ingroup regfiMiddleLayer
     1200 * @ingroup regfiGlueLayer
    9541201 */
    9551202REGFI_SUBKEY_LIST*    regfi_load_subkeylist(REGFI_FILE* file, uint32_t offset,
    … …  
    9621209 * XXX: finish documenting
    9631210 *
    964  * @ingroup regfiMiddleLayer
     1211 * @ingroup regfiGlueLayer
    9651212 */
    9661213REGFI_VALUE_LIST*     regfi_load_valuelist(REGFI_FILE* file, uint32_t offset,
    … …  
    9741221 * XXX: finish documenting
    9751222 *
    976  * @ingroup regfiMiddleLayer
     1223 * @ingroup regfiGlueLayer
    9771224 */
    9781225REGFI_BUFFER          regfi_load_data(REGFI_FILE* file, uint32_t voffset,
    … …  
    9851232 * XXX: finish documenting
    9861233 *
    987  * @ingroup regfiMiddleLayer
     1234 * @ingroup regfiGlueLayer
    9881235 */
    9891236REGFI_BUFFER          regfi_load_big_data(REGFI_FILE* file, uint32_t offset,
    … …  
    9981245 * XXX: finish documenting
    9991246 *
    1000  * @ingroup regfiMiddleLayer
     1247 * @ingroup regfiGlueLayer
    10011248 */
    10021249bool                  regfi_interpret_data(REGFI_FILE* file,
    … …  
    10091256 * XXX: finish documenting
    10101257 *
    1011  * @ingroup regfiMiddleLayer
     1258 * @ingroup regfiGlueLayer
    10121259 */
    10131260void                  regfi_free_classname(REGFI_CLASSNAME* classname);
    … …  
    10181265 * XXX: finish documenting
    10191266 *
    1020  * @ingroup regfiMiddleLayer
     1267 * @ingroup regfiGlueLayer
    10211268 */
    10221269void                  regfi_free_data(REGFI_DATA* data);
    … …  
    10291276 * XXX: finish documenting
    10301277 *
    1031  * @ingroup regfiMiddleLayer
     1278 * @ingroup regfiGlueLayer
    10321279 */
    10331280const REGFI_SK_REC*   regfi_load_sk(REGFI_FILE* file, uint32_t offset,
    … …  
    10391286 * XXX: finish documenting
    10401287 *
    1041  * @ingroup regfiMiddleLayer
     1288 * @ingroup regfiGlueLayer
    10421289 */
    10431290const REGFI_HBIN*     regfi_lookup_hbin(REGFI_FILE* file, uint32_t offset);
    … …  
    10471294/******************************************************************************/
    10481295/**
    1049  * @defgroup regfiBottomLayer Bottom Layer: Direct Data Structure Access
     1296 * @defgroup regfiParseLayer Parsing Layer: Direct Data Structure Access
    10501297 */
    10511298/******************************************************************************/
    … …  
    10661313 * @return A newly allocated NK record structure, or NULL on failure.
    10671314 *
    1068  * @ingroup regfiBottomLayer
     1315 * @ingroup regfiParseLayer
    10691316 */
    10701317REGFI_NK_REC*         regfi_parse_nk(REGFI_FILE* file, uint32_t offset,
    … …  
    10761323 * XXX: finish documenting
    10771324 *
    1078  * @ingroup regfiBottomLayer
     1325 * @ingroup regfiParseLayer
    10791326 */
    10801327REGFI_SUBKEY_LIST*    regfi_parse_subkeylist(REGFI_FILE* file, uint32_t offset,
    … …  
    10861333 * XXX: finish documenting
    10871334 *
    1088  * @ingroup regfiBottomLayer
     1335 * @ingroup regfiParseLayer
    10891336 */
    10901337REGFI_VK_REC*         regfi_parse_vk(REGFI_FILE* file, uint32_t offset,
    … …  
    10961343 * XXX: finish documenting
    10971344 *
    1098  * @ingroup regfiBottomLayer
     1345 * @ingroup regfiParseLayer
    10991346 */
    11001347REGFI_SK_REC*         regfi_parse_sk(REGFI_FILE* file, uint32_t offset,
    … …  
    11091356 * XXX: finish documenting
    11101357 *
    1111  * @ingroup regfiBottomLayer
     1358 * @ingroup regfiParseLayer
    11121359 */
    11131360range_list*           regfi_parse_unalloc_cells(REGFI_FILE* file);
    … …  
    11181365 * XXX: finish documenting
    11191366 *
    1120  * @ingroup regfiBottomLayer
     1367 * @ingroup regfiParseLayer
    11211368 */
    11221369bool                  regfi_parse_cell(int fd, uint32_t offset,
    … …  
    11291376 * XXX: finish documenting
    11301377 *
    1131  * @ingroup regfiBottomLayer
     1378 * @ingroup regfiParseLayer
    11321379 */
    11331380uint8_t*                regfi_parse_classname(REGFI_FILE* file, uint32_t offset,
    … …  
    11401387 * XXX: finish documenting
    11411388 *
    1142  * @ingroup regfiBottomLayer
     1389 * @ingroup regfiParseLayer
    11431390 */
    11441391REGFI_BUFFER          regfi_parse_data(REGFI_FILE* file, uint32_t offset,
    … …  
    11511398 * XXX: finish documenting
    11521399 *
    1153  * @ingroup regfiBottomLayer
     1400 * @ingroup regfiParseLayer
    11541401 */
    11551402REGFI_BUFFER          regfi_parse_little_data(REGFI_FILE* file, uint32_t voffset,
    … …  
    11631410                                    REGFI_ENCODING output_encoding);
    11641411void                  regfi_subkeylist_free(REGFI_SUBKEY_LIST* list);
    1165 uint32_t                regfi_read(int fd, uint8_t* buf, uint32_t* length);
     1412uint32_t              regfi_read(int fd, uint8_t* buf, uint32_t* length);
    11661413
    11671414const char*           regfi_type_val2str(unsigned int val);

  • trunk/include/void_stack.h

    r168 r169  
    1 /**
    2  * @file
    3  *
    4  * Copyright (C) 2005,2007,2009 Timothy D. Morgan
     1/*
     2 * Copyright (C) 2005,2007,2009-2010 Timothy D. Morgan
    53 *
    64 * This program is free software; you can redistribute it and/or modify
    … …  
    2018 */
    2119
     20/**
     21 *@file
     22 *
     23 * This is a very simple implementation of a stack which stores chunks of
     24 * memory of any type.
     25 */
     26
     27
    2228#ifndef _VOID_STACK_H
    2329#define _VOID_STACK_H
    … …  
    2834#include "talloc.h"
    2935
     36/** XXX: document this. */
    3037typedef struct _void_stack
    3138{
    … …  
    3542} void_stack;
    3643
     44
     45/** XXX: document this. */
    3746typedef struct _void_stack_iterator
    3847{
    … …  
    4251
    4352
    44 /* void_stack_new():
    45  *  Allocates a new void_stack.
     53/** Allocates a new void_stack.
    4654 *
    47  * Arguments:
    48  *  max_size -- the maxiumum number of elements
    49  *              which may be pushed onto the stack.
     55 * @param max_size the maxiumum number of elements
     56 *                 which may be pushed onto the stack.
    5057 *
    51  * Returns:
    52  *  a pointer to the newly allocated void_stack, or NULL if an error occurred.
     58 * @return a pointer to the newly allocated void_stack,
     59 *        or NULL if an error occurred.
    5360 */
    5461void_stack* void_stack_new(unsigned short max_size);
    5562
    5663
    57 /* void_stack_copy():
    58  *  Makes a shallow copy of void_stack.
     64/** Makes a shallow copy of void_stack.
    5965 *
    60  * Arguments:
    61  *  v -- the stack to make a copy of.
     66 * @param v the stack to make a copy of.
    6267 *
    63  * Returns:
    64  *  a pointer to the duplicate void_stack, or NULL If an error occurred.
     68 * @return a pointer to the duplicate void_stack, or NULL if an error occurred.
    6569 */
    6670void_stack* void_stack_copy(const void_stack* v);
    6771
    6872
    69 /* void_stack_copy_reverse():
    70  *  Makes a shallow copy of void_stack in reverse order.
     73/** Makes a shallow copy of void_stack in reverse order.
    7174 *
    72  * Arguments:
    73  *  v -- the stack to make a copy of.
     75 * @param v the stack to make a copy of.
    7476 *
    75  * Returns:
    76  *  a pointer to the duplicate void_stack (which will be in reverse order),
    77  *  or NULL If an error occurred.
     77 * @return a pointer to the duplicate void_stack
     78 *         (which will be in reverse order), or NULL if an error occurred.
    7879 */
    7980void_stack* void_stack_copy_reverse(const void_stack* v);
    8081
    8182
    82 /* void_stack_free():
    83  *  Frees the memory associated with a void_stack, but not the elements held
     83/** Frees the memory associated with a void_stack, but not the elements held
    8484 *  on the stack.
    8585 *
    86  * Arguments:
    87  *  stack -- the stack to be free()d.
     86 * @param stack the stack to be free()d.
    8887 */
    8988void void_stack_free(void_stack* stack);
    9089
    9190
    92 /* void_stack_free_deep():
    93  *  Frees the memory associated with a void_stack and the elements referenced
    94  *  by the stack.  Do not use this function if the elements of the stack
    95  *  are also free()d elsewhere, or contain pointers to other memory which
    96  *  cannot be otherwise free()d.
     91/** Frees the memory associated with a void_stack and the elements referenced
     92 *  by the stack. 
    9793 *
    98  * Arguments:
    99  *  stack -- the stack to be free()d.
     94 * Do not use this function if the elements of the stack
     95 * are also free()d elsewhere, or contain pointers to other memory which
     96 * cannot be otherwise free()d.
     97 *
     98 * @param stack the stack to be free()d.
    10099 */
    101100void void_stack_free_deep(void_stack* stack);
    102101
    103102
    104 /* void_stack_size():
    105  *  Query the current number of elements on a void_stack()
     103/** Query the current number of elements on a void_stack()
    106104 *
    107  * Arguments:
    108  *  stack -- the void_stack to query
     105 * @param stack the void_stack to query
    109106 *
    110  * Returns:
    111  *  the number of elements currently on the stack.
     107 * @return the number of elements currently on the stack.
    112108 */
    113109unsigned short void_stack_size(const void_stack* stack);
    114110
    115111
    116 /* void_stack_pop():
    117  *  Removes the top element on a void_stack and returns a reference to it.
     112/** Removes the top element on a void_stack and returns a reference to it.
    118113 *
    119  * Arguments:
    120  *  stack -- the void_stack to pop
     114 * @param stack the void_stack to pop
    121115 *
    122  * Returns:
    123  *  a pointer to the popped stack element, or NULL if no elements exist on
    124  *  the stack.
     116 * @return a pointer to the popped stack element, or NULL if no elements exist
     117 *         on the stack.
    125118 */
    126119void* void_stack_pop(void_stack* stack);
    127120
    128121
    129 /* void_stack_push():
    130  *  Puts a new element on the top of a void_stack.
     122/** Puts a new element on the top of a void_stack.
    131123 *
    132  * Arguments:
    133  *  stack -- the void_stack being modified.
     124 * @param stack the void_stack being modified.
     125 * @param e the element to be added
    134126 *
    135  *  e     -- the element to be added
    136  *
    137  * Returns:
    138  *  true if the element was successfully added, false otherwise.
     127 * @return true if the element was successfully added, false otherwise.
    139128 */
    140129bool void_stack_push(void_stack* stack, void* e);
    141130
    142131
    143 /* void_stack_cur():
    144  *  Returns a pointer to the current element on the top of the stack.
     132/** Returns a pointer to the current element on the top of the stack.
    145133 *
    146  * Arguments:
    147  *  stack -- the void_stack being queried.
     134 * @param stack the void_stack being queried.
    148135 *
    149  * Returns:
    150  *  a pointer to the current element on the top of the stack, or NULL if no
    151  *  elements exist in the stack.
     136 * @return a pointer to the current element on the top of the stack, or NULL if
     137 *         no elements exist in the stack.
    152138 */
    153139const void* void_stack_cur(const void_stack* stack);
    154140
    155141
    156 /* void_stack_iterator_new():
    157  *  Creates a new iterator for the specified void_stack.
     142/** Creates a new iterator for the specified void_stack.
    158143 *
    159  * Arguments:
    160  *  stack -- the void_stack to be referenced by the new iterator
     144 * @param stack the void_stack to be referenced by the new iterator
    161145 *
    162  * Returns:
    163  *  a new void_stack_iterator, or NULL if an error occurred.
     146 * @return a new void_stack_iterator, or NULL if an error occurred.
    164147 */
    165148void_stack_iterator* void_stack_iterator_new(const void_stack* stack);
    166149
    167150
    168 /* void_stack_iterator_free():
    169  *  Frees a void_stack_iterator.  Does not affect the void_stack referenced
    170  *  by the iterator.
     151/** Frees a void_stack_iterator.
    171152 *
    172  * Arguments:
    173  *  iter -- the void_stack_iterator to be free()d.
     153 * Does not affect the void_stack referenced by the iterator.
     154 *
     155 * @param iter the void_stack_iterator to be free()d.
    174156 */
    175157void void_stack_iterator_free(void_stack_iterator* iter);
    176158
    177159
    178 /* void_stack_iterator_next():
    179  *  Returns a pointer to the the next element in the stack.  Iterates over
    180  *  elements starting in order from the oldest element (bottom of the stack).
     160/** Returns a pointer to the the next element in the stack.
    181161 *
    182  * Arguments:
    183  *  iter -- the void_stack_iterator used to lookup the next element.
     162 * Iterates over elements starting in order from the oldest element (bottom of the stack).
    184163 *
    185  * Returns:
    186  *  a pointer to the next element.
     164 * @param iter the void_stack_iterator used to lookup the next element.
     165 *
     166 * @return a pointer to the next element.
    187167 */
    188168const void* void_stack_iterator_next(void_stack_iterator* iter);

  • trunk/include/winsec.h

    r168 r169  
    1 /** @file
    2  * This file contains refactored Samba code used to interpret Windows
    3  * Security Descriptors. See:
    4  *   http://websvn.samba.org/cgi-bin/viewcvs.cgi/trunk/source/
    5  *
    6  * Revisions have been made based on information provided by Microsoft
    7  * at:
    8  *    http://msdn.microsoft.com/en-us/library/cc230366(PROT.10).aspx
    9  *
    10  * Copyright (C) 2005,2009 Timothy D. Morgan
     1/*
     2 * Copyright (C) 2005,2009-2010 Timothy D. Morgan
    113 * Copyright (C) 1992-2005 Samba development team
    124 *
    … …  
    2719 */
    2820
     21/**
     22 * @file
     23 *
     24 * A small library for interpreting Windows Security Descriptors.
     25 * This library was originally based on Samba source from:
     26 *   http://websvn.samba.org/cgi-bin/viewcvs.cgi/trunk/source/
     27 *
     28 * The library has been heavily rewritten and improved based on information
     29 * provided by Microsoft at:
     30 *    http://msdn.microsoft.com/en-us/library/cc230366%28PROT.10%29.aspx
     31 */
     32
    2933#ifndef _WINSEC_H
    3034#define _WINSEC_H
    … …  
    7074
    7175
     76/** XXX: document this. */
    7277typedef struct _winsec_uuid
    7378{
    74        uint32_t time_low;
    75        uint16_t time_mid;
    76        uint16_t time_hi_and_version;
    77        uint8_t  clock_seq[2];
    78        uint8_t  node[6];
     79  /** XXX: document this. */
     80  uint32_t time_low;
     81
     82  /** XXX: document this. */
     83  uint16_t time_mid;
     84
     85  /** XXX: document this. */
     86  uint16_t time_hi_and_version;
     87
     88  /** XXX: document this. */
     89  uint8_t  clock_seq[2];
     90
     91  /** XXX: document this. */
     92  uint8_t  node[6];
    7993} WINSEC_UUID;
    8094
    8195
     96/** XXX: document this. */
    8297typedef struct _winsec_sid
    8398{
    84   uint8_t  sid_rev_num;             /* SID revision number */
    85   uint8_t  num_auths;               /* Number of sub-authorities */
    86   uint8_t  id_auth[6];              /* Identifier Authority */
    87   /*
    88    *  Pointer to sub-authorities.
    89    *
     99  /** SID revision number */
     100  uint8_t  sid_rev_num;
     101
     102  /** Number of sub-authorities */
     103  uint8_t  num_auths;
     104
     105  /** Identifier Authority */
     106  uint8_t  id_auth[6];
     107
     108  /** Pointer to sub-authorities.
     109   *
    90110   * @note The values in these uint32_t's are in *native* byteorder, not
    91111   * neccessarily little-endian...... JRA.
    92112   */
    93   /* XXX: Make this dynamically allocated? */
    94   uint32_t sub_auths[WINSEC_MAX_SUBAUTHS];
     113  uint32_t sub_auths[WINSEC_MAX_SUBAUTHS];   /* XXX: Make this dynamically allocated? */
    95114} WINSEC_DOM_SID;
    96115
    97116
     117/** XXX: document this. */
    98118typedef struct _winsec_ace
    99119{
    100         uint8_t type;  /* xxxx_xxxx_ACE_TYPE - e.g allowed / denied etc */
    101         uint8_t flags; /* xxxx_INHERIT_xxxx - e.g OBJECT_INHERIT_ACE */
    102         uint16_t size;
    103         uint32_t access_mask;
    104 
    105         /* this stuff may be present when type is XXXX_TYPE_XXXX_OBJECT */
    106         uint32_t  obj_flags;   /* xxxx_ACE_OBJECT_xxxx e.g present/inherited present etc */
    107         WINSEC_UUID* obj_guid;  /* object GUID */
    108         WINSEC_UUID* inh_guid;  /* inherited object GUID */             
    109         /* eof object stuff */
    110 
    111         WINSEC_DOM_SID* trustee;
     120  /** xxxx_xxxx_ACE_TYPE - e.g allowed / denied etc */
     121  uint8_t type;
     122
     123  /** xxxx_INHERIT_xxxx - e.g OBJECT_INHERIT_ACE */
     124  uint8_t flags;
     125
     126  /** XXX: finish documenting */
     127  uint16_t size;
     128
     129  /** XXX: finish documenting */
     130  uint32_t access_mask;
     131 
     132  /* This stuff may be present when type is XXXX_TYPE_XXXX_OBJECT */
     133
     134  /** xxxx_ACE_OBJECT_xxxx e.g present/inherited present etc */
     135  uint32_t  obj_flags;
     136
     137  /** Object GUID */
     138  WINSEC_UUID* obj_guid;
     139
     140  /** Inherited object GUID */
     141  WINSEC_UUID* inh_guid;
     142
     143  /* eof object stuff */
     144 
     145  /** XXX: finish documenting */
     146  WINSEC_DOM_SID* trustee;
    112147
    113148} WINSEC_ACE;
    114149
     150
     151/** XXX: document this. */
    115152typedef struct _winsec_acl
    116153{
    117         uint16_t revision; /* 0x0003 */
    118         uint16_t size;     /* size in bytes of the entire ACL structure */
    119         uint32_t num_aces; /* number of Access Control Entries */
    120 
    121         WINSEC_ACE** aces;
     154  /** 0x0003 */
     155  uint16_t revision;
     156
     157  /** Size, in bytes, of the entire ACL structure */
     158  uint16_t size;
     159
     160  /** Number of Access Control Entries */
     161  uint32_t num_aces;
     162 
     163  /** XXX: document this. */
     164  WINSEC_ACE** aces;
    122165
    123166} WINSEC_ACL;
    124167
     168
     169/** XXX: document this. */
    125170typedef struct _winsec_desc
    126171{
    127         uint8_t revision; /* 0x01 */
    128         uint8_t sbz1;     /* "If the Control field has the RM flag set,
    129                            *  then this field contains the resource
    130                            *  manager (RM) control value. ... Otherwise,
    131                            *  this field is reserved and MUST be set to
    132                            *  zero." -- Microsoft.  See reference above.
    133                            */
    134         uint16_t control; /* WINSEC_DESC_* flags */
    135 
    136         uint32_t off_owner_sid; /* offset to owner sid */
    137         uint32_t off_grp_sid  ; /* offset to group sid */
    138         uint32_t off_sacl     ; /* offset to system list of permissions */
    139         uint32_t off_dacl     ; /* offset to list of permissions */
    140 
    141         WINSEC_DOM_SID* owner_sid;
    142         WINSEC_DOM_SID* grp_sid;
    143         WINSEC_ACL* sacl;       /* system ACL */
    144         WINSEC_ACL* dacl;       /* user ACL */
     172  /** 0x01 */
     173  uint8_t revision;
     174
     175  /** XXX: better explain this
     176   *
     177   * "If the Control field has the RM flag set, then this field contains the
     178   *  resource manager (RM) control value. ... Otherwise, this field is reserved
     179   *  and MUST be set to zero." -- Microsoft.
     180   *  See:
     181   *   http://msdn.microsoft.com/en-us/library/cc230371%28PROT.10%29.aspx
     182   */
     183  uint8_t sbz1;
     184
     185  /** WINSEC_DESC_* flags */
     186  uint16_t control;
     187 
     188  /** Offset to owner sid */
     189  uint32_t off_owner_sid;
     190
     191  /** Offset to group sid */
     192  uint32_t off_grp_sid;
     193
     194  /** Offset to system list of permissions */
     195  uint32_t off_sacl;
     196
     197  /** Offset to list of permissions */
     198  uint32_t off_dacl;
     199
     200  /** XXX: document this */
     201  WINSEC_DOM_SID* owner_sid;
     202
     203  /** XXX: document this */
     204  WINSEC_DOM_SID* grp_sid;
     205
     206  /** System ACL */
     207  WINSEC_ACL* sacl;
     208
     209  /** User ACL */
     210  WINSEC_ACL* dacl;
    145211
    146212} WINSEC_DESC;
    147213
     214
     215/**
     216 *
     217 * XXX: finish documenting
     218 */
    148219WINSEC_DESC* winsec_parse_descriptor(const uint8_t* buf, uint32_t buf_len);
     220
     221
     222/**
     223 *
     224 * XXX: finish documenting
     225 */
    149226void winsec_free_descriptor(WINSEC_DESC* desc);
    150227
     228/**
     229 *
     230 * XXX: finish documenting
     231 */
    151232WINSEC_DESC* winsec_parse_desc(void* talloc_ctx,
    152233                               const uint8_t* buf, uint32_t buf_len);
     234
     235/**
     236 *
     237 * XXX: finish documenting
     238 */
    153239WINSEC_ACL* winsec_parse_acl(void* talloc_ctx,
    154240                             const uint8_t* buf, uint32_t buf_len);
     241
     242/**
     243 *
     244 * XXX: finish documenting
     245 */
    155246WINSEC_ACE* winsec_parse_ace(void* talloc_ctx,
    156247                             const uint8_t* buf, uint32_t buf_len);
     248
     249/**
     250 *
     251 * XXX: finish documenting
     252 */
    157253WINSEC_DOM_SID* winsec_parse_dom_sid(void* talloc_ctx,
    158254                                     const uint8_t* buf, uint32_t buf_len);
     255
     256/**
     257 *
     258 * XXX: finish documenting
     259 */
    159260WINSEC_UUID* winsec_parse_uuid(void* talloc_ctx,
    160261                               const uint8_t* buf, uint32_t buf_len);
    161262
     263
     264/**
     265 *
     266 * XXX: finish documenting
     267 */
    162268size_t winsec_sid_size(const WINSEC_DOM_SID* sid);
     269
     270/**
     271 *
     272 * XXX: finish documenting
     273 */
    163274int winsec_sid_compare_auth(const WINSEC_DOM_SID* sid1, const WINSEC_DOM_SID* sid2);
     275
     276/**
     277 *
     278 * XXX: finish documenting
     279 */
    164280int winsec_sid_compare(const WINSEC_DOM_SID* sid1, const WINSEC_DOM_SID* sid2);
     281
     282/**
     283 *
     284 * XXX: finish documenting
     285 */
    165286bool winsec_sid_equal(const WINSEC_DOM_SID* sid1, const WINSEC_DOM_SID* sid2);
     287
     288/**
     289 *
     290 * XXX: finish documenting
     291 */
    166292bool winsec_desc_equal(WINSEC_DESC* s1, WINSEC_DESC* s2);
     293
     294/**
     295 *
     296 * XXX: finish documenting
     297 */
    167298bool winsec_acl_equal(WINSEC_ACL* s1, WINSEC_ACL* s2);
     299
     300/**
     301 *
     302 * XXX: finish documenting
     303 */
    168304bool winsec_ace_equal(WINSEC_ACE* s1, WINSEC_ACE* s2);
     305
     306/**
     307 *
     308 * XXX: finish documenting
     309 */
    169310bool winsec_ace_object(uint8_t type);
    170311
Note: See TracChangeset for help on using the changeset viewer.