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
69 =item hive_node_h hivex_root (hive_h *h);
71 Return root node of the hive. All valid registries must contain
74 On error this returns 0 and sets errno.
76 =item char *hivex_node_name (hive_h *h, hive_node_h node);
78 Return the name of the node. The name is reencoded as UTF-8
79 and returned as a C string.
81 The string should be freed by the caller when it is no longer needed.
83 Note that the name of the root node is a dummy, such as
84 C<$$$PROTO.HIV> (other names are possible: it seems to depend on the
85 tool or program that created the hive in the first place). You can
86 only know the "real" name of the root node by knowing which registry
87 file this hive originally comes from, which is knowledge that is
88 outside the scope of this library.
90 On error this returns NULL and sets errno.
92 =item hive_node_h *hivex_node_children (hive_h *h, hive_node_h node);
94 Return a 0-terminated array of nodes which are the subkeys
95 (children) of C<node>.
97 The array should be freed by the caller when it is no longer needed.
99 On error this returns NULL and sets errno.
101 =item hive_node_h hivex_node_get_child (hive_h *h, hive_node_h node, const char *name);
103 Return the child of node with the name C<name>, if it exists.
105 The name is matched case insensitively.
107 If the child node does not exist, this returns 0 without
110 On error this returns 0 and sets errno.
112 =item hive_node_h hivex_node_parent (hive_h *h, hive_node_h node);
114 Return the parent of C<node>.
116 On error this returns 0 and sets errno.
118 The parent pointer of the root node in registry files that we
119 have examined seems to be invalid, and so this function will
120 return an error if called on the root node.
124 =head2 GETTING VALUES AT A NODE
126 The enum below describes the possible types for the value(s)
132 hive_t_expand_string = 2,
137 hive_t_multiple_strings = 7,
138 hive_t_resource_list = 8,
139 hive_t_full_resource_description = 9,
140 hive_t_resource_requirements_list = 10,
146 =item hive_value_h *hivex_node_values (hive_h *h, hive_node_h node);
148 Return the 0-terminated array of (key, value) pairs attached to
151 The array should be freed by the caller when it is no longer needed.
153 On error this returns NULL and sets errno.
155 =item hive_value_h hivex_node_get_value (hive_h *h, hive_node_h node, const char *key);
157 Return the value attached to this node which has the name C<key>,
160 The key name is matched case insensitively.
162 Note that to get the default key, you should pass the empty
163 string C<""> here. The default key is often written C<"@">, but
164 inside hives that has no meaning and won't give you the
167 If no such key exists, this returns 0 and does not set errno.
169 On error this returns 0 and sets errno.
171 =item char *hivex_value_key (hive_h *h, hive_value_h value);
173 Return the key (name) of a (key, value) pair. The name
174 is reencoded as UTF-8 and returned as a C string.
176 The string should be freed by the caller when it is no longer needed.
178 Note that this function can return a zero-length string. In the
179 context of Windows Registries, this means that this value is the
180 default key for this node in the tree. This is usually written
183 On error this returns NULL and sets errno.
185 =item int hivex_value_type (hive_h *h, hive_value_h value, hive_type *t, size_t *len);
187 Return the data type and length of the value in this (key, value)
188 pair. See also C<hivex_value_value> which returns all this
189 information, and the value itself. Also, C<hivex_value_*> functions
190 below which can be used to return the value in a more useful form when
191 you know the type in advance.
193 Returns 0 on success. On error this returns -1 and sets errno.
195 =item char *hivex_value_value (hive_h *h, hive_value_h value, hive_type *t, size_t *len);
197 Return the value of this (key, value) pair. The value should
198 be interpreted according to its type (see C<hive_type>).
200 The value is returned in an array of bytes of length C<len>.
202 The value should be freed by the caller when it is no longer needed.
204 On error this returns NULL and sets errno.
206 =item char *hivex_value_string (hive_h *h, hive_value_h value);
208 If this value is a string, return the string reencoded as UTF-8
209 (as a C string). This only works for values which have type
210 C<hive_t_string>, C<hive_t_expand_string> or C<hive_t_link>.
212 The string should be freed by the caller when it is no longer needed.
214 On error this returns NULL and sets errno.
216 =item char **hivex_value_multiple_strings (hive_h *h, hive_value_h value);
218 If this value is a multiple-string, return the strings reencoded
219 as UTF-8 (as a NULL-terminated array of C strings). This only
220 works for values which have type C<hive_t_multiple_strings>.
222 The string array and each string in it should be freed by the
223 caller when they are no longer needed.
225 On error this returns NULL and sets errno.
227 =item int32_t hivex_value_dword (hive_h *h, hive_value_h value);
229 If this value is a DWORD (Windows int32), return it. This only works
230 for values which have type C<hive_t_dword> or C<hive_t_dword_be>.
232 =item int64_t hivex_value_qword (hive_h *h, hive_value_h value);
234 If this value is a QWORD (Windows int64), return it. This only
235 works for values which have type C<hive_t_qword>.
239 =head2 VISITING ALL NODES
241 The visitor pattern is useful if you want to visit all nodes
242 in the tree or all nodes below a certain point in the tree.
244 First you set up your own C<struct hivex_visitor> with your
247 Each of these callback functions should return 0 on success or -1
248 on error. If any callback returns -1, then the entire visit
249 terminates immediately. If you don't need a callback function at
250 all, set the function pointer to NULL.
252 struct hivex_visitor {
253 int (*node_start) (hive_h *, void *opaque, hive_node_h, const char *name);
254 int (*node_end) (hive_h *, void *opaque, hive_node_h, const char *name);
255 int (*value_string) (hive_h *, void *opaque, hive_node_h, hive_value_h,
256 hive_type t, size_t len, const char *key, const char *str);
257 int (*value_multiple_strings) (hive_h *, void *opaque, hive_node_h,
258 hive_value_h, hive_type t, size_t len, const char *key, char **argv);
259 int (*value_string_invalid_utf16) (hive_h *, void *opaque, hive_node_h,
260 hive_value_h, hive_type t, size_t len, const char *key,
262 int (*value_dword) (hive_h *, void *opaque, hive_node_h, hive_value_h,
263 hive_type t, size_t len, const char *key, int32_t);
264 int (*value_qword) (hive_h *, void *opaque, hive_node_h, hive_value_h,
265 hive_type t, size_t len, const char *key, int64_t);
266 int (*value_binary) (hive_h *, void *opaque, hive_node_h, hive_value_h,
267 hive_type t, size_t len, const char *key, const char *value);
268 int (*value_none) (hive_h *, void *opaque, hive_node_h, hive_value_h,
269 hive_type t, size_t len, const char *key, const char *value);
270 int (*value_other) (hive_h *, void *opaque, hive_node_h, hive_value_h,
271 hive_type t, size_t len, const char *key, const char *value);
276 =item int hivex_visit (hive_h *h, const struct hivex_visitor *visitor, size_t len, void *opaque, int flags);
278 Visit all the nodes recursively in the hive C<h>.
280 C<visitor> should be a C<hivex_visitor> structure with callback
281 fields filled in as required (unwanted callbacks can be set to
282 NULL). C<len> must be the length of the 'visitor' struct (you
283 should pass C<sizeof (struct hivex_visitor)> for this).
285 This returns 0 if the whole recursive visit was completed
286 successfully. On error this returns -1. If one of the callback
287 functions returned an error than we don't touch errno. If the
288 error was generated internally then we set errno.
290 You can skip bad registry entries by setting C<flag> to
291 C<HIVEX_VISIT_SKIP_BAD>. If this flag is not set, then a bad registry
292 causes the function to return an error immediately.
294 This function is robust if the registry contains cycles or
295 pointers which are invalid or outside the registry. It detects
296 these cases and returns an error.
298 =item int hivex_visit_node (hive_h *h, hive_node_h node, const struct hivex_visitor *visitor, size_t len, void *opaque);
300 Same as C<hivex_visit> but instead of starting out at the root, this
305 =head1 THE STRUCTURE OF THE WINDOWS REGISTRY
307 Note: To understand the relationship between hives and the common
308 Windows Registry keys (like C<HKEY_LOCAL_MACHINE>) please see the
309 Wikipedia page on the Windows Registry.
311 The Windows Registry is split across various binary files, each
312 file being known as a "hive". This library only handles a single
315 Hives are n-ary trees with a single root. Each node in the tree
318 Each node in the tree (including non-leaf nodes) may have an
319 arbitrary list of (key, value) pairs attached to it. It may
320 be the case that one of these pairs has an empty key. This
321 is referred to as the default key for the node.
323 The (key, value) pairs are the place where the useful data is
324 stored in the registry. The key is always a string (possibly the
325 empty string for the default key). The value is a typed object
326 (eg. string, int32, binary, etc.).
328 =head1 NOTE ON THE USE OF ERRNO
330 Many functions in this library set errno to indicate errors.
331 These are the values of errno you may encounter:
337 Corrupt or unsupported Registry file format.
345 Passed an invalid argument to the function.
349 Followed a Registry pointer which goes outside
350 the registry or outside a registry block.
354 Registry contains cycles.
358 Field in the registry out of range.
368 L<http://libguestfs.org/>,
374 Richard W.M. Jones (C<rjones at redhat dot com>)
378 Copyright (C) 2009 Red Hat Inc.
380 Derived from code by Petter Nordahl-Hagen under a compatible license:
381 Copyright (c) 1997-2007 Petter Nordahl-Hagen.
383 Derived from code by Markus Stephany under a compatible license:
384 Copyright (c)2000-2004, Markus Stephany.
386 This library is free software; you can redistribute it and/or
387 modify it under the terms of the GNU Lesser General Public
388 License as published by the Free Software Foundation;
389 version 2.1 of the License.
391 This library is distributed in the hope that it will be useful,
392 but WITHOUT ANY WARRANTY; without even the implied warranty of
393 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
394 Lesser General Public License for more details.
396 See file LICENSE for the full license.