1hivex(3) Windows Registry hivex(3)
2
3
4
6 hivex - Windows Registry "hive" extraction library
7
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
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
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
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
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
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
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
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
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
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
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)