1hivex(3)                       Windows Registry                       hivex(3)
2
3
4

NAME

6       hivex - Windows Registry "hive" extraction library
7

SYNOPSIS

9        #include <hivex.h>
10
11        hive_h *hivex_open (const char *filename, int flags);
12        int hivex_close (hive_h *h);
13        hive_node_h hivex_root (hive_h *h);
14        int64_t hivex_last_modified (hive_h *h);
15        char *hivex_node_name (hive_h *h, hive_node_h node);
16        size_t hivex_node_name_len (hive_h *h, hive_node_h node);
17        int64_t hivex_node_timestamp (hive_h *h, hive_node_h node);
18        hive_node_h *hivex_node_children (hive_h *h, hive_node_h node);
19        hive_node_h hivex_node_get_child (hive_h *h, hive_node_h node, const char *name);
20        size_t hivex_node_nr_children (hive_h *h, hive_node_h node);
21        hive_node_h hivex_node_parent (hive_h *h, hive_node_h node);
22        hive_value_h *hivex_node_values (hive_h *h, hive_node_h node);
23        hive_value_h hivex_node_get_value (hive_h *h, hive_node_h node, const char *key);
24        size_t hivex_node_nr_values (hive_h *h, hive_node_h node);
25        size_t hivex_value_key_len (hive_h *h, hive_value_h val);
26        char *hivex_value_key (hive_h *h, hive_value_h val);
27        int hivex_value_type (hive_h *h, hive_value_h val, hive_type *t, size_t *len);
28        size_t hivex_node_struct_length (hive_h *h, hive_node_h node);
29        size_t hivex_value_struct_length (hive_h *h, hive_value_h val);
30        hive_value_h hivex_value_data_cell_offset (hive_h *h, hive_value_h val, size_t *len);
31        char *hivex_value_value (hive_h *h, hive_value_h val, hive_type *t, size_t *len);
32        char *hivex_value_string (hive_h *h, hive_value_h val);
33        char **hivex_value_multiple_strings (hive_h *h, hive_value_h val);
34        int32_t hivex_value_dword (hive_h *h, hive_value_h val);
35        int64_t hivex_value_qword (hive_h *h, hive_value_h val);
36        int hivex_commit (hive_h *h, const char *filename, int flags);
37        hive_node_h hivex_node_add_child (hive_h *h, hive_node_h parent, const char *name);
38        int hivex_node_delete_child (hive_h *h, hive_node_h node);
39        int hivex_node_set_values (hive_h *h, hive_node_h node, size_t nr_values, const hive_set_value *values, int flags);
40        int hivex_node_set_value (hive_h *h, hive_node_h node, const hive_set_value *val, int flags);
41
42       Link with -lhivex.
43

DESCRIPTION

45       Hivex is a library for extracting the contents of Windows Registry
46       "hive" files.  It is designed to be secure against buggy or malicious
47       registry files.
48
49       Unlike other tools in this area, it doesn't use the textual .REG
50       format, because parsing that is as much trouble as parsing the original
51       binary format.  Instead it makes the file available through a C API,
52       and then wraps this API in higher level scripting and GUI tools.
53
54       There is a separate program to export the hive as XML (see hivexml(1)),
55       or to navigate the file (see hivexsh(1)).  There is also a Perl script
56       to export and merge the file as a textual .REG (regedit) file, see
57       hivexregedit(1).
58
59       If you just want to export or modify the Registry of a Windows virtual
60       machine, you should look at virt-win-reg(1).
61
62       Hivex is also comes with language bindings for OCaml, Perl, Python and
63       Ruby.
64

TYPES

66   "hive_h *"
67       This handle describes an open hive file.
68
69   "hive_node_h"
70       This is a node handle, an integer but opaque outside the library.
71       Valid node handles cannot be 0.  The library returns 0 in some
72       situations to indicate an error.
73
74   "hive_type"
75       The enum below describes the possible types for the value(s) stored at
76       each node.  Note that you should not trust the type field in a Windows
77       Registry, as it very often has no relationship to reality.  Some
78       applications use their own types.  The encoding of strings is not
79       specified.  Some programs store everything (including strings) in
80       binary blobs.
81
82        enum hive_type {
83          /* Just a key without a value */
84          hive_t_REG_NONE = 0,
85          /* A Windows string (encoding is unknown, but often UTF16-LE) */
86          hive_t_REG_SZ = 1,
87          /* A Windows string that contains %env% (environment variable expansion) */
88          hive_t_REG_EXPAND_SZ = 2,
89          /* A blob of binary */
90          hive_t_REG_BINARY = 3,
91          /* DWORD (32 bit integer), little endian */
92          hive_t_REG_DWORD = 4,
93          /* DWORD (32 bit integer), big endian */
94          hive_t_REG_DWORD_BIG_ENDIAN = 5,
95          /* Symbolic link to another part of the registry tree */
96          hive_t_REG_LINK = 6,
97          /* Multiple Windows strings.  See http://blogs.msdn.com/oldnewthing/archive/2009/10/08/9904646.aspx */
98          hive_t_REG_MULTI_SZ = 7,
99          /* Resource list */
100          hive_t_REG_RESOURCE_LIST = 8,
101          /* Resource descriptor */
102          hive_t_REG_FULL_RESOURCE_DESCRIPTOR = 9,
103          /* Resouce requirements list */
104          hive_t_REG_RESOURCE_REQUIREMENTS_LIST = 10,
105          /* QWORD (64 bit integer), unspecified endianness but usually little endian */
106          hive_t_REG_QWORD = 11,
107       };
108
109   "hive_value_h"
110       This is a value handle, an integer but opaque outside the library.
111       Valid value handles cannot be 0.  The library returns 0 in some
112       situations to indicate an error.
113
114   "hive_set_value"
115       The typedef "hive_set_value" is used in conjunction with the
116       "hivex_node_set_values" call described below.
117
118        struct hive_set_value {
119          char *key;     /* key - a UTF-8 encoded ASCIIZ string */
120          hive_type t;   /* type of value field */
121          size_t len;    /* length of value field in bytes */
122          char *value;   /* value field */
123        };
124        typedef struct hive_set_value hive_set_value;
125
126       To set the default value for a node, you have to pass "key = """.
127
128       Note that the "value" field is just treated as a list of bytes, and is
129       stored directly in the hive.  The caller has to ensure correct encoding
130       and endianness, for example converting dwords to little endian.
131
132       The correct type and encoding for values depends on the node and key in
133       the registry, the version of Windows, and sometimes even changes
134       between versions of Windows for the same key.  We don't document it
135       here.  Often it's not documented at all.
136

FUNCTIONS

138   hivex_open
139        hive_h *hivex_open (const char *filename, int flags);
140
141       Opens the hive named "filename" for reading.
142
143       Flags is an ORed list of the open flags (or 0 if you don't want to pass
144       any flags).  These flags are defined:
145
146       HIVEX_OPEN_VERBOSE
147           Verbose messages.
148
149       HIVEX_OPEN_DEBUG
150           Very verbose messages, suitable for debugging problems in the
151           library itself.
152
153           This is also selected if the "HIVEX_DEBUG" environment variable is
154           set to 1.
155
156       HIVEX_OPEN_WRITE
157           Open the hive for writing.  If omitted, the hive is read-only.
158
159           See "WRITING TO HIVE FILES" in hivex(3).
160
161       HIVEX_OPEN_UNSAFE
162           Open the hive in unsafe mode that enables heuristics to handle
163           corrupted hives.
164
165           This may allow to read or write registry keys/values that appear
166           intact in an otherwise corrupted hive. Use at your own risk.
167
168       Returns a new hive handle.  On error this returns NULL and sets errno.
169
170   hivex_close
171        int hivex_close (hive_h *h);
172
173       Close a hive handle and free all associated resources.
174
175       Note that any uncommitted writes are not committed by this call, but
176       instead are lost.  See "WRITING TO HIVE FILES" in hivex(3).
177
178       Returns 0 on success.  On error this returns -1 and sets errno.
179
180       This function frees the hive handle (even if it returns an error).  The
181       hive handle must not be used again after calling this function.
182
183   hivex_root
184        hive_node_h hivex_root (hive_h *h);
185
186       Return root node of the hive.  All valid hives must contain a root
187       node.
188
189       Returns a node handle.  On error this returns 0 and sets errno.
190
191   hivex_last_modified
192        int64_t hivex_last_modified (hive_h *h);
193
194       Return the modification time from the header of the hive.
195
196       The returned value is a Windows filetime.  To convert this to a Unix
197       "time_t" see:
198       <http://stackoverflow.com/questions/6161776/convert-windows-filetime-to-second-in-unix-linux/6161842#6161842>
199
200   hivex_node_name
201        char *hivex_node_name (hive_h *h, hive_node_h node);
202
203       Return the name of the node.
204
205       Note that the name of the root node is a dummy, such as "$$$PROTO.HIV"
206       (other names are possible: it seems to depend on the tool or program
207       that created the hive in the first place).  You can only know the
208       "real" name of the root node by knowing which registry file this hive
209       originally comes from, which is knowledge that is outside the scope of
210       this library.
211
212       The name is recoded to UTF-8 and may contain embedded NUL characters.
213
214       Returns a string.  The string must be freed by the caller when it is no
215       longer needed.  On error this returns NULL and sets errno.
216
217   hivex_node_name_len
218        size_t hivex_node_name_len (hive_h *h, hive_node_h node);
219
220       Return the length of the node name as produced by "hivex_node_name".
221
222       Returns a size.  On error this returns 0 and sets errno.
223
224   hivex_node_timestamp
225        int64_t hivex_node_timestamp (hive_h *h, hive_node_h node);
226
227       Return the modification time of the node.
228
229       The returned value is a Windows filetime.  To convert this to a Unix
230       "time_t" see:
231       <http://stackoverflow.com/questions/6161776/convert-windows-filetime-to-second-in-unix-linux/6161842#6161842>
232
233   hivex_node_children
234        hive_node_h *hivex_node_children (hive_h *h, hive_node_h node);
235
236       Return an array of nodes which are the subkeys (children) of "node".
237
238       Returns a 0-terminated array of nodes.  The array must be freed by the
239       caller when it is no longer needed.  On error this returns NULL and
240       sets errno.
241
242   hivex_node_get_child
243        hive_node_h hivex_node_get_child (hive_h *h, hive_node_h node, const char *name);
244
245       Return the child of node with the name "name", if it exists.
246
247       The name is matched case insensitively.
248
249       Returns a node handle.  If the node was not found, this returns 0
250       without setting errno.  On error this returns 0 and sets errno.
251
252   hivex_node_nr_children
253        size_t hivex_node_nr_children (hive_h *h, hive_node_h node);
254
255       Return the number of nodes as produced by "hivex_node_children".
256
257       Returns a size.  On error this returns 0 and sets errno.
258
259   hivex_node_parent
260        hive_node_h hivex_node_parent (hive_h *h, hive_node_h node);
261
262       Return the parent of "node".
263
264       The parent pointer of the root node in registry files that we have
265       examined seems to be invalid, and so this function will return an error
266       if called on the root node.
267
268       Returns a node handle.  On error this returns 0 and sets errno.
269
270   hivex_node_values
271        hive_value_h *hivex_node_values (hive_h *h, hive_node_h node);
272
273       Return the array of (key, value) pairs attached to this node.
274
275       Returns a 0-terminated array of values.  The array must be freed by the
276       caller when it is no longer needed.  On error this returns NULL and
277       sets errno.
278
279   hivex_node_get_value
280        hive_value_h hivex_node_get_value (hive_h *h, hive_node_h node, const char *key);
281
282       Return the value attached to this node which has the name "key", if it
283       exists.
284
285       The key name is matched case insensitively.
286
287       Note that to get the default key, you should pass the empty string ""
288       here.  The default key is often written "@", but inside hives that has
289       no meaning and won't give you the default key.
290
291       Returns a value handle.  On error this returns 0 and sets errno.
292
293   hivex_node_nr_values
294        size_t hivex_node_nr_values (hive_h *h, hive_node_h node);
295
296       Return the number of (key, value) pairs attached to this node as
297       produced by "hivex_node_values".
298
299       Returns a size.  On error this returns 0 and sets errno.
300
301   hivex_value_key_len
302        size_t hivex_value_key_len (hive_h *h, hive_value_h val);
303
304       Return the length of the key (name) of a (key, value) pair as produced
305       by "hivex_value_key". The length can legitimately be 0, so errno is the
306       necessary mechanism to check for errors.
307
308       In the context of Windows Registries, a zero-length name means that
309       this value is the default key for this node in the tree.  This is
310       usually written as "@".
311
312       The key is recoded to UTF-8 and may contain embedded NUL characters.
313
314       Returns a size.  On error this returns 0 and sets errno.
315
316   hivex_value_key
317        char *hivex_value_key (hive_h *h, hive_value_h val);
318
319       Return the key (name) of a (key, value) pair.  The name is reencoded as
320       UTF-8 and returned as a string.
321
322       The string should be freed by the caller when it is no longer needed.
323
324       Note that this function can return a zero-length string.  In the
325       context of Windows Registries, this means that this value is the
326       default key for this node in the tree.  This is usually written as "@".
327
328       Returns a string.  The string must be freed by the caller when it is no
329       longer needed.  On error this returns NULL and sets errno.
330
331   hivex_value_type
332        int hivex_value_type (hive_h *h, hive_value_h val, hive_type *t, size_t *len);
333
334       Return the data length and data type of the value in this (key, value)
335       pair.  See also "hivex_value_value" which returns all this information,
336       and the value itself.  Also, "hivex_value_*" functions below which can
337       be used to return the value in a more useful form when you know the
338       type in advance.
339
340       Returns 0 on success.  On error this returns -1 and sets errno.
341
342   hivex_node_struct_length
343        size_t hivex_node_struct_length (hive_h *h, hive_node_h node);
344
345       Return the length of the node data structure.
346
347       Returns a size.  On error this returns 0 and sets errno.
348
349   hivex_value_struct_length
350        size_t hivex_value_struct_length (hive_h *h, hive_value_h val);
351
352       Return the length of the value data structure.
353
354       Returns a size.  On error this returns 0 and sets errno.
355
356   hivex_value_data_cell_offset
357        hive_value_h hivex_value_data_cell_offset (hive_h *h, hive_value_h val, size_t *len);
358
359       Return the offset and length of the value's data cell.
360
361       The data cell is a registry structure that contains the length (a 4
362       byte, little endian integer) followed by the data.
363
364       If the length of the value is less than or equal to 4 bytes then the
365       offset and length returned by this function is zero as the data is
366       inlined in the value.
367
368       Returns 0 and sets errno on error.
369
370       Returns a value handle.  On error this returns 0 and sets errno.
371
372   hivex_value_value
373        char *hivex_value_value (hive_h *h, hive_value_h val, hive_type *t, size_t *len);
374
375       Return the value of this (key, value) pair.  The value should be
376       interpreted according to its type (see "hive_type").
377
378       The value is returned as an array of bytes (of length "len").  The
379       value must be freed by the caller when it is no longer needed.  On
380       error this returns NULL and sets errno.
381
382   hivex_value_string
383        char *hivex_value_string (hive_h *h, hive_value_h val);
384
385       If this value is a string, return the string reencoded as UTF-8 (as a C
386       string).  This only works for values which have type "hive_t_string",
387       "hive_t_expand_string" or "hive_t_link".
388
389       Returns a string.  The string must be freed by the caller when it is no
390       longer needed.  On error this returns NULL and sets errno.
391
392   hivex_value_multiple_strings
393        char **hivex_value_multiple_strings (hive_h *h, hive_value_h val);
394
395       If this value is a multiple-string, return the strings reencoded as
396       UTF-8 (in C, as a NULL-terminated array of C strings, in other language
397       bindings, as a list of strings).  This only works for values which have
398       type "hive_t_multiple_strings".
399
400       Returns a NULL-terminated array of C strings.  The strings and the
401       array must all be freed by the caller when they are no longer needed.
402       On error this returns NULL and sets errno.
403
404   hivex_value_dword
405        int32_t hivex_value_dword (hive_h *h, hive_value_h val);
406
407       If this value is a DWORD (Windows int32), return it.  This only works
408       for values which have type "hive_t_dword" or "hive_t_dword_be".
409
410   hivex_value_qword
411        int64_t hivex_value_qword (hive_h *h, hive_value_h val);
412
413       If this value is a QWORD (Windows int64), return it.  This only works
414       for values which have type "hive_t_qword".
415
416   hivex_commit
417        int hivex_commit (hive_h *h, const char *filename, int flags);
418
419       Commit (write) any changes which have been made.
420
421       "filename" is the new file to write.  If "filename" is null/undefined
422       then we overwrite the original file (ie. the file name that was passed
423       to "hivex_open").
424
425       Note this does not close the hive handle.  You can perform further
426       operations on the hive after committing, including making more
427       modifications.  If you no longer wish to use the hive, then you should
428       close the handle after committing.
429
430       The flags parameter is unused.  Always pass 0.
431
432       Returns 0 on success.  On error this returns -1 and sets errno.
433
434   hivex_node_add_child
435        hive_node_h hivex_node_add_child (hive_h *h, hive_node_h parent, const char *name);
436
437       Add a new child node named "name" to the existing node "parent".  The
438       new child initially has no subnodes and contains no keys or values.
439       The sk-record (security descriptor) is inherited from the parent.
440
441       The parent must not have an existing child called "name", so if you
442       want to overwrite an existing child, call "hivex_node_delete_child"
443       first.
444
445       Returns a node handle.  On error this returns 0 and sets errno.
446
447   hivex_node_delete_child
448        int hivex_node_delete_child (hive_h *h, hive_node_h node);
449
450       Delete the node "node".  All values at the node and all subnodes are
451       deleted (recursively).  The "node" handle and the handles of all
452       subnodes become invalid.  You cannot delete the root node.
453
454       Returns 0 on success.  On error this returns -1 and sets errno.
455
456   hivex_node_set_values
457        int hivex_node_set_values (hive_h *h, hive_node_h node, size_t nr_values, const hive_set_value *values, int flags);
458
459       This call can be used to set all the (key, value) pairs stored in
460       "node".
461
462       "node" is the node to modify.
463
464       The flags parameter is unused.  Always pass 0.
465
466       "values" is an array of (key, value) pairs.  There should be
467       "nr_values" elements in this array.
468
469       Any existing values stored at the node are discarded, and their
470       "hive_value_h" handles become invalid.  Thus you can remove all values
471       stored at "node" by passing "nr_values = 0".
472
473       Returns 0 on success.  On error this returns -1 and sets errno.
474
475   hivex_node_set_value
476        int hivex_node_set_value (hive_h *h, hive_node_h node, const hive_set_value *val, int flags);
477
478       This call can be used to replace a single "(key, value)" pair stored in
479       "node".  If the key does not already exist, then a new key is added.
480       Key matching is case insensitive.
481
482       "node" is the node to modify.
483
484       The flags parameter is unused.  Always pass 0.
485
486       "value" is a single (key, value) pair.
487
488       Existing "hive_value_h" handles become invalid.
489
490       Returns 0 on success.  On error this returns -1 and sets errno.
491

WRITING TO HIVE FILES

493       The hivex library supports making limited modifications to hive files.
494       We have tried to implement this very conservatively in order to reduce
495       the chance of corrupting your registry.  However you should be careful
496       and take back-ups, since Microsoft has never documented the hive
497       format, and so it is possible there are nuances in the reverse-
498       engineered format that we do not understand.
499
500       To be able to modify a hive, you must pass the "HIVEX_OPEN_WRITE" flag
501       to "hivex_open", otherwise any write operation will return with errno
502       "EROFS".
503
504       The write operations shown below do not modify the on-disk file
505       immediately.  You must call "hivex_commit" in order to write the
506       changes to disk.  If you call "hivex_close" without committing then any
507       writes are discarded.
508
509       Hive files internally consist of a "memory dump" of binary blocks (like
510       the C heap), and some of these blocks can be unused.  The hivex library
511       never reuses these unused blocks.  Instead, to ensure robustness in the
512       face of the partially understood on-disk format, hivex only allocates
513       new blocks after the end of the file, and makes minimal modifications
514       to existing structures in the file to point to these new blocks.  This
515       makes hivex slightly less disk-efficient than it could be, but disk is
516       cheap, and registry modifications tend to be very small.
517
518       When deleting nodes, it is possible that this library may leave
519       unreachable live blocks in the hive.  This is because certain parts of
520       the hive disk format such as security (sk) records and big data (db)
521       records and classname fields are not well understood (and not
522       documented at all) and we play it safe by not attempting to modify
523       them.  Apart from wasting a little bit of disk space, it is not thought
524       that unreachable blocks are a problem.
525
526   WRITE OPERATIONS WHICH ARE NOT SUPPORTED
527       •   Changing the root node.
528
529       •   Creating a new hive file from scratch.  This is impossible at
530           present because not all fields in the header are understood.  In
531           the hivex source tree is a file called "images/minimal" which could
532           be used as the basis for a new hive (but caveat emptor).
533
534       •   Modifying or deleting single values at a node.
535
536       •   Modifying security key (sk) records or classnames.  Previously we
537           did not understand these records.  However now they are well-
538           understood and we could add support if it was required (but nothing
539           much really uses them).
540

VISITING ALL NODES

542       The visitor pattern is useful if you want to visit all nodes in the
543       tree or all nodes below a certain point in the tree.
544
545       First you set up your own "struct hivex_visitor" with your callback
546       functions.
547
548       Each of these callback functions should return 0 on success or -1 on
549       error.  If any callback returns -1, then the entire visit terminates
550       immediately.  If you don't need a callback function at all, set the
551       function pointer to NULL.
552
553        struct hivex_visitor {
554          int (*node_start) (hive_h *, void *opaque, hive_node_h, const char *name);
555          int (*node_end) (hive_h *, void *opaque, hive_node_h, const char *name);
556          int (*value_string) (hive_h *, void *opaque, hive_node_h, hive_value_h,
557                hive_type t, size_t len, const char *key, const char *str);
558          int (*value_multiple_strings) (hive_h *, void *opaque, hive_node_h,
559                hive_value_h, hive_type t, size_t len, const char *key, char **argv);
560          int (*value_string_invalid_utf16) (hive_h *, void *opaque, hive_node_h,
561                hive_value_h, hive_type t, size_t len, const char *key,
562                const char *str);
563          int (*value_dword) (hive_h *, void *opaque, hive_node_h, hive_value_h,
564                hive_type t, size_t len, const char *key, int32_t);
565          int (*value_qword) (hive_h *, void *opaque, hive_node_h, hive_value_h,
566                hive_type t, size_t len, const char *key, int64_t);
567          int (*value_binary) (hive_h *, void *opaque, hive_node_h, hive_value_h,
568                hive_type t, size_t len, const char *key, const char *value);
569          int (*value_none) (hive_h *, void *opaque, hive_node_h, hive_value_h,
570                hive_type t, size_t len, const char *key, const char *value);
571          int (*value_other) (hive_h *, void *opaque, hive_node_h, hive_value_h,
572                hive_type t, size_t len, const char *key, const char *value);
573          /* If value_any callback is not NULL, then the other value_*
574           * callbacks are not used, and value_any is called on all values.
575           */
576          int (*value_any) (hive_h *, void *opaque, hive_node_h, hive_value_h,
577                hive_type t, size_t len, const char *key, const char *value);
578        };
579
580       hivex_visit
581            int hivex_visit (hive_h *h, const struct hivex_visitor *visitor, size_t len, void *opaque, int flags);
582
583           Visit all the nodes recursively in the hive "h".
584
585           "visitor" should be a "hivex_visitor" structure with callback
586           fields filled in as required (unwanted callbacks can be set to
587           NULL).  "len" must be the length of the 'visitor' struct (you
588           should pass "sizeof (struct hivex_visitor)" for this).
589
590           This returns 0 if the whole recursive visit was completed
591           successfully.  On error this returns -1.  If one of the callback
592           functions returned an error than we don't touch errno.  If the
593           error was generated internally then we set errno.
594
595           You can skip bad registry entries by setting "flag" to
596           "HIVEX_VISIT_SKIP_BAD".  If this flag is not set, then a bad
597           registry causes the function to return an error immediately.
598
599           This function is robust if the registry contains cycles or pointers
600           which are invalid or outside the registry.  It detects these cases
601           and returns an error.
602
603       hivex_visit_node
604            int hivex_visit_node (hive_h *h, hive_node_h node, const struct hivex_visitor *visitor, size_t len, void *opaque);
605
606           Same as "hivex_visit" but instead of starting out at the root, this
607           starts at "node".
608

THE STRUCTURE OF THE WINDOWS REGISTRY

610       Note: To understand the relationship between hives and the common
611       Windows Registry keys (like "HKEY_LOCAL_MACHINE") please see the
612       Wikipedia page on the Windows Registry.
613
614       The Windows Registry is split across various binary files, each file
615       being known as a "hive".  This library only handles a single hive file
616       at a time.
617
618       Hives are n-ary trees with a single root.  Each node in the tree has a
619       name.
620
621       Each node in the tree (including non-leaf nodes) may have an arbitrary
622       list of (key, value) pairs attached to it.  It may be the case that one
623       of these pairs has an empty key.  This is referred to as the default
624       key for the node.
625
626       The (key, value) pairs are the place where the useful data is stored in
627       the registry.  The key is always a string (possibly the empty string
628       for the default key).  The value is a typed object (eg. string, int32,
629       binary, etc.).
630
631   RELATIONSHIP TO .REG FILES
632       The hivex C library does not care about or deal with Windows .REG
633       files.  Instead we push this complexity up to the Perl Win::Hivex(3)
634       library and the Perl programs hivexregedit(1) and virt-win-reg(1).
635       Nevertheless it is useful to look at the relationship between the
636       Registry and .REG files because they are so common.
637
638       A .REG file is a textual representation of the registry, or part of the
639       registry.  The actual registry hives that Windows uses are binary
640       files.  There are a number of Windows and Linux tools that let you
641       generate .REG files, or merge .REG files back into the registry hives.
642       Notable amongst them is Microsoft's REGEDIT program (formerly known as
643       REGEDT32).
644
645       A typical .REG file will contain many sections looking like this:
646
647        [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Stack]
648        "@"="Generic Stack"
649        "TileInfo"="prop:System.FileCount"
650        "TilePath"=str(2):"%systemroot%\\system32"
651        "ThumbnailCutoff"=dword:00000000
652        "FriendlyTypeName"=hex(2):40,00,25,00,53,00,79,00,73,00,74,00,65,00,6d,00,52,00,6f,00,\
653         6f,00,74,00,25,00,5c,00,53,00,79,00,73,00,74,00,65,00,6d,00,\
654         33,00,32,00,5c,00,73,00,65,00,61,00,72,00,63,00,68,00,66,00,\
655         6f,00,6c,00,64,00,65,00,72,00,2e,00,64,00,6c,00,6c,00,2c,00,\
656         2d,00,39,00,30,00,32,00,38,00,00,00,d8
657
658       Taking this one piece at a time:
659
660        [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Stack]
661
662       This is the path to this node in the registry tree.  The first part,
663       "HKEY_LOCAL_MACHINE\SOFTWARE" means that this comes from a hive file
664       called "C:\WINDOWS\SYSTEM32\CONFIG\SOFTWARE".  "\Classes\Stack" is the
665       real path part, starting at the root node of the "SOFTWARE" hive.
666
667       Below the node name is a list of zero or more key-value pairs.  Any
668       interior or leaf node in the registry may have key-value pairs
669       attached.
670
671        "@"="Generic Stack"
672
673       This is the "default key".  In reality (ie. inside the binary hive) the
674       key string is the empty string.  In .REG files this is written as "@"
675       but this has no meaning either in the hives themselves or in this
676       library.  The value is a string (type 1 - see "enum hive_type" above).
677
678        "TileInfo"="prop:System.FileCount"
679
680       This is a regular (key, value) pair, with the value being a type 1
681       string.  Note that inside the binary file the string is likely to be
682       UTF-16LE encoded.  This library converts to and from UTF-8 strings
683       transparently in some cases.
684
685        "TilePath"=str(2):"%systemroot%\\system32"
686
687       The value in this case has type 2 (expanded string) meaning that some
688       %...% variables get expanded by Windows.  (This library doesn't know or
689       care about variable expansion).
690
691        "ThumbnailCutoff"=dword:00000000
692
693       The value in this case is a dword (type 4).
694
695        "FriendlyTypeName"=hex(2):40,00,....
696
697       This value is an expanded string (type 2) represented in the .REG file
698       as a series of hex bytes.  In this case the string appears to be a
699       UTF-16LE string.
700

NOTE ON THE USE OF ERRNO

702       Many functions in this library set errno to indicate errors.  These are
703       the values of errno you may encounter (this list is not exhaustive):
704
705       ENOTSUP
706           Corrupt or unsupported Registry file format.
707
708       HIVEX_NO_KEY
709           Missing root key.
710
711       EINVAL
712           Passed an invalid argument to the function.
713
714       EFAULT
715           Followed a Registry pointer which goes outside the registry or
716           outside a registry block.
717
718       ELOOP
719           Registry contains cycles.
720
721       ERANGE
722           Field in the registry out of range.
723
724       EEXIST
725           Registry key already exists.
726
727       EROFS
728           Tried to write to a registry which is not opened for writing.
729

ENVIRONMENT VARIABLES

731       HIVEX_DEBUG
732           Setting HIVEX_DEBUG=1 will enable very verbose messages.  This is
733           useful for debugging problems with the library itself.
734

SEE ALSO

736       hivexget(1), hivexml(1), hivexsh(1), hivexregedit(1), virt-win-reg(1),
737       Win::Hivex(3), guestfs(3), <http://libguestfs.org/>, virt-cat(1),
738       virt-edit(1), <http://en.wikipedia.org/wiki/Windows_Registry>.
739

AUTHORS

741       Richard W.M. Jones ("rjones at redhat dot com")
742
744       Copyright (C) 2009-2010 Red Hat Inc.
745
746       Derived from code by Petter Nordahl-Hagen under a compatible license:
747       Copyright (C) 1997-2007 Petter Nordahl-Hagen.
748
749       Derived from code by Markus Stephany under a compatible license:
750       Copyright (C) 2000-2004 Markus Stephany.
751
752       This library is free software; you can redistribute it and/or modify it
753       under the terms of the GNU Lesser General Public License as published
754       by the Free Software Foundation; version 2.1 of the License only.
755
756       This library is distributed in the hope that it will be useful, but
757       WITHOUT ANY WARRANTY; without even the implied warranty of
758       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
759       Lesser General Public License for more details.
760
761
762
763hivex-1.3.23                      2023-01-18                          hivex(3)
Impressum