source: trunk/include/regfi.h @ 228

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

added a test case for pyregfi multithreaded use
updated the regfi multithreaded test case
fixed several ctypes interface problems in pyregfi
added locking to pyregfi iterators for thread safety
fixed regfi talloc race conditions with an additional lock

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