5 hivex - Windows Registry "hive" extraction library
9 hive_h *hivex_open (const char *filename, int flags);
10 int hivex_close (hive_h *h);
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, and to have limited functionality (writing or
17 modifying these files is not in the scope of this library).
19 Unlike many other tools in this area, it doesn't use the textual .REG
20 format for output, because parsing that is as much trouble as parsing
21 the original binary format. Instead it makes the file available
22 through a C API, or there is a separate program to export the hive as
23 XML (see L<hivexml(1)>), or to get individual keys (see
26 =head2 OPENING AND CLOSING A HIVE
30 =item hive_h *hivex_open (const char *filename, int flags);
32 Opens the hive named C<filename> for reading.
34 Flags is an ORed list of the open flags (or C<0> if you don't
35 want to pass any flags). Currently the only
40 =item HIVEX_OPEN_VERBOSE
44 =item HIVEX_OPEN_DEBUG
46 Very verbose messages, suitable for debugging problems in the library
49 This is also selected if the C<HIVEX_DEBUG> environment variable
54 C<hivex_open> returns a hive handle. On error this returns NULL and
55 sets C<errno> to indicate the error.
57 =item int hivex_close (hive_h *h);
59 Close a hive handle and free all associated resources.
61 Returns 0 on success. On error this returns -1 and sets errno.
65 =head2 NAVIGATING THE TREE OF HIVE SUBKEYS
71 This is a node handle, an integer but opaque outside the library.
72 Valid node handles cannot be 0. The library returns 0 in some
73 situations to indicate an error.
75 =item hive_node_h hivex_root (hive_h *h);
77 Return root node of the hive. All valid registries must contain
80 On error this returns 0 and sets errno.
82 =item char *hivex_node_name (hive_h *h, hive_node_h node);
84 Return the name of the node. The name is reencoded as UTF-8
85 and returned as a C string.
87 The string should be freed by the caller when it is no longer needed.
89 Note that the name of the root node is a dummy, such as
90 C<$$$PROTO.HIV> (other names are possible: it seems to depend on the
91 tool or program that created the hive in the first place). You can
92 only know the "real" name of the root node by knowing which registry
93 file this hive originally comes from, which is knowledge that is
94 outside the scope of this library.
96 On error this returns NULL and sets errno.
98 =item hive_node_h *hivex_node_children (hive_h *h, hive_node_h node);
100 Return a 0-terminated array of nodes which are the subkeys
101 (children) of C<node>.
103 The array should be freed by the caller when it is no longer needed.
105 On error this returns NULL and sets errno.
107 =item hive_node_h hivex_node_get_child (hive_h *h, hive_node_h node, const char *name);
109 Return the child of node with the name C<name>, if it exists.
111 The name is matched case insensitively.
113 If the child node does not exist, this returns 0 without
116 On error this returns 0 and sets errno.
118 =item hive_node_h hivex_node_parent (hive_h *h, hive_node_h node);
120 Return the parent of C<node>.
122 On error this returns 0 and sets errno.
124 The parent pointer of the root node in registry files that we
125 have examined seems to be invalid, and so this function will
126 return an error if called on the root node.
130 =head2 GETTING VALUES AT A NODE
132 The enum below describes the possible types for the value(s)
138 hive_t_expand_string = 2,
143 hive_t_multiple_strings = 7,
144 hive_t_resource_list = 8,
145 hive_t_full_resource_description = 9,
146 hive_t_resource_requirements_list = 10,
154 This is a value handle, an integer but opaque outside the library.
155 Valid value handles cannot be 0. The library returns 0 in some
156 situations to indicate an error.
158 =item hive_value_h *hivex_node_values (hive_h *h, hive_node_h node);
160 Return the 0-terminated array of (key, value) pairs attached to
163 The array should be freed by the caller when it is no longer needed.
165 On error this returns NULL and sets errno.
167 =item hive_value_h hivex_node_get_value (hive_h *h, hive_node_h node, const char *key);
169 Return the value attached to this node which has the name C<key>,
172 The key name is matched case insensitively.
174 Note that to get the default key, you should pass the empty
175 string C<""> here. The default key is often written C<"@">, but
176 inside hives that has no meaning and won't give you the
179 If no such key exists, this returns 0 and does not set errno.
181 On error this returns 0 and sets errno.
183 =item char *hivex_value_key (hive_h *h, hive_value_h value);
185 Return the key (name) of a (key, value) pair. The name
186 is reencoded as UTF-8 and returned as a C string.
188 The string should be freed by the caller when it is no longer needed.
190 Note that this function can return a zero-length string. In the
191 context of Windows Registries, this means that this value is the
192 default key for this node in the tree. This is usually written
195 On error this returns NULL and sets errno.
197 =item int hivex_value_type (hive_h *h, hive_value_h value, hive_type *t, size_t *len);
199 Return the data type and length of the value in this (key, value)
200 pair. See also C<hivex_value_value> which returns all this
201 information, and the value itself. Also, C<hivex_value_*> functions
202 below which can be used to return the value in a more useful form when
203 you know the type in advance.
205 Returns 0 on success. On error this returns -1 and sets errno.
207 =item char *hivex_value_value (hive_h *h, hive_value_h value, hive_type *t, size_t *len);
209 Return the value of this (key, value) pair. The value should
210 be interpreted according to its type (see C<enum hive_type>).
212 The value is returned in an array of bytes of length C<len>.
214 The value should be freed by the caller when it is no longer needed.
216 On error this returns NULL and sets errno.
218 =item char *hivex_value_string (hive_h *h, hive_value_h value);
220 If this value is a string, return the string reencoded as UTF-8
221 (as a C string). This only works for values which have type
222 C<hive_t_string>, C<hive_t_expand_string> or C<hive_t_link>.
224 The string should be freed by the caller when it is no longer needed.
226 On error this returns NULL and sets errno.
228 =item char **hivex_value_multiple_strings (hive_h *h, hive_value_h value);
230 If this value is a multiple-string, return the strings reencoded
231 as UTF-8 (as a NULL-terminated array of C strings). This only
232 works for values which have type C<hive_t_multiple_strings>.
234 The string array and each string in it should be freed by the
235 caller when they are no longer needed.
237 On error this returns NULL and sets errno.
239 =item int32_t hivex_value_dword (hive_h *h, hive_value_h value);
241 If this value is a DWORD (Windows int32), return it. This only works
242 for values which have type C<hive_t_dword> or C<hive_t_dword_be>.
244 =item int64_t hivex_value_qword (hive_h *h, hive_value_h value);
246 If this value is a QWORD (Windows int64), return it. This only
247 works for values which have type C<hive_t_qword>.
251 =head2 VISITING ALL NODES
253 The visitor pattern is useful if you want to visit all nodes
254 in the tree or all nodes below a certain point in the tree.
256 First you set up your own C<struct hivex_visitor> with your
259 Each of these callback functions should return 0 on success or -1
260 on error. If any callback returns -1, then the entire visit
261 terminates immediately. If you don't need a callback function at
262 all, set the function pointer to NULL.
264 struct hivex_visitor {
265 int (*node_start) (hive_h *, void *opaque, hive_node_h, const char *name);
266 int (*node_end) (hive_h *, void *opaque, hive_node_h, const char *name);
267 int (*value_string) (hive_h *, void *opaque, hive_node_h, hive_value_h,
268 hive_type t, size_t len, const char *key, const char *str);
269 int (*value_multiple_strings) (hive_h *, void *opaque, hive_node_h,
270 hive_value_h, hive_type t, size_t len, const char *key, char **argv);
271 int (*value_string_invalid_utf16) (hive_h *, void *opaque, hive_node_h,
272 hive_value_h, hive_type t, size_t len, const char *key,
274 int (*value_dword) (hive_h *, void *opaque, hive_node_h, hive_value_h,
275 hive_type t, size_t len, const char *key, int32_t);
276 int (*value_qword) (hive_h *, void *opaque, hive_node_h, hive_value_h,
277 hive_type t, size_t len, const char *key, int64_t);
278 int (*value_binary) (hive_h *, void *opaque, hive_node_h, hive_value_h,
279 hive_type t, size_t len, const char *key, const char *value);
280 int (*value_none) (hive_h *, void *opaque, hive_node_h, hive_value_h,
281 hive_type t, size_t len, const char *key, const char *value);
282 int (*value_other) (hive_h *, void *opaque, hive_node_h, hive_value_h,
283 hive_type t, size_t len, const char *key, const char *value);
284 /* If value_any callback is not NULL, then the other value_*
285 * callbacks are not used, and value_any is called on all values.
287 int (*value_any) (hive_h *, void *opaque, hive_node_h, hive_value_h,
288 hive_type t, size_t len, const char *key, const char *value);
293 =item int hivex_visit (hive_h *h, const struct hivex_visitor *visitor, size_t len, void *opaque, int flags);
295 Visit all the nodes recursively in the hive C<h>.
297 C<visitor> should be a C<hivex_visitor> structure with callback
298 fields filled in as required (unwanted callbacks can be set to
299 NULL). C<len> must be the length of the 'visitor' struct (you
300 should pass C<sizeof (struct hivex_visitor)> for this).
302 This returns 0 if the whole recursive visit was completed
303 successfully. On error this returns -1. If one of the callback
304 functions returned an error than we don't touch errno. If the
305 error was generated internally then we set errno.
307 You can skip bad registry entries by setting C<flag> to
308 C<HIVEX_VISIT_SKIP_BAD>. If this flag is not set, then a bad registry
309 causes the function to return an error immediately.
311 This function is robust if the registry contains cycles or
312 pointers which are invalid or outside the registry. It detects
313 these cases and returns an error.
315 =item int hivex_visit_node (hive_h *h, hive_node_h node, const struct hivex_visitor *visitor, size_t len, void *opaque);
317 Same as C<hivex_visit> but instead of starting out at the root, this
322 =head1 THE STRUCTURE OF THE WINDOWS REGISTRY
324 Note: To understand the relationship between hives and the common
325 Windows Registry keys (like C<HKEY_LOCAL_MACHINE>) please see the
326 Wikipedia page on the Windows Registry.
328 The Windows Registry is split across various binary files, each
329 file being known as a "hive". This library only handles a single
332 Hives are n-ary trees with a single root. Each node in the tree
335 Each node in the tree (including non-leaf nodes) may have an
336 arbitrary list of (key, value) pairs attached to it. It may
337 be the case that one of these pairs has an empty key. This
338 is referred to as the default key for the node.
340 The (key, value) pairs are the place where the useful data is
341 stored in the registry. The key is always a string (possibly the
342 empty string for the default key). The value is a typed object
343 (eg. string, int32, binary, etc.).
345 =head2 RELATIONSHIP TO .REG FILES
347 Although this library does not care about or deal with Windows reg
348 files, it's useful to look at the relationship between the registry
349 itself and reg files because they are so common.
351 A reg file is a text representation of the registry, or part of the
352 registry. The actual registry hives that Windows uses are binary
353 files. There are a number of Windows and Linux tools that let you
354 generate reg files, or merge reg files back into the registry hives.
355 Notable amongst them is Microsoft's REGEDIT program (formerly known as
358 A typical reg file will contain many sections looking like this:
360 [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Stack]
362 "TileInfo"="prop:System.FileCount"
363 "TilePath"=str(2):"%systemroot%\\system32"
364 "ThumbnailCutoff"=dword:00000000
365 "FriendlyTypeName"=hex(2):40,00,25,00,53,00,79,00,73,00,74,00,65,00,6d,00,52,00,6f,00,\
366 6f,00,74,00,25,00,5c,00,53,00,79,00,73,00,74,00,65,00,6d,00,\
367 33,00,32,00,5c,00,73,00,65,00,61,00,72,00,63,00,68,00,66,00,\
368 6f,00,6c,00,64,00,65,00,72,00,2e,00,64,00,6c,00,6c,00,2c,00,\
369 2d,00,39,00,30,00,32,00,38,00,00,00,d8
371 Taking this one piece at a time:
373 [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Stack]
375 This is the path to this node in the registry tree. The first part,
376 C<HKEY_LOCAL_MACHINE\SOFTWARE> means that this comes from a hive
377 (file) called C<SOFTWARE>. C<\Classes\Stack> is the real path part,
378 starting at the root node of the C<SOFTWARE> hive.
380 Below the node name is a list of zero or more key-value pairs. Any
381 interior or leaf node in the registry may have key-value pairs
386 This is the "default key". In reality (ie. inside the binary hive)
387 the key string is the empty string. In reg files this is written as
388 C<@> but this has no meaning either in the hives themselves or in this
389 library. The value is a string (type 1 - see C<enum hive_type>
392 "TileInfo"="prop:System.FileCount"
394 This is a regular (key, value) pair, with the value being a type 1
395 string. Note that inside the binary file the string is likely to be
396 UTF-16 encoded. This library converts to and from UTF-8 strings
399 "TilePath"=str(2):"%systemroot%\\system32"
401 The value in this case has type 2 (expanded string) meaning that some
402 %...% variables get expanded by Windows. (This library doesn't know
403 or care about variable expansion).
405 "ThumbnailCutoff"=dword:00000000
407 The value in this case is a dword (type 4).
409 "FriendlyTypeName"=hex(2):40,00,....
411 This value is an expanded string (type 2) represented in the reg file
412 as a series of hex bytes. In this case the string appears to be a
415 =head1 NOTE ON THE USE OF ERRNO
417 Many functions in this library set errno to indicate errors. These
418 are the values of errno you may encounter (this list is not
425 Corrupt or unsupported Registry file format.
433 Passed an invalid argument to the function.
437 Followed a Registry pointer which goes outside
438 the registry or outside a registry block.
442 Registry contains cycles.
446 Field in the registry out of range.
450 =head1 ENVIRONMENT VARIABLES
456 Setting HIVEX_DEBUG=1 will enable very verbose messages. This is
457 useful for debugging problems with the library itself.
467 L<http://libguestfs.org/>,
470 L<http://en.wikipedia.org/wiki/Windows_Registry>.
474 Richard W.M. Jones (C<rjones at redhat dot com>)
478 Copyright (C) 2009-2010 Red Hat Inc.
480 Derived from code by Petter Nordahl-Hagen under a compatible license:
481 Copyright (C) 1997-2007 Petter Nordahl-Hagen.
483 Derived from code by Markus Stephany under a compatible license:
484 Copyright (C) 2000-2004 Markus Stephany.
486 This library is free software; you can redistribute it and/or
487 modify it under the terms of the GNU Lesser General Public
488 License as published by the Free Software Foundation;
489 version 2.1 of the License.
491 This library is distributed in the hope that it will be useful,
492 but WITHOUT ANY WARRANTY; without even the implied warranty of
493 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
494 Lesser General Public License for more details.
496 See file LICENSE for the full license.