source: releases/0.12.0/include/regfi.h@ 286

Last change on this file since 286 was 179, checked in by tim, 15 years ago

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