Changeset 169 for trunk/include/winsec.h


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

filled in additional, minimal documentation

File:
1 edited

Legend:

Unmodified
Added
Removed

  • 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.