source: trunk/include/regfi.h @ 252

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

updated pyregfi to work with regfi changes
renamed some functions for more clarity
fixed some issues related to talloc_reference

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