source: trunk/include/regfi.h @ 224

Last change on this file since 224 was 224, checked in by tim, 14 years ago

added new regfi API function to help manage memory better
fixed reference loop problems in pyregfi

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