source: trunk/include/regfi.h @ 226

Last change on this file since 226 was 226, checked in by tim, 13 years ago

several fixes for pyregfi Windows portability
better error handling within pyregfi

  • Property svn:keywords set to Id
File size: 47.2 KB
RevLine 
[169]1/*
[168]2 * Copyright (C) 2005-2010 Timothy D. Morgan
[193]3 * Copyright (C) 2010 Michael Cohen
[30]4 * Copyright (C) 2005 Gerald (Jerry) Carter
5 *
6 * This program is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
[134]8 * the Free Software Foundation; version 3 of the License.
[30]9 *
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13 * GNU General Public License for more details.
14 *
15 * You should have received a copy of the GNU General Public License
16 * along with this program; if not, write to the Free Software
17 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
18 *
19 * $Id: regfi.h 226 2011-04-05 19:01:41Z tim $
20 */
21
[169]22/**
23 * @file
24 * Windows NT (and later) read-only registry library
25 *
26 * This library is intended for use in digital forensics investigations, but
27 * is likely useful in other applications.
28 *
29 * Branched from Samba project Subversion repository, version #6903:
30 *   http://viewcvs.samba.org/cgi-bin/viewcvs.cgi/trunk/source/include/regfio.h?rev=6903&view=auto
31 *
32 * Since then, it has been heavily rewritten, simplified, and improved.
33 */
[30]34
[168]35/**
36 * @mainpage Home
37 *
[169]38 * The regfi library is a read-only NT registry library which serves as the main
39 * engine behind the reglookup tool.  It is designed with digital forensic
40 * analysis in mind, but it should also be useful in other tools which need to
41 * efficiently traverse and query registry data structures.
42 *
43 * The library is broken down into four main parts, the
44 * @ref regfiBase "Base Layer", which any code dependent on the library will
45 * likely need to rely on, as well as three main functional layers:
46 * @li @ref regfiIteratorLayer
47 * @li @ref regfiGlueLayer
48 * @li @ref regfiParseLayer
49 *
50 * Most users will find that a combination of the Base Layer and the Iterator Layer
[185]51 * will be sufficient for accessing registry hive files.  Those who are willing
[169]52 * to dive deep into registry data structures, for instance to recover deleted
53 * data structures or to research Windows registry behavior in detail, will
54 * find the Parse Layer to be quite useful.
[168]55 */
56
[169]57
[78]58#ifndef _REGFI_H
59#define _REGFI_H
[30]60
[31]61#include <stdlib.h>
62#include <stdio.h>
[30]63#include <stdbool.h>
[31]64#include <string.h>
[30]65#include <errno.h>
[31]66#include <time.h>
[30]67#include <fcntl.h>
68#include <sys/stat.h>
69#include <sys/types.h>
70#include <unistd.h>
[159]71#include <iconv.h>
[180]72#include <pthread.h>
[201]73#include <talloc.h>
[30]74
[193]75/* regfi headers */
76#include <byteorder.h>
77#include <winsec.h>
78#include <void_stack.h>
79#include <range_list.h>
80#include <lru_cache.h>
[30]81
[201]82/* GCC-specific macro for library exports */
83#ifdef _EXPORT
84#undef _EXPORT
85#endif
[226]86#ifdef REGFI_WIN32
87#define _EXPORT __declspec(dllexport)
88#else
[201]89#define _EXPORT __attribute__((visibility("default")))
[226]90#endif
[184]91
[226]92#ifndef EOVERFLOW
93# define EOVERFLOW E2BIG
94#endif
[185]95
[30]96/******************************************************************************/
[184]97/* Constants for use while interacting with the library                       */
98/******************************************************************************/
[138]99
100/* regfi library error message types */
[182]101#define REGFI_LOG_INFO  0x0001
102#define REGFI_LOG_WARN  0x0004
103#define REGFI_LOG_ERROR 0x0010
[185]104#define REGFI_DEFAULT_LOG_MASK REGFI_LOG_ERROR|REGFI_LOG_WARN
[138]105
[161]106/* regfi library supported character encodings */
107/* UTF16LE is not supported for output */
[193]108typedef enum {
109  REGFI_ENCODING_DEFAULT  = 0,
110  REGFI_ENCODING_ASCII =   0,
111  REGFI_ENCODING_UTF8  =  1,
112  REGFI_ENCODING_UTF16LE = 2,
113  REGFI_NUM_ENCODINGS  =  3
114} REGFI_ENCODING;
[161]115
[32]116/* Registry data types */
[193]117typedef enum {
118  REG_NONE                   =    0,
119  REG_SZ                     =    1,
120  REG_EXPAND_SZ              =    2,
121  REG_BINARY                 =    3,
122  REG_DWORD                  =    4,
123  REG_DWORD_LE               =    4 , /* DWORD, little endian */
124  REG_DWORD_BE               =    5 , /* DWORD, big endian */
125  REG_LINK                   =    6,
126  REG_MULTI_SZ               =    7,
127  REG_RESOURCE_LIST          =    8,
128  REG_FULL_RESOURCE_DESCRIPTOR=   9,
129  REG_RESOURCE_REQUIREMENTS_LIST= 10,
130  REG_QWORD                     = 11, /* 64-bit little endian */
[72]131/* XXX: Has MS defined a REG_QWORD_BE? */
[32]132/* Not a real type in the registry */
[193]133  REG_KEY                 =   0x7FFFFFFF
134} REGFI_DATA_TYPE;
[135]135#define REGFI_OFFSET_NONE          0xffffffff
[30]136
[165]137
[184]138
139/******************************************************************************/
140/* Various resource limits and related constants                              */
141/******************************************************************************/
142
143/* Flags determining whether or not to cache various record types internally */
144#define REGFI_CACHE_SK             0
145
[165]146/* This maximum depth is described here:
147 * http://msdn.microsoft.com/en-us/library/ms724872%28VS.85%29.aspx
148 */
149#define REGFI_MAX_DEPTH            512
150
151/* This limit defines the maximum number of levels deep that ri subkey list
152 * trees can go.
153 */
154/* XXX: This is totally arbitrary right now.
155 *      The actual limit may need to be discovered by experimentation.
156 */
[149]157#define REGFI_MAX_SUBKEY_DEPTH     255
[139]158
[165]159
[184]160/******************************************************************************/
161/* Symbols for internal use                                                   */
162/******************************************************************************/
163
164/* Global thread-local storage key */
[185]165pthread_key_t regfi_log_key;
[184]166
[135]167/* Header sizes and magic number lengths for various records */
[147]168#define REGFI_HBIN_ALLOC           0x1000 /* Minimum allocation unit for HBINs */
169#define REGFI_REGF_SIZE            0x1000 /* "regf" header block size */
[135]170#define REGFI_REGF_MAGIC_SIZE      4
[151]171#define REGFI_REGF_NAME_SIZE       64
172#define REGFI_REGF_RESERVED1_SIZE  340
173#define REGFI_REGF_RESERVED2_SIZE  3528
[135]174#define REGFI_HBIN_MAGIC_SIZE      4
175#define REGFI_CELL_MAGIC_SIZE      2
176#define REGFI_HBIN_HEADER_SIZE     0x20
[116]177#define REGFI_NK_MIN_LENGTH        0x4C
178#define REGFI_VK_MIN_LENGTH        0x14
179#define REGFI_SK_MIN_LENGTH        0x14
[127]180#define REGFI_SUBKEY_LIST_MIN_LEN  0x4
[157]181#define REGFI_BIG_DATA_MIN_LENGTH  0xC
[30]182
[135]183
[116]184/* Constants used for validation */
[125]185/* XXX: Can we add clock resolution validation as well as range?  It has
186 *      been reported that Windows timestamps are never more than a
187 *      certain granularity (250ms?), which could be used to help
[147]188 *      eliminate false positives.  Would need to verify this and
[125]189 *      perhaps conservatively implement a check.
190 */
[116]191 /* Minimum time is Jan 1, 1990 00:00:00 */
192#define REGFI_MTIME_MIN_HIGH       0x01B41E6D
[178]193
[116]194 /* Maximum time is Jan 1, 2290 00:00:00
195  * (We hope no one is using Windows by then...)
196  */
197#define REGFI_MTIME_MAX_HIGH       0x03047543
[30]198
[116]199
[30]200/* Flags for the vk records */
[162]201#define REGFI_VK_FLAG_ASCIINAME    0x0001
[135]202#define REGFI_VK_DATA_IN_OFFSET    0x80000000
[152]203#define REGFI_VK_MAX_DATA_LENGTH   1024*1024  /* XXX: This is arbitrary */
[30]204
[137]205
[152]206/* Known key flags */
207/*******************/
[137]208/* These next two show up on normal-seeming keys in Vista and W2K3 registries */
209#define REGFI_NK_FLAG_UNKNOWN1     0x4000
210#define REGFI_NK_FLAG_UNKNOWN2     0x1000
[152]211
[167]212/* This next one shows up in some Vista "software" registries */
213/* XXX: This shows up in the following two SOFTWARE keys in Vista:
214 *   /Wow6432Node/Microsoft
215 *   /Wow6432Node/Microsoft/Cryptography
216 * 
217 * It comes along with UNKNOWN2 and ASCIINAME for a total flags value of 0x10A0
218 */
[137]219#define REGFI_NK_FLAG_UNKNOWN3     0x0080
[30]220
[152]221/* Predefined handle.  Rumor has it that the valuelist count for this key is
222 * where the handle is stored.
223 * http://msdn.microsoft.com/en-us/library/ms724836(VS.85).aspx
224 */
225#define REGFI_NK_FLAG_PREDEF_KEY   0x0040
[137]226
[152]227/* The name will be in ASCII if this next bit is set, otherwise UTF-16LE */
228#define REGFI_NK_FLAG_ASCIINAME    0x0020
229
230/* Symlink key. 
231 * See: http://www.codeproject.com/KB/system/regsymlink.aspx
232 */
233#define REGFI_NK_FLAG_LINK         0x0010
234
235/* This key cannot be deleted */
236#define REGFI_NK_FLAG_NO_RM        0x0008
237
238/* Root of a hive */
239#define REGFI_NK_FLAG_ROOT         0x0004
240
241/* Mount point of another hive.  NULL/(default) value indicates which hive
242 * and where in the hive it points to.
243 */
244#define REGFI_NK_FLAG_HIVE_LINK    0x0002
245
246/* These keys shouldn't be stored on disk, according to:
247 * http://geekswithblogs.net/sdorman/archive/2007/12/24/volatile-registry-keys.aspx
248 */
249#define REGFI_NK_FLAG_VOLATILE     0x0001
250
251/* Useful for identifying unknown flag types */
252#define REGFI_NK_KNOWN_FLAGS       (REGFI_NK_FLAG_PREDEF_KEY\
253                                    | REGFI_NK_FLAG_ASCIINAME\
254                                    | REGFI_NK_FLAG_LINK\
255                                    | REGFI_NK_FLAG_NO_RM\
256                                    | REGFI_NK_FLAG_ROOT\
257                                    | REGFI_NK_FLAG_HIVE_LINK\
258                                    | REGFI_NK_FLAG_VOLATILE\
259                                    | REGFI_NK_FLAG_UNKNOWN1\
[167]260                                    | REGFI_NK_FLAG_UNKNOWN2\
261                                    | REGFI_NK_FLAG_UNKNOWN3)
[152]262
[168]263
[193]264#ifndef CHAR_BIT
[168]265#define CHAR_BIT 8
[193]266#endif
267
[168]268#define TIME_T_MIN ((time_t)0 < (time_t) -1 ? (time_t) 0 \
269                    : ~ (time_t) 0 << (sizeof (time_t) * CHAR_BIT - 1))
270#define TIME_T_MAX (~ (time_t) 0 - TIME_T_MIN)
271#define TIME_FIXUP_CONSTANT (369.0*365.25*24*60*60-(3.0*24*60*60+6.0*60*60))
272
[184]273
274
275/******************************************************************************/
276/* Structures                                                                 */
277/******************************************************************************/
278
[168]279typedef struct _regfi_nttime
280{
281  uint32_t low;
282  uint32_t high;
283} REGFI_NTTIME;
284
285
[182]286typedef struct _regfi_log
287{
288  /* Error/warning/info messages returned by lower layer functions */
289  char* messages;
290
291  /* Mask for error message types that will be stored. */
292  uint16_t msg_mask;
293
294} REGFI_LOG;
295
296
[169]297/** HBIN block information
298 * @ingroup regfiMiddleLayer
299 */
[135]300typedef struct _regfi_hbin
[97]301{
[169]302  /** Offset of this HBIN in the registry file */
303  uint32_t file_off;
[97]304
[169]305  /** Number of active records pointing to this block (not used currently) */
306  uint32_t ref_count;
307
308  /** Offset from first hbin block */
309  uint32_t first_hbin_off;
310
311  /** Block size of this block Should be a multiple of 4096 (0x1000) */
312  uint32_t block_size;
313
314  /** Relative offset to next block. 
315   *
316   * @note This value may be unreliable!
317   */
318  uint32_t next_block;
319
320  /** Magic number for the HBIN (should be "hbin"). */
321  uint8_t magic[REGFI_HBIN_MAGIC_SIZE];
[135]322} REGFI_HBIN;
[30]323
[97]324
[127]325/* Subkey List -- list of key offsets and hashed names for consistency */
[97]326typedef struct 
327{
[139]328  /* Virtual offset of NK record or additional subkey list,
329   * depending on this list's type.
330   */
[168]331  uint32_t offset;
[139]332
[168]333  uint32_t hash;
[135]334} REGFI_SUBKEY_LIST_ELEM;
[30]335
[97]336
[169]337/** Subkey-list structure
338 * @ingroup regfiMiddleLayer
339 */
[145]340typedef struct _regfi_subkey_list
[97]341{
[139]342  /* Real offset of this record's cell in the file */
[168]343  uint32_t offset;
[139]344
[168]345  uint32_t cell_size;
[139]346 
347  /* Number of immediate children */
[202]348  uint32_t num_children;
[139]349
[202]350  /* Total number of keys referenced by this list and its children */
351  uint32_t num_keys;
[139]352
[135]353  REGFI_SUBKEY_LIST_ELEM* elements;
[168]354  uint8_t magic[REGFI_CELL_MAGIC_SIZE];
[139]355
356  /* Set if the magic indicates this subkey list points to child subkey lists */
[202]357  bool recursive_type;
[135]358} REGFI_SUBKEY_LIST;
[30]359
[97]360
[168]361typedef uint32_t REGFI_VALUE_LIST_ELEM;
[169]362/** Value-list structure
363 * @ingroup regfiMiddleLayer
364 */
[145]365typedef struct _regfi_value_list
366{
[206]367  /* Real offset of this record's cell in the file */
368  uint32_t offset;
369
370  uint32_t cell_size;
371
[145]372  /* Actual number of values referenced by this list. 
373   * May differ from parent key's num_values if there were parsing errors.
374   */
[168]375  uint32_t num_values;
[145]376
377  REGFI_VALUE_LIST_ELEM* elements;
378} REGFI_VALUE_LIST;
379
380
[169]381/** Class name structure (used in storing SysKeys)
382 * @ingroup regfiBase
383 */
[160]384typedef struct _regfi_classname
385{
[206]386  /** Real offset of this record's cell in the file */
387  uint32_t offset;
388
[169]389  /** As converted to requested REGFI_ENCODING */
[160]390  char* interpreted;
391
[169]392  /** Represents raw buffer read from classname cell.
393   *
394   * Length of this item is specified in the size field.
395   */
[168]396  uint8_t* raw;
[160]397
[169]398  /** Length of the raw data.
399   *
400   * May be shorter than that indicated by parent key.
401   */
[168]402  uint16_t size;
[160]403} REGFI_CLASSNAME;
404
405
[169]406/** Data record structure
407 * @ingroup regfiBase
408 */
[159]409typedef struct _regfi_data
410{
[209]411  /* XXX: this isn't populated yet. Should set it to start of data cell
412   *      or big data cell.
413   */
414  uint32_t offset;
415
[169]416  /** Data type of this data, as indicated by the referencing VK record. */
[193]417  REGFI_DATA_TYPE type;
[159]418
[169]419  /** Length of the raw data. */
[168]420  uint32_t size;
[159]421
[169]422  /** This is always present, representing the raw data cell contents. */
[168]423  uint8_t* raw;
[159]424
[209]425  /** Represents the length of the interpreted value. Meaning is type-specific.
426   *  Will be 0 if interpretation failed for any reason.
427   */
[168]428  uint32_t interpreted_size;
[159]429
[169]430  /** These items represent interpreted versions of the REGFI_DATA::raw field.
431   *
432   * Only use the appropriate member according to the REGFI_DATA::type field.
433   * In the event of an unknown type, use only the REGFI_DATA::raw field.
[159]434   */
435  union _regfi_data_interpreted
436  {
[169]437    /** REG_NONE
438     *
439     * Stored as a raw buffer.  Use REGFI_DATA::interpreted_size to determine
440     * length.
441     */
442    uint8_t* none; 
443
444    /** REG_SZ
445     *
446     * Stored as a NUL terminated string.  Converted to the specified
447     * REGFI_ENCODING.
448     */
[168]449    uint8_t* string;
[169]450
451    /** REG_EXPAND_SZ
452     *
453     * Stored as a NUL terminated string.  Converted to the specified
454     * REGFI_ENCODING.
455     */
[168]456    uint8_t* expand_string;
[169]457
458    /** REG_BINARY
459     *
460     * Stored as a raw buffer.  Use REGFI_DATA::interpreted_size to determine
461     * length.
462     */
463    uint8_t* binary;
464
465    /** REG_DWORD */
[168]466    uint32_t dword;
[169]467
468    /** REG_DWORD_BE */
[168]469    uint32_t dword_be;
[169]470
471    /** REG_LINK
472     *
473     * Stored as a NUL terminated string.  Converted to the specified
474     * REGFI_ENCODING.
475     */
[168]476    uint8_t* link;
[169]477
478    /** REG_MULTI_SZ
479     *
480     * Stored as a list of uint8_t* pointers, terminated with a NULL pointer.
481     * Each string element in the list is NUL terminated, and the character set
482     * is determined by the specified REGFI_ENCODING.
483     */
[168]484    uint8_t** multiple_string;
[169]485
486    /** REG_QWORD */
[168]487    uint64_t qword;
[159]488
489    /* The following are treated as binary currently, but this may change in
490     * the future as the formats become better understood.
491     */
[169]492
493    /** REG_RESOURCE_LIST
494     *
495     * Stored as a raw buffer.  Use REGFI_DATA::interpreted_size to determine
496     * length.
497     */
[168]498    uint8_t* resource_list;
[169]499
500    /** REG_FULL_RESOURCE_DESCRIPTOR
501     *
502     * Stored as a raw buffer.  Use REGFI_DATA::interpreted_size to determine
503     * length.
504     */
[168]505    uint8_t* full_resource_descriptor;
[169]506
507    /** REG_RESOURCE_REQUIREMENTS_LIST
508     *
509     * Stored as a raw buffer.  Use REGFI_DATA::interpreted_size to determine
510     * length.
511     */
[168]512    uint8_t* resource_requirements_list;
[159]513  } interpreted;
514} REGFI_DATA;
515
516
[169]517/** Value structure
518 * @ingroup regfiBase
519 */
[206]520typedef struct _regfi_vk
[97]521{
[169]522  /** Real offset of this record's cell in the file */
523  uint32_t offset;     
[101]524
[169]525  /** ((start_offset - end_offset) & 0xfffffff8) */
526  uint32_t cell_size;
[159]527
[169]528  /** The name of this value converted to desired REGFI_ENCODING. 
529   *
530   * This conversion typically occurs automatically through REGFI_ITERATOR
531   * settings.  String is NUL terminated.
532   */
[206]533  char* name;
[169]534
535  /** The raw value name
536   *
537   * Length of the buffer is stored in name_length.
538   */
[206]539  uint8_t* name_raw;
[169]540
[206]541  /** Length of name_raw */
[168]542  uint16_t name_length;
[169]543
544  /** Offset from beginning of this hbin block */
545  uint32_t hbin_off;
[53]546 
[169]547  /** Size of the value's data as reported in the VK record.
548   *
549   * May be different than that obtained while parsing the data cell itself.
550   */
551  uint32_t data_size;
552
553  /** Virtual offset of data cell */
554  uint32_t data_off;
555
556  /** Value's data type */
[193]557  REGFI_DATA_TYPE type;
[169]558
559  /** VK record's magic number (should be "vk") */
[168]560  uint8_t  magic[REGFI_CELL_MAGIC_SIZE];
[169]561
562  /** VK record flags */
[168]563  uint16_t flags;
[169]564
565  /* XXX: A 2-byte field of unknown purpose stored in the VK record */
[168]566  uint16_t unknown1;
[169]567
568  /** Whether or not the data record is stored in the VK record's data_off field.
569   *
570   * This information is derived from the high bit of the raw data size field.
571   */
572  bool     data_in_offset;
[206]573
574  /* XXX: deprecated */
575  REGFI_DATA* data;
576
[203]577} REGFI_VK;
[30]578
579
580/* Key Security */
[206]581struct _regfi_sk;
[30]582
[169]583/** Security structure
584 * @ingroup regfiBase
585 */
[206]586typedef struct _regfi_sk
[97]587{
[169]588  /** Real file offset of this record */
589  uint32_t offset;
[111]590
[169]591  /** ((start_offset - end_offset) & 0xfffffff8) */
592  uint32_t cell_size;
593
594  /** The stored Windows security descriptor for this SK record */
[134]595  WINSEC_DESC* sec_desc;
[169]596
597  /** Offset of this record from beginning of this hbin block */
598  uint32_t hbin_off;
[53]599 
[169]600  /** Offset of the previous SK record in the linked list of SK records */
[168]601  uint32_t prev_sk_off;
[169]602
603  /** Offset of the next SK record in the linked list of SK records */
[168]604  uint32_t next_sk_off;
[169]605
606  /** Number of keys referencing this SK record */
[168]607  uint32_t ref_count;
[169]608
609  /** Size of security descriptor (sec_desc) */
610  uint32_t desc_size;
611
612  /* XXX: A 2-byte field of unknown purpose */
[168]613  uint16_t unknown_tag;
[169]614
615  /** The magic number for this record (should be "sk") */
[168]616  uint8_t  magic[REGFI_CELL_MAGIC_SIZE];
[203]617} REGFI_SK;
[30]618
[81]619
[169]620/** Key structure
621 * @ingroup regfiBase
622 */
[206]623typedef struct _regfi_nk
[97]624{
[169]625  /** Real offset of this record's cell in the file */
626  uint32_t offset;
[84]627
[169]628  /** Actual or estimated length of the cell. 
629   * Always in multiples of 8.
630   */
631  uint32_t cell_size;
632
633  /** Preloaded value-list for this key.
634   * This element is loaded automatically when using the iterator interface and
635   * possibly some lower layer interfaces.
636   */
[145]637  REGFI_VALUE_LIST* values;
[169]638
639
640  /** Preloaded subkey-list for this key.
641   * This element is loaded automatically when using the iterator interface and
642   * possibly some lower layer interfaces.
643   */
[135]644  REGFI_SUBKEY_LIST* subkeys;
[53]645 
[169]646  /** Key flags */
[168]647  uint16_t flags;
[169]648
649  /** Magic number of key (should be "nk") */
[168]650  uint8_t  magic[REGFI_CELL_MAGIC_SIZE];
[169]651
652  /** Key's last modification time */
[168]653  REGFI_NTTIME mtime;
[169]654
655  /** Length of keyname_raw */
[168]656  uint16_t name_length;
[169]657
658  /** Length of referenced classname */
[168]659  uint16_t classname_length;
[169]660
661  /** The name of this key converted to desired REGFI_ENCODING. 
662   *
663   * This conversion typically occurs automatically through REGFI_ITERATOR
664   * settings.  String is NUL terminated.
665   */
[206]666  char* name;
[169]667
668  /** The raw key name
669   *
670   * Length of the buffer is stored in name_length.
671   */
[206]672  uint8_t* name_raw;
[169]673
[215]674  /** Virtual offset of parent key */
[169]675  uint32_t parent_off;
676
[215]677  /** Virtual offset of classname key */
[168]678  uint32_t classname_off;
[53]679 
[169]680  /* XXX: max subkey name * 2 */
681  uint32_t max_bytes_subkeyname;
682
683  /* XXX: max subkey classname length (as if) */
684  uint32_t max_bytes_subkeyclassname;
685
[206]686  /* XXX: max value name * 2 */
[169]687  uint32_t max_bytes_valuename;
688
689  /* XXX: max value data size */
690  uint32_t max_bytes_value;
[53]691 
[169]692  /* XXX: Fields of unknown purpose */
[168]693  uint32_t unknown1;
694  uint32_t unknown2;
695  uint32_t unknown3;
696  uint32_t unk_index;               /* nigel says run time index ? */
[53]697 
[169]698  /** Number of subkeys */
[168]699  uint32_t num_subkeys;
[169]700
701  /** Virtual offset of subkey-list */
702  uint32_t subkeys_off;
703
704  /** Number of values for this key */
[168]705  uint32_t num_values;
[169]706
707  /** Virtual offset of value-list */
708  uint32_t values_off;
709
710  /** Virtual offset of SK record */
711  uint32_t sk_off;
[203]712} REGFI_NK;
[30]713
[81]714
[178]715typedef struct _regfi_raw_file
716{
[226]717  int64_t  (* seek)(); /* (REGFI_RAW_FILE* self, uint64_t offset, int whence) */
[178]718  ssize_t  (* read)(); /* (REGFI_RAW_FILE* self, void* buf, size_t count) */
[97]719
[178]720  uint64_t cur_off;
721  uint64_t size;
722  void*    state;
723} REGFI_RAW_FILE;
724
725
[169]726/** Registry hive file data structure
727 *
728 * This essential structure stores run-time information about a single open
729 * registry hive as well as file header (REGF block) data.  This structure
730 * also stores a list of warnings and error messages generated while parsing
731 * the registry hive.  These can be tuned using @ref regfi_set_message_mask. 
[202]732 * Messages may be retrieved using @ref regfi_log_get_str.
[169]733 *
734 * @note If the message mask is set to record any messages, dependent code
[202]735 *       must use @ref regfi_log_get_str periodically to clear the message
[169]736 *       queue. Otherwise, this structure will grow in size over time as
737 *       messages queue up.
738 *
739 * @ingroup regfiBase
740 */ 
[178]741typedef struct _regfi_file
[97]742{
[135]743  /* Data parsed from file header */
744  /********************************/
[168]745  uint8_t  magic[REGFI_REGF_MAGIC_SIZE];/* "regf" */
[151]746
747 /* These sequence numbers should match if
748  * the hive was properly synced to disk.
749  */
[168]750  uint32_t sequence1;           
751  uint32_t sequence2;
[151]752
[168]753  REGFI_NTTIME mtime;
754  uint32_t major_version;  /* Set to 1 in all known hives */
755  uint32_t minor_version;  /* Set to 3 or 5 in all known hives */
756  uint32_t type;           /* XXX: Unverified.  Set to 0 in all known hives */
757  uint32_t format;         /* XXX: Unverified.  Set to 1 in all known hives */
[97]758
[168]759  uint32_t root_cell;  /* Offset to root cell in the first (or any?) hbin block */
760  uint32_t last_block; /* Offset to last hbin block in file */
[151]761
[168]762  uint32_t cluster;    /* XXX: Unverified. Set to 1 in all known hives */
[151]763
764  /* Matches hive's base file name. Stored in UTF-16LE */
[168]765  uint8_t file_name[REGFI_REGF_NAME_SIZE];
[151]766
767  WINSEC_UUID* rm_id;       /* XXX: Unverified. */
768  WINSEC_UUID* log_id;      /* XXX: Unverified. */
769  WINSEC_UUID* tm_id;       /* XXX: Unverified. */
[168]770  uint32_t flags;             /* XXX: Unverified. */
771  uint32_t guid_signature;    /* XXX: Unverified. */
[151]772
[168]773  uint32_t checksum;          /* Stored checksum from file */
774  uint32_t computed_checksum; /* Our own calculation of the checksum.
[151]775                             * (XOR of bytes 0x0000 - 0x01FB) */
776
777  WINSEC_UUID* thaw_tm_id;  /* XXX: Unverified. */
778  WINSEC_UUID* thaw_rm_id;  /* XXX: Unverified. */
779  WINSEC_UUID* thaw_log_id; /* XXX: Unverified. */
[168]780  uint32_t boot_type;         /* XXX: Unverified. */
781  uint32_t boot_recover;      /* XXX: Unverified. */
[151]782
783  /* This seems to include random junk.  Possibly unsanitized memory left over
784   * from when header block was written.  For instance, chunks of nk records
785   * can be found, though often it's all 0s. */
[168]786  uint8_t reserved1[REGFI_REGF_RESERVED1_SIZE];
[151]787
788  /* This is likely reserved and unusued currently.  (Should be all 0s.)
789   * Included here for easier access in looking for hidden data
790   * or doing research. */
[168]791  uint8_t reserved2[REGFI_REGF_RESERVED2_SIZE];
[151]792
[203]793
794  /* Run-time information */
795  /************************/
[206]796  /* For sanity checking (not part of the registry header) */
797  uint32_t file_length;
798
799  /** The encoding that all strings are converted to during interpretation.
800   */
801  REGFI_ENCODING string_encoding;
802
[203]803  /* Functions for accessing the file */
804  REGFI_RAW_FILE* cb;
805
806  /* Mutex for all cb access.  This is done to prevent one thread from moving
807   * the file offset while another thread is in the middle of a multi-read
808   * parsing transaction */
809  pthread_mutex_t cb_lock;
810
811  /* Metadata about hbins */
812  range_list* hbins;
813
814  /* Multiple read access allowed, write access is exclusive */
815  pthread_rwlock_t hbins_lock;
816
817  /* SK record cached since they're repeatedly reused */
818  lru_cache* sk_cache;
819
820  /* Need exclusive access for LRUs, since lookups make changes */
821  pthread_mutex_t sk_lock;
822
[135]823} REGFI_FILE;
[30]824
825
[169]826/** Registry hive iterator
827 * @ingroup regfiIteratorLayer
828 */
[151]829typedef struct _regfi_iterator
[97]830{
[169]831  /** The registry hive this iterator is associated with */
[135]832  REGFI_FILE* f;
[169]833
834  /** All current parent keys and associated iterator positions */
[80]835  void_stack* key_positions;
[169]836
837  /** The current key */
[203]838  REGFI_NK* cur_key;
[169]839
840  /** Index of the current subkey */
[168]841  uint32_t cur_subkey;
[169]842
843  /** Index of the current value */
[168]844  uint32_t cur_value;
[78]845} REGFI_ITERATOR;
846
[80]847
[151]848typedef struct _regfi_iter_position
[97]849{
[203]850  REGFI_NK* nk;
[168]851  uint32_t cur_subkey;
[80]852  /* We could store a cur_value here as well, but didn't see
853   * the use in it right now.
854   */
855} REGFI_ITER_POSITION;
856
857
[169]858/** General purpose buffer with stored length
859 * @ingroup regfiBottomLayer
860 */
[151]861typedef struct _regfi_buffer
862{
[168]863  uint8_t* buf;
[151]864  uint32_t len;
865} REGFI_BUFFER;
866
867
[169]868
[54]869/******************************************************************************/
[168]870/**
[169]871 * @defgroup regfiBase Base Layer: Essential Functions and Data Structures
[168]872 *
[169]873 * These functions are either necessary for normal use of the regfi API or just
874 * don't fit particularly well in any of the other layers.
[168]875 */
[135]876/******************************************************************************/
[166]877
[168]878/** Parses file headers of an already open registry hive file and
879 *  allocates related structures for further parsing.
[166]880 *
[168]881 * @param fd A file descriptor of an already open file.  Must be seekable.
[166]882 *
[168]883 * @return A reference to a newly allocated REGFI_FILE structure, if successful;
[184]884 *         NULL on error.  Use regfi_free to free the returned REGFI_FILE.
[168]885 *
886 * @ingroup regfiBase
[166]887 */
[201]888_EXPORT
[206]889REGFI_FILE* regfi_alloc(int fd, REGFI_ENCODING output_encoding);
[166]890
891
[178]892/** Parses file headers returned by supplied callback functions.
[166]893 *
[178]894 * This interface is useful if you have a registry hive in memory
895 * or have some other reason to emulate a real file.
[166]896 *
[178]897 * @param file_cb A structure defining the callback functions needed to access the file.
[168]898 *
[178]899 * @return A reference to a newly allocated REGFI_FILE structure, if successful;
[184]900 *         NULL on error.  Use regfi_free to free the returned REGFI_FILE.
[178]901 *
[168]902 * @ingroup regfiBase
[166]903 */
[201]904_EXPORT
[206]905REGFI_FILE* regfi_alloc_cb(REGFI_RAW_FILE* file_cb,
906                           REGFI_ENCODING output_encoding);
[166]907
908
[168]909/** Frees a hive's data structures without closing the underlying file.
[166]910 *
[168]911 * @param file The registry structure to free.
912 *
913 * @ingroup regfiBase
[166]914 */
[201]915_EXPORT
916void regfi_free(REGFI_FILE* file);
[166]917
918
[168]919/** Get errors, warnings, and/or verbose information relating to processing of
920 *  the given registry file.
[135]921 *
[168]922 * @return A newly allocated char* which must be free()d by the caller.
923 *
924 * @ingroup regfiBase
[135]925 */
[201]926_EXPORT
[182]927char* regfi_log_get_str();
[159]928
[166]929
[185]930/** Set the verbosity level of messages generated by the library for the
931 *  current thread.
[166]932 *
[185]933 * @param mask   An integer representing the types of messages desired.
[166]934 *               Acceptable values are created through bitwise ORs of
[185]935 *               REGFI_LOG_* values.  For instance, if only errors and
[166]936 *               informational messages were desired (but not warnings),
[185]937 *               then one would specify: REGFI_LOG_ERROR|REGFI_LOG_INFO
938 *               By default the message mask is: REGFI_LOG_ERROR|REGFI_LOG_WARN.
[166]939 *
[185]940 * @return       true on success and false on failure.  Failure occurs if
941 *               underlying pthread functions fail.  errno is set in this case.
[182]942 *
[185]943 * Message masks are set in a thread-specific way.  If one were to set a message
944 * mask in one thread and then spawn a new thread, then the new thread will have
945 * it's message mask reset to the default.  This function may be called at any
946 * time and will take effect immediately for the current thread.
[182]947 *
[185]948 * @note When a non-zero message mask is set, messages will
949 *       accumulate in memory without limit if they are not fetched using
950 *       @ref regfi_get_log_str and subsequently freed by the caller.  It is
951 *       recommended that messsages be fetched after each regfi API call in
952 *       order to provide the most context.
953 *
[182]954 * @ingroup regfiBase
955 */
[201]956_EXPORT
[185]957bool regfi_log_set_mask(uint16_t mask);
[182]958
959
[215]960/** Fetches a hive's root key.
961 *
962 * @return Returns the root key or NULL on failure.  Key must be freed using
963 *         @ref regfi_free_record.
964 *
965 * @ingroup regfiBase
966 */
967_EXPORT
968const REGFI_NK*       regfi_get_rootkey(REGFI_FILE* file);
[168]969
[215]970
[184]971/** Frees a record previously returned by one of the API functions.
[159]972 *
[203]973 * Can be used to free REGFI_NK, REGFI_VK, REGFI_SK, REGFI_DATA, and
[184]974 * REGFI_CLASSNAME records.
[159]975 *
[184]976 * @note The "const" in the data type is a bit misleading and is there just for
977 * convenience.  Since records returned previously must not be modified by users
978 * of the API due to internal caching, these are returned as const, so this
[215]979 * function is const to make passing those records back easy.
[168]980 *
981 * @ingroup regfiBase
982 */
[201]983_EXPORT
[184]984void regfi_free_record(const void* record);
[168]985
986
[224]987/** Increments reference count on record
988 *
989 * Adds an extra internal reference to specified record, making it necessary to
990 * call regfi_free_record on it an additional time before it is freed.  This is
991 * useful in cases where multiple threads/structures need access to a record,
992 * without requiring them to be in sync with when it is freed.
993 *
994 * Can be used on REGFI_NK, REGFI_VK, REGFI_SK, REGFI_DATA, and
995 * REGFI_CLASSNAME records.
996 *
997 * @return true on success, false otherwise
998 *
999 * @ingroup regfiBase
1000 */
1001_EXPORT
1002bool regfi_reference_record(const void* record);
1003
1004
[207]1005/** Retrieves number of subkeys referenced by this key.
1006 *
1007 * Number of subkeyss in key structure and subkey list structure could differ,
1008 * so this provides a standard/sane way of determining the number.
1009 *
1010 * @param key  the key whose number of subkeys is desired
1011 *
1012 * @return Returns the number of subkeys referenced by this key.
1013 *
1014 * @ingroup regfiBase
1015 */
1016_EXPORT
1017uint32_t regfi_fetch_num_subkeys(const REGFI_NK* key);
1018
1019
1020/** Retrieves number of values referenced by this key.
1021 *
1022 * Number of values in key structure and value list structure could differ,
1023 * so this provides a standard/sane way of determining the number.
1024 *
1025 * @param key  the key whose number of values is desired
1026 *
1027 * @return Returns the number of values referenced by this key.
1028 *
1029 * @ingroup regfiBase
1030 */
1031_EXPORT
1032uint32_t regfi_fetch_num_values(const REGFI_NK* key);
1033
1034
[206]1035/** Retrieves classname for a given key.
1036 *
1037 * @param file the file from which key is derived
1038 * @param key the key whose classname is desired
1039 *
1040 * @return Returns a newly allocated classname structure, or NULL on failure.
1041 *         Classname structures must be freed with @ref regfi_free_record.
1042 *
1043 * @ingroup regfiBase
1044 */
1045_EXPORT
1046const REGFI_CLASSNAME* regfi_fetch_classname(REGFI_FILE* file, 
1047                                             const REGFI_NK* key);
1048
1049
1050/** Returns the SK (security) record referenced by the supplied key.
1051 *
1052 * @param file the file from which key is derived
1053 * @param key  the key whose SK record is desired
1054 *
1055 * @return A read-only SK structure, or NULL on failure.
1056 *
1057 * @ingroup regfiBase
1058 */
1059_EXPORT
1060const REGFI_SK* regfi_fetch_sk(REGFI_FILE* file, const REGFI_NK* key);
1061
1062
1063/** Retrieves data for a given value.
1064 *
1065 * @param file the file from which value is derived
1066 * @param value the value whose data is desired
1067 *
1068 * @return Returns a newly allocated data structure, or NULL on failure.
1069 *         Data structures must be freed with @ref regfi_free_record.
1070 *
1071 * @ingroup regfiBase
1072 */
1073_EXPORT
1074const REGFI_DATA* regfi_fetch_data(REGFI_FILE* file,
1075                                   const REGFI_VK* value);
1076
1077
[207]1078/** Locates a specific subkey of a given key.
1079 *
1080 * @param file  the file from which key is derived
1081 * @param key   the key whose subkey is desired
1082 * @param name  name of the desired subkey
1083 * @param index a return value: the index of the desired subkey.
1084 *              undefined on error
1085 *
1086 * @return true if the subkey is found, false if an error occurred or if the
1087 *         specified name could not be found. If an error occurs, messages
1088 *         will be written explaining the issue. (See regfi_log_get_str.)
1089 *
1090 * @ingroup regfiBase
1091 */
1092_EXPORT
1093bool regfi_find_subkey(REGFI_FILE* file, const REGFI_NK* key, 
1094                       const char* name, uint32_t* index);
1095
1096
1097/** Locates a specific value of a given key.
1098 *
1099 * @param file  the file from which key is derived
1100 * @param key   the key whose value is desired
1101 * @param name  name of the desired value
1102 * @param index a return value: the index of the desired value. 
1103 *              undefined on error
1104 *
1105 * @return true if the value is found, false if an error occurred or if the
1106 *         specified name could not be found. If an error occurs, messages
1107 *         will be written explaining the issue. (See regfi_log_get_str.)
1108 *
1109 * @ingroup regfiBase
1110 */
1111_EXPORT
1112bool regfi_find_value(REGFI_FILE* file, const REGFI_NK* key,
1113                      const char* name, uint32_t* index);
1114
1115
1116/** Retrieves a specific subkey of a given key.
1117 *
1118 * @param file  the file from which key is derived
1119 * @param key   the key whose subkey is desired
1120 * @param index the index of the desired subkey
1121 *
1122 * @return the requested subkey or NULL on error.
1123 *
1124 * @ingroup regfiBase
1125 */
1126_EXPORT
1127const REGFI_NK* regfi_get_subkey(REGFI_FILE* file, const REGFI_NK* key, 
1128                                 uint32_t index);
1129
1130
1131/** Retrieves a specific value of a given key.
1132 *
1133 * @param file  the file from which key is derived
1134 * @param key   the key whose value is desired
1135 * @param index the index of the desired value
1136 *
1137 * @return the requested value or NULL on error.
1138 *
1139 * @ingroup regfiBase
1140 */
1141_EXPORT
1142const REGFI_VK* regfi_get_value(REGFI_FILE* file, const REGFI_NK* key, 
1143                                uint32_t index);
1144
1145
1146
[215]1147/** Uses a key's parent_off reference to retrieve it's parent.
1148 *
1149 * @param file  the file from which key is derived
1150 * @param key   the key whose parent is desired
1151 *
1152 * @return the requested subkey or NULL on error.
1153 *
1154 * @ingroup regfiBase
1155 */
1156_EXPORT
1157const REGFI_NK* regfi_get_parentkey(REGFI_FILE* file, const REGFI_NK* key);
1158
1159
[168]1160/******************************************************************************/
1161/**
[169]1162 * @defgroup regfiIteratorLayer Iterator Layer: Primary regfi Library Interface
[168]1163 *
1164 * This top layer of API functions provides an iterator interface which makes
1165 * traversing registry data structures easy in both single-threaded and
1166 * multi-threaded scenarios.
1167 */
1168/******************************************************************************/
1169
1170/** Creates a new iterator for the provided registry file.
1171 *
1172 * @param file The opened registry file the iterator should be created for.
1173 *
1174 * @param output_encoding Character encoding that strings should be returned in.
1175 *                        Only supply the REGFI_ENCODING_* constants, as others
1176 *                        will be rejected.
1177 *                        The following values are currently accepted:
1178 *                        REGFI_ENCODING_DEFAULT (currently REGFI_ENCODING_ASCII)
1179 *                        REGFI_ENCODING_ASCII
1180 *                        REGFI_ENCODING_UTF8
1181 *
1182 * @return A newly allocated REGFI_ITERATOR.
1183 *         Must be free()d with regfi_iterator_free.
1184 *
[169]1185 * @ingroup regfiIteratorLayer
[168]1186 */
[201]1187_EXPORT
[206]1188REGFI_ITERATOR* regfi_iterator_new(REGFI_FILE* file);
[166]1189
1190
[168]1191/** Frees a registry file iterator previously created by regfi_iterator_new.
[166]1192 *
1193 * This does not affect the underlying registry file's allocation status.
1194 *
[168]1195 * @param i the iterator to be freed
1196 *
[169]1197 * @ingroup regfiIteratorLayer
[166]1198 */
[201]1199_EXPORT
1200void regfi_iterator_free(REGFI_ITERATOR* i);
[166]1201
1202
[168]1203/** Traverse deeper into the registry tree at the current subkey.
[166]1204 *
[168]1205 * @param i the iterator
[166]1206 *
[168]1207 * @return  true on success, false on failure. 
1208 *          Note that subkey and value indexes are preserved.  That is, if a
1209 *          regfi_iterator_up call occurs later (reversing the effect of this
1210 *          call) then the subkey and value referenced prior to the
1211 *          regfi_iterator_down call will still be referenced.  This  makes
1212 *          depth-first iteration particularly easy.
1213 *
[169]1214 * @ingroup regfiIteratorLayer
[166]1215 */
[201]1216_EXPORT
1217bool regfi_iterator_down(REGFI_ITERATOR* i);
[166]1218
1219
[168]1220/** Traverse up to the current key's parent key.
[166]1221 *
[168]1222 * @param i the iterator
[166]1223 *
[168]1224 * @return  true on success, false on failure.  Any subkey or value state
1225 *          associated with the current key is lost.
1226 *
[169]1227 * @ingroup regfiIteratorLayer
[166]1228 */
[201]1229_EXPORT
1230bool regfi_iterator_up(REGFI_ITERATOR* i);
[166]1231
1232
[168]1233/** Traverse up to the root key of the hive.
[166]1234 *
[168]1235 * @param i the iterator
[166]1236 *
[168]1237 * @return true on success, false on failure.
1238 *
[169]1239 * @ingroup regfiIteratorLayer
[166]1240 */
[201]1241_EXPORT
1242bool regfi_iterator_to_root(REGFI_ITERATOR* i);
[30]1243
[166]1244
[168]1245/** Traverse down multiple levels in the registry hive.
[166]1246 *
1247 * XXX: This currently only accepts ASCII key names.  Need to look into
1248 *      accepting other encodings.
1249 *
[168]1250 * @param i    the iterator
1251 * @param path a list of key names representing the path.  This list must
1252 *             contain NUL terminated strings.  The list itself is
1253 *             terminated with a NULL pointer.  All path elements must be
1254 *             keys; value names are not accepted (even as the last
1255 *             element).
1256 *
1257 * @return true on success, false on failure.  If any element of path is not
1258 *                 found, false will be returned and the iterator will remain
1259 *                 in its original position.
1260 *
[169]1261 * @ingroup regfiIteratorLayer
[166]1262 */
[201]1263_EXPORT
[168]1264bool regfi_iterator_walk_path(REGFI_ITERATOR* i, const char** path);
[166]1265
1266
[168]1267/** Returns the currently referenced key.
[166]1268 *
[168]1269 * @param i the iterator
[166]1270 *
[168]1271 * @return A read-only key structure for the current key, or NULL on failure.
[221]1272 *         Data structures must be freed with @ref regfi_free_record.
[168]1273 *
[169]1274 * @ingroup regfiIteratorLayer
[166]1275 */
[201]1276_EXPORT
[203]1277const REGFI_NK* regfi_iterator_cur_key(REGFI_ITERATOR* i);
[166]1278
1279
[168]1280/** Sets the internal subkey index to the first subkey referenced by the current
[200]1281 *  key.
[166]1282 *
[168]1283 * @param i the iterator
[166]1284 *
[200]1285 * @return True if the current key has any subkeys, false otherwise.
[168]1286 *
[169]1287 * @ingroup regfiIteratorLayer
[166]1288 */
[201]1289_EXPORT
[199]1290bool regfi_iterator_first_subkey(REGFI_ITERATOR* i);
[166]1291
1292
[168]1293/** Returns the currently indexed subkey.
[166]1294 *
[168]1295 * @param i the iterator
[166]1296 *
[168]1297 * @return A newly allocated key structure for the currently referenced subkey,
1298 *         or NULL on failure.  Newly allocated keys must be freed with
[185]1299 *         @ref regfi_free_record.
[168]1300 *
[169]1301 * @ingroup regfiIteratorLayer
[166]1302 */
[201]1303_EXPORT
[203]1304const REGFI_NK* regfi_iterator_cur_subkey(REGFI_ITERATOR* i);
[167]1305
1306
[200]1307/** Increments the internal subkey index to the next key in the subkey-list.
[167]1308 *
[168]1309 * @param i the iterator
[167]1310 *
[200]1311 * @return True if another subkey should exist, false otherwise.
[168]1312 *
[169]1313 * @ingroup regfiIteratorLayer
[167]1314 */
[201]1315_EXPORT
[199]1316bool regfi_iterator_next_subkey(REGFI_ITERATOR* i);
[167]1317
1318
[168]1319/** Searches for a subkey with a given name under the current key.
[167]1320 *
[207]1321 * @param i     the iterator
1322 * @param name  subkey name to search for
[167]1323 *
[168]1324 * @return True if such a subkey was found, false otherwise.  If a subkey is
1325 *         found, the current subkey index is set to that subkey.  Otherwise,
1326 *         the subkey index remains at the same location as before the call.
1327 *
[169]1328 * @ingroup regfiIteratorLayer
[167]1329 */
[201]1330_EXPORT
[207]1331bool regfi_iterator_find_subkey(REGFI_ITERATOR* i, const char* name);
[150]1332
[184]1333
[168]1334/** Sets the internal value index to the first value referenced by the current
[200]1335 *  key.
[167]1336 *
[168]1337 * @param i the iterator
[167]1338 *
[200]1339 * @return True if the current key has any values, false otherwise.
[168]1340 *
[169]1341 * @ingroup regfiIteratorLayer
[167]1342 */
[201]1343_EXPORT
[199]1344bool regfi_iterator_first_value(REGFI_ITERATOR* i);
[167]1345
1346
[168]1347/** Returns the currently indexed value.
[167]1348 *
[168]1349 * @param i the iterator
[167]1350 *
[168]1351 * @return A newly allocated value structure for the currently referenced value,
1352 *         or NULL on failure.  Newly allocated values must be freed with
[185]1353 *         @ref regfi_free_record.
[168]1354 *
[169]1355 * @ingroup regfiIteratorLayer
[167]1356 */
[201]1357_EXPORT
[203]1358const REGFI_VK* regfi_iterator_cur_value(REGFI_ITERATOR* i);
[167]1359
1360
[200]1361/** Increments the internal value index to the next value in the value-list.
[167]1362 *
[168]1363 * @param i the iterator
[167]1364 *
[200]1365 * @return True if another value should exist, false otherwise.
[168]1366 *
[169]1367 * @ingroup regfiIteratorLayer
[167]1368 */
[201]1369_EXPORT
[199]1370bool regfi_iterator_next_value(REGFI_ITERATOR* i);
[167]1371
1372
[168]1373/** Searches for a value with a given name under the current key.
[167]1374 *
[207]1375 * @param i     the iterator
1376 * @param name  value name to search for
[167]1377 *
[168]1378 * @return True if such a value was found, false otherwise.  If a value is
1379 *         found, the current value index is set to that value.  Otherwise,
1380 *         the value index remains at the same location as before the call.
1381 *
[169]1382 * @ingroup regfiIteratorLayer
[167]1383 */
[201]1384_EXPORT
[207]1385bool regfi_iterator_find_value(REGFI_ITERATOR* i, const char* name);
[80]1386
[167]1387
[168]1388/******************************************************************************/
1389/**
[169]1390 * @defgroup regfiGlueLayer Glue Layer: Logical Data Structure Loading
[168]1391 */
1392/******************************************************************************/
1393
[215]1394/** Loads a key and associated data structures given a file offset.
[168]1395 *
1396 * XXX: finish documenting
1397 *
[169]1398 * @ingroup regfiGlueLayer
[168]1399 */
[201]1400_EXPORT
[203]1401REGFI_NK* regfi_load_key(REGFI_FILE* file, uint32_t offset, 
[215]1402                         REGFI_ENCODING output_encoding, 
1403                         bool strict);
[168]1404
1405
1406/** Loads a value at a given file offset alng with associated data structures.
1407 *
1408 * XXX: finish documenting
1409 *
[169]1410 * @ingroup regfiGlueLayer
[168]1411 */
[201]1412_EXPORT
[203]1413REGFI_VK* regfi_load_value(REGFI_FILE* file, uint32_t offset, 
[201]1414                               REGFI_ENCODING output_encoding, 
1415                               bool strict);
[168]1416
1417
1418/** Loads a logical subkey list in its entirety which may span multiple records.
1419 *
1420 * XXX: finish documenting
1421 *
[169]1422 * @ingroup regfiGlueLayer
[168]1423 */
[201]1424_EXPORT
1425REGFI_SUBKEY_LIST* regfi_load_subkeylist(REGFI_FILE* file, uint32_t offset,
1426                                         uint32_t num_keys, uint32_t max_size,
1427                                         bool strict);
[168]1428
1429
1430/** Loads a valuelist.
1431 *
1432 * XXX: finish documenting
1433 *
[169]1434 * @ingroup regfiGlueLayer
[168]1435 */
[201]1436_EXPORT
1437REGFI_VALUE_LIST* regfi_load_valuelist(REGFI_FILE* file, uint32_t offset, 
1438                                       uint32_t num_values, uint32_t max_size,
1439                                       bool strict);
[127]1440
[168]1441
1442/** Loads a data record which may be contained in the virtual offset, in a
1443 *  single cell, or in multiple cells through big data records.
1444 *
1445 * XXX: finish documenting
1446 *
[169]1447 * @ingroup regfiGlueLayer
[168]1448 */
[201]1449_EXPORT
1450REGFI_BUFFER regfi_load_data(REGFI_FILE* file, uint32_t voffset,
1451                             uint32_t length, bool data_in_offset,
1452                             bool strict);
[157]1453
[168]1454
1455/** Loads the data associated with a big data record at the specified offset.
1456 *
1457 * XXX: finish documenting
1458 *
[169]1459 * @ingroup regfiGlueLayer
[168]1460 */
[201]1461_EXPORT
1462REGFI_BUFFER regfi_load_big_data(REGFI_FILE* file, uint32_t offset, 
1463                                 uint32_t data_length,uint32_t cell_length,
1464                                 range_list* used_ranges,
1465                                 bool strict);
[168]1466
1467
1468/** Given raw data, attempts to interpret the data based on a specified registry
1469 *  data type.
1470 *
1471 * XXX: finish documenting
1472 *
[169]1473 * @ingroup regfiGlueLayer
[168]1474 */
[201]1475_EXPORT
1476bool regfi_interpret_data(REGFI_FILE* file, 
1477                          REGFI_ENCODING string_encoding,
1478                          uint32_t type, REGFI_DATA* data);
[168]1479
1480
1481
[146]1482/* These are cached so return values don't need to be freed. */
[168]1483
1484/** Loads an "sk" security record at the specified offset.
1485 *
1486 * XXX: finish documenting
1487 *
[169]1488 * @ingroup regfiGlueLayer
[168]1489 */
[201]1490_EXPORT
[203]1491const REGFI_SK* regfi_load_sk(REGFI_FILE* file, uint32_t offset,
[201]1492                                  bool strict);
[146]1493
1494
[206]1495
1496
[168]1497/** Retrieves the HBIN data structure stored at the specified offset.
1498 *
1499 * XXX: finish documenting
1500 *
[169]1501 * @ingroup regfiGlueLayer
[168]1502 */
[201]1503_EXPORT
1504const REGFI_HBIN* regfi_lookup_hbin(REGFI_FILE* file, uint32_t offset);
[168]1505
1506
1507
1508/******************************************************************************/
1509/**
[169]1510 * @defgroup regfiParseLayer Parsing Layer: Direct Data Structure Access
[168]1511 */
1512/******************************************************************************/
1513
[201]1514_EXPORT
1515REGFI_FILE* regfi_parse_regf(REGFI_RAW_FILE* file_cb, bool strict);
[80]1516
[201]1517_EXPORT
1518REGFI_HBIN* regfi_parse_hbin(REGFI_FILE* file, uint32_t offset, 
1519                             bool strict);
[99]1520
[201]1521
[168]1522/** Parses an NK record at the specified offset
[99]1523 *
[168]1524 * @param file     the registry file structure
1525 * @param offset   the offset of the cell (not the record) to be parsed.
1526 * @param max_size the maximum size the NK cell could be. (for validation)
1527 * @param strict   if true, rejects any malformed records.  Otherwise,
1528 *                 tries to minimally validate integrity.
1529 *
1530 * @return A newly allocated NK record structure, or NULL on failure.
1531 *
[169]1532 * @ingroup regfiParseLayer
[99]1533 */
[201]1534_EXPORT
[203]1535REGFI_NK* regfi_parse_nk(REGFI_FILE* file, uint32_t offset,
[201]1536                             uint32_t max_size, bool strict);
[99]1537
[139]1538
[168]1539/** Parses a single cell containing a subkey-list record.
1540 *
1541 * XXX: finish documenting
1542 *
[169]1543 * @ingroup regfiParseLayer
[168]1544 */
[201]1545_EXPORT
1546REGFI_SUBKEY_LIST* regfi_parse_subkeylist(REGFI_FILE* file, uint32_t offset,
1547                                          uint32_t max_size, bool strict);
[103]1548
[111]1549
[168]1550/** Parses a VK (value) record at the specified offset
1551 *
1552 * XXX: finish documenting
1553 *
[169]1554 * @ingroup regfiParseLayer
[168]1555 */
[201]1556_EXPORT
[203]1557REGFI_VK* regfi_parse_vk(REGFI_FILE* file, uint32_t offset, 
[201]1558                             uint32_t max_size, bool strict);
[168]1559
1560
1561/** Parses an SK (security) record at the specified offset
1562 *
1563 * XXX: finish documenting
1564 *
[169]1565 * @ingroup regfiParseLayer
[168]1566 */
[201]1567_EXPORT
[203]1568REGFI_SK* regfi_parse_sk(REGFI_FILE* file, uint32_t offset, 
[201]1569                             uint32_t max_size, bool strict);
[168]1570
1571
1572/** Retrieves information on all cells in the registry hive which are
1573 *  currently in the unallocated status. 
1574 *
1575 * The unallocated status is determined based soley on the cell length sign.
1576 *
1577 * XXX: finish documenting
1578 *
[169]1579 * @ingroup regfiParseLayer
[168]1580 */
[201]1581_EXPORT
1582range_list* regfi_parse_unalloc_cells(REGFI_FILE* file);
[101]1583
[111]1584
[168]1585/** Helper function to parse a cell
1586 *
1587 * XXX: finish documenting
1588 *
[169]1589 * @ingroup regfiParseLayer
[168]1590 */
[201]1591_EXPORT
1592bool regfi_parse_cell(REGFI_RAW_FILE* file_cb, uint32_t offset,
1593                      uint8_t* hdr, uint32_t hdr_len,
1594                      uint32_t* cell_length, bool* unalloc);
[126]1595
[157]1596
[168]1597/** Parses a classname cell
1598 *
1599 * XXX: finish documenting
1600 *
[169]1601 * @ingroup regfiParseLayer
[168]1602 */
[201]1603_EXPORT
1604uint8_t* regfi_parse_classname(REGFI_FILE* file, uint32_t offset,
1605                               uint16_t* name_length, 
1606                               uint32_t max_size, bool strict);
[157]1607
1608
[168]1609/** Parses a single-cell data record
1610 *
1611 * XXX: finish documenting
1612 *
[169]1613 * @ingroup regfiParseLayer
[168]1614 */
[201]1615_EXPORT
1616REGFI_BUFFER regfi_parse_data(REGFI_FILE* file, uint32_t offset,
1617                              uint32_t length, bool strict);
[127]1618
[150]1619
[168]1620/** Parses a "little data" record which is stored entirely within the
1621 *  provided virtual offset.
1622 *
1623 * XXX: finish documenting
1624 *
[169]1625 * @ingroup regfiParseLayer
[168]1626 */
[201]1627_EXPORT
1628REGFI_BUFFER regfi_parse_little_data(REGFI_FILE* file, uint32_t voffset, 
1629                                     uint32_t length, bool strict);
[150]1630
[168]1631
1632/******************************************************************************/
[215]1633/*    Private (and undocumented) Functions                                    */
[168]1634/******************************************************************************/
[226]1635int64_t               regfi_raw_seek(REGFI_RAW_FILE* self, 
1636                                     uint64_t offset, int whence);
[178]1637ssize_t               regfi_raw_read(REGFI_RAW_FILE* self, 
1638                                     void* buf, size_t count);
[201]1639_EXPORT
[226]1640uint64_t              regfi_seek(REGFI_RAW_FILE* file_cb, 
1641                                 uint64_t offset, int whence);
[201]1642_EXPORT
[178]1643uint32_t              regfi_read(REGFI_RAW_FILE* file_cb, 
1644                                 uint8_t* buf, uint32_t* length);
1645
[201]1646_EXPORT
[135]1647const char*           regfi_type_val2str(unsigned int val);
[201]1648_EXPORT
[135]1649int                   regfi_type_str2val(const char* str);
[127]1650
[201]1651_EXPORT
[135]1652char*                 regfi_get_sacl(WINSEC_DESC* sec_desc);
[201]1653_EXPORT
[135]1654char*                 regfi_get_dacl(WINSEC_DESC* sec_desc);
[201]1655_EXPORT
[135]1656char*                 regfi_get_owner(WINSEC_DESC* sec_desc);
[201]1657_EXPORT
[135]1658char*                 regfi_get_group(WINSEC_DESC* sec_desc);
1659
[168]1660REGFI_SUBKEY_LIST*    regfi_merge_subkeylists(uint16_t num_lists, 
[135]1661                                              REGFI_SUBKEY_LIST** lists,
1662                                              bool strict);
[168]1663REGFI_SUBKEY_LIST*    regfi_load_subkeylist_aux(REGFI_FILE* file, uint32_t offset,
1664                                                uint32_t max_size, bool strict,
1665                                                uint8_t depth_left);
1666void                  regfi_add_message(REGFI_FILE* file, uint16_t msg_type, 
[138]1667                                        const char* fmt, ...);
[206]1668REGFI_NK*             regfi_copy_nk(const REGFI_NK* nk);
1669REGFI_VK*             regfi_copy_vk(const REGFI_VK* vk);
[201]1670_EXPORT
[168]1671int32_t               regfi_calc_maxsize(REGFI_FILE* file, uint32_t offset);
1672int32_t               regfi_conv_charset(const char* input_charset, 
[161]1673                                         const char* output_charset,
[168]1674                                         uint8_t* input, char* output, 
1675                                         uint32_t input_len, uint32_t output_max);
[201]1676_EXPORT
[159]1677REGFI_DATA*           regfi_buffer_to_data(REGFI_BUFFER raw_data);
[146]1678
[168]1679/* XXX: move to base API and document */
[201]1680_EXPORT
[168]1681void                  regfi_unix2nt_time(REGFI_NTTIME* nt, time_t t);
[201]1682_EXPORT
[219]1683double                regfi_nt2unix_time(const REGFI_NTTIME* nt);
[168]1684
1685
[201]1686_EXPORT
[203]1687void regfi_interpret_keyname(REGFI_FILE* file, REGFI_NK* nk, 
[172]1688                             REGFI_ENCODING output_encoding, bool strict);
[201]1689_EXPORT
[203]1690void regfi_interpret_valuename(REGFI_FILE* file, REGFI_VK* vk, 
[172]1691                               REGFI_ENCODING output_encoding, bool strict);
1692
[202]1693_EXPORT
1694void regfi_init();
[172]1695
[202]1696
[78]1697#endif  /* _REGFI_H */
Note: See TracBrowser for help on using the repository browser.