hivex: Fix handling of inline VKs.
[libguestfs.git] / hivex / hivex.pod
1 =encoding utf8
2
3 =head1 NAME
4
5 hivex - Windows Registry "hive" extraction library
6
7 =head1 SYNOPSIS
8
9  hive_h *hivex_open (const char *filename, int flags);
10  int hivex_close (hive_h *h);
11
12 =head1 DESCRIPTION
13
14 libhivex is a library for extracting the contents of Windows Registry
15 "hive" files.  It is designed to be secure against buggy or malicious
16 registry files.
17
18 Unlike many other tools in this area, it doesn't use the textual .REG
19 format for output, because parsing that is as much trouble as parsing
20 the original binary format.  Instead it makes the file available
21 through a C API, or there is a separate program to export the hive as
22 XML (see L<hivexml(1)>), or to get individual keys (see
23 L<hivexget(1)>).
24
25 =head2 OPENING AND CLOSING A HIVE
26
27 =over 4
28
29 =item hive_h *hivex_open (const char *filename, int flags);
30
31 Opens the hive named C<filename> for reading.
32
33 Flags is an ORed list of the open flags (or C<0> if you don't
34 want to pass any flags).  These flags are defined:
35
36 =over 4
37
38 =item HIVEX_OPEN_VERBOSE
39
40 Verbose messages.
41
42 =item HIVEX_OPEN_DEBUG
43
44 Very verbose messages, suitable for debugging problems in the library
45 itself.
46
47 This is also selected if the C<HIVEX_DEBUG> environment variable
48 is set to 1.
49
50 =item HIVEX_OPEN_WRITE
51
52 Open the hive for writing.  If omitted, the hive is read-only.
53
54 See L</WRITING TO HIVE FILES>.
55
56 =back
57
58 C<hivex_open> returns a hive handle.  On error this returns NULL and
59 sets C<errno> to indicate the error.
60
61 =item int hivex_close (hive_h *h);
62
63 Close a hive handle and free all associated resources.
64
65 Note that any uncommitted writes are I<not> committed by this call,
66 but instead are lost.  See L</WRITING TO HIVE FILES>.
67
68 Returns 0 on success.  On error this returns -1 and sets errno.
69
70 =back
71
72 =head2 NAVIGATING THE TREE OF HIVE SUBKEYS
73
74 =over 4
75
76 =item hive_node_h
77
78 This is a node handle, an integer but opaque outside the library.
79 Valid node handles cannot be 0.  The library returns 0 in some
80 situations to indicate an error.
81
82 =item hive_node_h hivex_root (hive_h *h);
83
84 Return root node of the hive.  All valid registries must contain
85 a root node.
86
87 On error this returns 0 and sets errno.
88
89 =item char *hivex_node_name (hive_h *h, hive_node_h node);
90
91 Return the name of the node.  The name is reencoded as UTF-8
92 and returned as a C string.
93
94 The string should be freed by the caller when it is no longer needed.
95
96 Note that the name of the root node is a dummy, such as
97 C<$$$PROTO.HIV> (other names are possible: it seems to depend on the
98 tool or program that created the hive in the first place).  You can
99 only know the "real" name of the root node by knowing which registry
100 file this hive originally comes from, which is knowledge that is
101 outside the scope of this library.
102
103 On error this returns NULL and sets errno.
104
105 =item hive_node_h *hivex_node_children (hive_h *h, hive_node_h node);
106
107 Return a 0-terminated array of nodes which are the subkeys
108 (children) of C<node>.
109
110 The array should be freed by the caller when it is no longer needed.
111
112 On error this returns NULL and sets errno.
113
114 =item hive_node_h hivex_node_get_child (hive_h *h, hive_node_h node, const char *name);
115
116 Return the child of node with the name C<name>, if it exists.
117
118 The name is matched case insensitively.
119
120 If the child node does not exist, this returns 0 without
121 setting errno.
122
123 On error this returns 0 and sets errno.
124
125 =item hive_node_h hivex_node_parent (hive_h *h, hive_node_h node);
126
127 Return the parent of C<node>.
128
129 On error this returns 0 and sets errno.
130
131 The parent pointer of the root node in registry files that we
132 have examined seems to be invalid, and so this function will
133 return an error if called on the root node.
134
135 =back
136
137 =head2 GETTING VALUES AT A NODE
138
139 The enum below describes the possible types for the value(s)
140 stored at each node.
141
142  enum hive_type {
143    hive_t_none = 0,
144    hive_t_string = 1,
145    hive_t_expand_string = 2,
146    hive_t_binary = 3,
147    hive_t_dword = 4,
148    hive_t_dword_be = 5,
149    hive_t_link = 6,
150    hive_t_multiple_strings = 7,
151    hive_t_resource_list = 8,
152    hive_t_full_resource_description = 9,
153    hive_t_resource_requirements_list = 10,
154    hive_t_qword = 11
155  };
156
157 =over 4
158
159 =item hive_value_h
160
161 This is a value handle, an integer but opaque outside the library.
162 Valid value handles cannot be 0.  The library returns 0 in some
163 situations to indicate an error.
164
165 =item hive_value_h *hivex_node_values (hive_h *h, hive_node_h node);
166
167 Return the 0-terminated array of (key, value) pairs attached to
168 this node.
169
170 The array should be freed by the caller when it is no longer needed.
171
172 On error this returns NULL and sets errno.
173
174 =item hive_value_h hivex_node_get_value (hive_h *h, hive_node_h node, const char *key);
175
176 Return the value attached to this node which has the name C<key>,
177 if it exists.
178
179 The key name is matched case insensitively.
180
181 Note that to get the default key, you should pass the empty
182 string C<""> here.  The default key is often written C<"@">, but
183 inside hives that has no meaning and won't give you the
184 default key.
185
186 If no such key exists, this returns 0 and does not set errno.
187
188 On error this returns 0 and sets errno.
189
190 =item char *hivex_value_key (hive_h *h, hive_value_h value);
191
192 Return the key (name) of a (key, value) pair.  The name
193 is reencoded as UTF-8 and returned as a C string.
194
195 The string should be freed by the caller when it is no longer needed.
196
197 Note that this function can return a zero-length string.  In the
198 context of Windows Registries, this means that this value is the
199 default key for this node in the tree.  This is usually written
200 as C<"@">.
201
202 On error this returns NULL and sets errno.
203
204 =item int hivex_value_type (hive_h *h, hive_value_h value, hive_type *t, size_t *len);
205
206 Return the data type and length of the value in this (key, value)
207 pair.  See also C<hivex_value_value> which returns all this
208 information, and the value itself.  Also, C<hivex_value_*> functions
209 below which can be used to return the value in a more useful form when
210 you know the type in advance.
211
212 Returns 0 on success.  On error this returns -1 and sets errno.
213
214 =item char *hivex_value_value (hive_h *h, hive_value_h value, hive_type *t, size_t *len);
215
216 Return the value of this (key, value) pair.  The value should
217 be interpreted according to its type (see C<enum hive_type>).
218
219 The value is returned in an array of bytes of length C<len>.
220
221 The value should be freed by the caller when it is no longer needed.
222
223 On error this returns NULL and sets errno.
224
225 =item char *hivex_value_string (hive_h *h, hive_value_h value);
226
227 If this value is a string, return the string reencoded as UTF-8
228 (as a C string).  This only works for values which have type
229 C<hive_t_string>, C<hive_t_expand_string> or C<hive_t_link>.
230
231 The string should be freed by the caller when it is no longer needed.
232
233 On error this returns NULL and sets errno.
234
235 =item char **hivex_value_multiple_strings (hive_h *h, hive_value_h value);
236
237 If this value is a multiple-string, return the strings reencoded
238 as UTF-8 (as a NULL-terminated array of C strings).  This only
239 works for values which have type C<hive_t_multiple_strings>.
240
241 The string array and each string in it should be freed by the
242 caller when they are no longer needed.
243
244 On error this returns NULL and sets errno.
245
246 =item int32_t hivex_value_dword (hive_h *h, hive_value_h value);
247
248 If this value is a DWORD (Windows int32), return it.  This only works
249 for values which have type C<hive_t_dword> or C<hive_t_dword_be>.
250
251 =item int64_t hivex_value_qword (hive_h *h, hive_value_h value);
252
253 If this value is a QWORD (Windows int64), return it.  This only
254 works for values which have type C<hive_t_qword>.
255
256 =back
257
258 =head2 VISITING ALL NODES
259
260 The visitor pattern is useful if you want to visit all nodes
261 in the tree or all nodes below a certain point in the tree.
262
263 First you set up your own C<struct hivex_visitor> with your
264 callback functions.
265
266 Each of these callback functions should return 0 on success or -1
267 on error.  If any callback returns -1, then the entire visit
268 terminates immediately.  If you don't need a callback function at
269 all, set the function pointer to NULL.
270
271  struct hivex_visitor {
272    int (*node_start) (hive_h *, void *opaque, hive_node_h, const char *name);
273    int (*node_end) (hive_h *, void *opaque, hive_node_h, const char *name);
274    int (*value_string) (hive_h *, void *opaque, hive_node_h, hive_value_h,
275          hive_type t, size_t len, const char *key, const char *str);
276    int (*value_multiple_strings) (hive_h *, void *opaque, hive_node_h,
277          hive_value_h, hive_type t, size_t len, const char *key, char **argv);
278    int (*value_string_invalid_utf16) (hive_h *, void *opaque, hive_node_h,
279          hive_value_h, hive_type t, size_t len, const char *key,
280          const char *str);
281    int (*value_dword) (hive_h *, void *opaque, hive_node_h, hive_value_h,
282          hive_type t, size_t len, const char *key, int32_t);
283    int (*value_qword) (hive_h *, void *opaque, hive_node_h, hive_value_h,
284          hive_type t, size_t len, const char *key, int64_t);
285    int (*value_binary) (hive_h *, void *opaque, hive_node_h, hive_value_h,
286          hive_type t, size_t len, const char *key, const char *value);
287    int (*value_none) (hive_h *, void *opaque, hive_node_h, hive_value_h,
288          hive_type t, size_t len, const char *key, const char *value);
289    int (*value_other) (hive_h *, void *opaque, hive_node_h, hive_value_h,
290          hive_type t, size_t len, const char *key, const char *value);
291    /* If value_any callback is not NULL, then the other value_*
292     * callbacks are not used, and value_any is called on all values.
293     */
294    int (*value_any) (hive_h *, void *opaque, hive_node_h, hive_value_h,
295          hive_type t, size_t len, const char *key, const char *value);
296  };
297
298 =over 4
299
300 =item int hivex_visit (hive_h *h, const struct hivex_visitor *visitor, size_t len, void *opaque, int flags);
301
302 Visit all the nodes recursively in the hive C<h>.
303
304 C<visitor> should be a C<hivex_visitor> structure with callback
305 fields filled in as required (unwanted callbacks can be set to
306 NULL).  C<len> must be the length of the 'visitor' struct (you
307 should pass C<sizeof (struct hivex_visitor)> for this).
308
309 This returns 0 if the whole recursive visit was completed
310 successfully.  On error this returns -1.  If one of the callback
311 functions returned an error than we don't touch errno.  If the
312 error was generated internally then we set errno.
313
314 You can skip bad registry entries by setting C<flag> to
315 C<HIVEX_VISIT_SKIP_BAD>.  If this flag is not set, then a bad registry
316 causes the function to return an error immediately.
317
318 This function is robust if the registry contains cycles or
319 pointers which are invalid or outside the registry.  It detects
320 these cases and returns an error.
321
322 =item int hivex_visit_node (hive_h *h, hive_node_h node, const struct hivex_visitor *visitor, size_t len, void *opaque);
323
324 Same as C<hivex_visit> but instead of starting out at the root, this
325 starts at C<node>.
326
327 =back
328
329 =head2 WRITING TO HIVE FILES
330
331 The hivex library supports making limited modifications to hive files.
332 We have tried to implement this very conservatively in order to reduce
333 the chance of corrupting your registry.  However you should be careful
334 and take back-ups, since Microsoft has never documented the hive
335 format, and so it is possible there are nuances in the
336 reverse-engineered format that we do not understand.
337
338 To be able to modify a hive, you must pass the C<HIVEX_OPEN_WRITE>
339 flag to C<hivex_open>, otherwise any write operation will return with
340 errno C<EROFS>.
341
342 The write operations shown below do not modify the on-disk file
343 immediately.  You must call C<hivex_commit> in order to write the
344 changes to disk.  If you call C<hivex_close> without committing then
345 any writes are discarded.
346
347 Hive files internally consist of a "memory dump" of binary blocks
348 (like the C heap), and some of these blocks can be unused.  The hivex
349 library never reuses these unused blocks.  Instead, to ensure
350 robustness in the face of the partially understood on-disk format,
351 hivex only allocates new blocks after the end of the file, and makes
352 minimal modifications to existing structures in the file to point to
353 these new blocks.  This makes hivex slightly less disk-efficient than
354 it could be, but disk is cheap, and registry modifications tend to be
355 very small.
356
357 When deleting nodes, it is possible that this library may leave
358 unreachable live blocks in the hive.  This is because certain parts of
359 the hive disk format such as security (sk) records and big data (db)
360 records and classname fields are not well understood (and not
361 documented at all) and we play it safe by not attempting to modify
362 them.  Apart from wasting a little bit of disk space, it is not
363 thought that unreachable blocks are a problem.
364
365 =over 4
366
367 =item int hivex_commit (hive_h *h, const char *filename, int flags);
368
369 Commit (write) any changes which have been made.
370
371 C<filename> is the new file to write.  If C<filename == NULL> then we
372 overwrite the original file (ie. the file name that was passed to
373 C<hivex_open>).  C<flags> is not used, always pass 0.
374
375 Returns 0 on success.  On error this returns -1 and sets errno.
376
377 Note this does not close the hive handle.  You can perform further
378 operations on the hive after committing, including making more
379 modifications.  If you no longer wish to use the hive, call
380 C<hivex_close> after this.
381
382 =item hive_node_h hivex_node_add_child (hive_h *h, hive_node_h parent, const char *name);
383
384 Add a new child node named C<name> to the existing node C<parent>.
385 The new child initially has no subnodes and contains no keys or
386 values.  The sk-record (security descriptor) is inherited from
387 the parent.
388
389 The parent must not have an existing child called C<name>, so if you
390 want to overwrite an existing child, call C<hivex_node_delete_child>
391 first.
392
393 Returns the node handle.  On error this returns 0 and sets errno.
394
395 =item int hivex_node_delete_child (hive_h *h, hive_node_h node);
396
397 Delete the node C<node>.  All values at the node and all subnodes are
398 deleted (recursively).  The C<node> handle and the handles of all
399 subnodes become invalid.  You cannot delete the root node.
400
401 Returns 0 on success.  On error this returns -1 and sets errno.
402
403 =item hive_set_value
404
405 The typedef C<hive_set_value> is used in conjunction with the
406 C<hivex_node_set_values> call described below.
407
408  struct hive_set_value {
409    char *key;     /* key - a UTF-8 encoded ASCIIZ string */
410    hive_type t;   /* type of value field */
411    size_t len;    /* length of value field in bytes */
412    char *value;   /* value field */
413  };
414  typedef struct hive_set_value hive_set_value;
415
416 To set the default value for a node, you have to pass C<key = "">.
417
418 Note that the C<value> field is just treated as a list of bytes, and
419 is stored directly in the hive.  The caller has to ensure correct
420 encoding and endianness, for example converting dwords to little
421 endian.
422
423 The correct type and encoding for values depends on the node and key
424 in the registry, the version of Windows, and sometimes even changes
425 between versions of Windows for the same key.  We don't document it
426 here.  Often it's not documented at all.
427
428 =item int hivex_node_set_values (hive_h *h, hive_node_h node, size_t nr_values, const hive_set_value *values, int flags);
429
430 This call can be used to set all the (key, value) pairs stored in C<node>.
431
432 C<node> is the node to modify.  C<values> is an array of (key, value)
433 pairs.  There should be C<nr_values> elements in this array.  C<flags>
434 is not used, always pass 0.
435
436 Any existing values stored at the node are discarded, and their
437 C<hive_value_h> handles become invalid.  Thus you can remove all
438 values stored at C<node> by passing C<nr_values = 0>.
439
440 Returns 0 on success.  On error this returns -1 and sets errno.
441
442 Note that this library does not offer a way to modify just a single
443 key at a node.  We don't implement a way to do this efficiently.
444
445 =back
446
447 =head3 WRITE OPERATIONS WHICH ARE NOT SUPPORTED
448
449 =over 4
450
451 =item *
452
453 Changing the root node.
454
455 =item *
456
457 Creating a new hive file from scratch.  This is impossible at present
458 because not all fields in the header are understood.
459
460 =item *
461
462 Modifying or deleting single values at a node.
463
464 =item *
465
466 Modifying security key (sk) records or classnames.
467 Previously we did not understand these records.  However now they
468 are well-understood and we could add support if it was required
469 (but nothing much really uses them).
470
471 =back
472
473 =head1 THE STRUCTURE OF THE WINDOWS REGISTRY
474
475 Note: To understand the relationship between hives and the common
476 Windows Registry keys (like C<HKEY_LOCAL_MACHINE>) please see the
477 Wikipedia page on the Windows Registry.
478
479 The Windows Registry is split across various binary files, each
480 file being known as a "hive".  This library only handles a single
481 hive file at a time.
482
483 Hives are n-ary trees with a single root.  Each node in the tree
484 has a name.
485
486 Each node in the tree (including non-leaf nodes) may have an
487 arbitrary list of (key, value) pairs attached to it.  It may
488 be the case that one of these pairs has an empty key.  This
489 is referred to as the default key for the node.
490
491 The (key, value) pairs are the place where the useful data is
492 stored in the registry.  The key is always a string (possibly the
493 empty string for the default key).  The value is a typed object
494 (eg. string, int32, binary, etc.).
495
496 =head2 RELATIONSHIP TO .REG FILES
497
498 Although this library does not care about or deal with Windows reg
499 files, it's useful to look at the relationship between the registry
500 itself and reg files because they are so common.
501
502 A reg file is a text representation of the registry, or part of the
503 registry.  The actual registry hives that Windows uses are binary
504 files.  There are a number of Windows and Linux tools that let you
505 generate reg files, or merge reg files back into the registry hives.
506 Notable amongst them is Microsoft's REGEDIT program (formerly known as
507 REGEDT32).
508
509 A typical reg file will contain many sections looking like this:
510
511  [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Stack]
512  "@"="Generic Stack"
513  "TileInfo"="prop:System.FileCount"
514  "TilePath"=str(2):"%systemroot%\\system32"
515  "ThumbnailCutoff"=dword:00000000
516  "FriendlyTypeName"=hex(2):40,00,25,00,53,00,79,00,73,00,74,00,65,00,6d,00,52,00,6f,00,\
517   6f,00,74,00,25,00,5c,00,53,00,79,00,73,00,74,00,65,00,6d,00,\
518   33,00,32,00,5c,00,73,00,65,00,61,00,72,00,63,00,68,00,66,00,\
519   6f,00,6c,00,64,00,65,00,72,00,2e,00,64,00,6c,00,6c,00,2c,00,\
520   2d,00,39,00,30,00,32,00,38,00,00,00,d8
521
522 Taking this one piece at a time:
523
524  [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Stack]
525
526 This is the path to this node in the registry tree.  The first part,
527 C<HKEY_LOCAL_MACHINE\SOFTWARE> means that this comes from a hive
528 (file) called C<SOFTWARE>.  C<\Classes\Stack> is the real path part,
529 starting at the root node of the C<SOFTWARE> hive.
530
531 Below the node name is a list of zero or more key-value pairs.  Any
532 interior or leaf node in the registry may have key-value pairs
533 attached.
534
535  "@"="Generic Stack"
536
537 This is the "default key".  In reality (ie. inside the binary hive)
538 the key string is the empty string.  In reg files this is written as
539 C<@> but this has no meaning either in the hives themselves or in this
540 library.  The value is a string (type 1 - see C<enum hive_type>
541 above).
542
543  "TileInfo"="prop:System.FileCount"
544
545 This is a regular (key, value) pair, with the value being a type 1
546 string.  Note that inside the binary file the string is likely to be
547 UTF-16 encoded.  This library converts to and from UTF-8 strings
548 transparently.
549
550  "TilePath"=str(2):"%systemroot%\\system32"
551
552 The value in this case has type 2 (expanded string) meaning that some
553 %...% variables get expanded by Windows.  (This library doesn't know
554 or care about variable expansion).
555
556  "ThumbnailCutoff"=dword:00000000
557
558 The value in this case is a dword (type 4).
559
560  "FriendlyTypeName"=hex(2):40,00,....
561
562 This value is an expanded string (type 2) represented in the reg file
563 as a series of hex bytes.  In this case the string appears to be a
564 UTF-16 string.
565
566 =head1 NOTE ON THE USE OF ERRNO
567
568 Many functions in this library set errno to indicate errors.  These
569 are the values of errno you may encounter (this list is not
570 exhaustive):
571
572 =over 4
573
574 =item ENOTSUP
575
576 Corrupt or unsupported Registry file format.
577
578 =item ENOKEY
579
580 Missing root key.
581
582 =item EINVAL
583
584 Passed an invalid argument to the function.
585
586 =item EFAULT
587
588 Followed a Registry pointer which goes outside
589 the registry or outside a registry block.
590
591 =item ELOOP
592
593 Registry contains cycles.
594
595 =item ERANGE
596
597 Field in the registry out of range.
598
599 =item EEXIST
600
601 Registry key already exists.
602
603 =item EROFS
604
605 Tried to write to a registry which is not opened for writing.
606
607 =back
608
609 =head1 ENVIRONMENT VARIABLES
610
611 =over 4
612
613 =item HIVEX_DEBUG
614
615 Setting HIVEX_DEBUG=1 will enable very verbose messages.  This is
616 useful for debugging problems with the library itself.
617
618 =back
619
620 =head1 SEE ALSO
621
622 L<hivexml(1)>,
623 L<hivexget(1)>,
624 L<virt-win-reg(1)>,
625 L<guestfs(3)>,
626 L<http://libguestfs.org/>,
627 L<virt-cat(1)>,
628 L<virt-edit(1)>,
629 L<http://en.wikipedia.org/wiki/Windows_Registry>.
630
631 =head1 AUTHORS
632
633 Richard W.M. Jones (C<rjones at redhat dot com>)
634
635 =head1 COPYRIGHT
636
637 Copyright (C) 2009-2010 Red Hat Inc.
638
639 Derived from code by Petter Nordahl-Hagen under a compatible license:
640 Copyright (C) 1997-2007 Petter Nordahl-Hagen.
641
642 Derived from code by Markus Stephany under a compatible license:
643 Copyright (C) 2000-2004 Markus Stephany.
644
645 This library is free software; you can redistribute it and/or
646 modify it under the terms of the GNU Lesser General Public
647 License as published by the Free Software Foundation;
648 version 2.1 of the License.
649
650 This library is distributed in the hope that it will be useful,
651 but WITHOUT ANY WARRANTY; without even the implied warranty of
652 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
653 Lesser General Public License for more details.
654
655 See file LICENSE for the full license.