hivex - Windows Registry "hive" extraction library
hive_h *hivex_open (const char *filename, int flags); int hivex_close (hive_h *h);
libhivex is a library for extracting the contents of Windows Registry "hive" files. It is designed to be secure against buggy or malicious registry files.
Unlike many other tools in this area, it doesn't use the textual .REG format for output, because parsing that is as much trouble as parsing the original binary format. Instead it makes the file available through a C API, or there is a separate program to export the hive as XML (see hivexml(1)), or to get individual keys (see hivexget(1)).
Opens the hive named filename for reading.
Flags is an ORed list of the open flags (or 0 if you don't
want to pass any flags). These flags are defined:
Verbose messages.
Very verbose messages, suitable for debugging problems in the library itself.
This is also selected if the HIVEX_DEBUG environment variable
is set to 1.
Open the hive for writing. If omitted, the hive is read-only.
hivex_open returns a hive handle. On error this returns NULL and
sets errno to indicate the error.
Close a hive handle and free all associated resources.
Note that any uncommitted writes are not committed by this call, but instead are lost. See WRITING TO HIVE FILES.
Returns 0 on success. On error this returns -1 and sets errno.
This is a node handle, an integer but opaque outside the library. Valid node handles cannot be 0. The library returns 0 in some situations to indicate an error.
Return root node of the hive. All valid registries must contain a root node.
On error this returns 0 and sets errno.
Return the name of the node. The name is reencoded as UTF-8 and returned as a C string.
The string should be freed by the caller when it is no longer needed.
Note that the name of the root node is a dummy, such as
$$$PROTO.HIV (other names are possible: it seems to depend on the
tool or program that created the hive in the first place). You can
only know the "real" name of the root node by knowing which registry
file this hive originally comes from, which is knowledge that is
outside the scope of this library.
On error this returns NULL and sets errno.
Return a 0-terminated array of nodes which are the subkeys
(children) of node.
The array should be freed by the caller when it is no longer needed.
On error this returns NULL and sets errno.
Return the child of node with the name name, if it exists.
The name is matched case insensitively.
If the child node does not exist, this returns 0 without setting errno.
On error this returns 0 and sets errno.
Return the parent of node.
On error this returns 0 and sets errno.
The parent pointer of the root node in registry files that we have examined seems to be invalid, and so this function will return an error if called on the root node.
The enum below describes the possible types for the value(s) stored at each node.
enum hive_type {
hive_t_none = 0,
hive_t_string = 1,
hive_t_expand_string = 2,
hive_t_binary = 3,
hive_t_dword = 4,
hive_t_dword_be = 5,
hive_t_link = 6,
hive_t_multiple_strings = 7,
hive_t_resource_list = 8,
hive_t_full_resource_description = 9,
hive_t_resource_requirements_list = 10,
hive_t_qword = 11
};
This is a value handle, an integer but opaque outside the library. Valid value handles cannot be 0. The library returns 0 in some situations to indicate an error.
Return the 0-terminated array of (key, value) pairs attached to this node.
The array should be freed by the caller when it is no longer needed.
On error this returns NULL and sets errno.
Return the value attached to this node which has the name key,
if it exists.
The key name is matched case insensitively.
Note that to get the default key, you should pass the empty
string "" here. The default key is often written "@", but
inside hives that has no meaning and won't give you the
default key.
If no such key exists, this returns 0 and does not set errno.
On error this returns 0 and sets errno.
Return the key (name) of a (key, value) pair. The name is reencoded as UTF-8 and returned as a C string.
The string should be freed by the caller when it is no longer needed.
Note that this function can return a zero-length string. In the
context of Windows Registries, this means that this value is the
default key for this node in the tree. This is usually written
as "@".
On error this returns NULL and sets errno.
Return the data type and length of the value in this (key, value)
pair. See also hivex_value_value which returns all this
information, and the value itself. Also, hivex_value_* functions
below which can be used to return the value in a more useful form when
you know the type in advance.
Returns 0 on success. On error this returns -1 and sets errno.
Return the value of this (key, value) pair. The value should
be interpreted according to its type (see enum hive_type).
The value is returned in an array of bytes of length len.
The value should be freed by the caller when it is no longer needed.
On error this returns NULL and sets errno.
If this value is a string, return the string reencoded as UTF-8
(as a C string). This only works for values which have type
hive_t_string, hive_t_expand_string or hive_t_link.
The string should be freed by the caller when it is no longer needed.
On error this returns NULL and sets errno.
If this value is a multiple-string, return the strings reencoded
as UTF-8 (as a NULL-terminated array of C strings). This only
works for values which have type hive_t_multiple_strings.
The string array and each string in it should be freed by the caller when they are no longer needed.
On error this returns NULL and sets errno.
If this value is a DWORD (Windows int32), return it. This only works
for values which have type hive_t_dword or hive_t_dword_be.
If this value is a QWORD (Windows int64), return it. This only
works for values which have type hive_t_qword.
The visitor pattern is useful if you want to visit all nodes in the tree or all nodes below a certain point in the tree.
First you set up your own struct hivex_visitor with your
callback functions.
Each of these callback functions should return 0 on success or -1 on error. If any callback returns -1, then the entire visit terminates immediately. If you don't need a callback function at all, set the function pointer to NULL.
struct hivex_visitor {
int (*node_start) (hive_h *, void *opaque, hive_node_h, const char *name);
int (*node_end) (hive_h *, void *opaque, hive_node_h, const char *name);
int (*value_string) (hive_h *, void *opaque, hive_node_h, hive_value_h,
hive_type t, size_t len, const char *key, const char *str);
int (*value_multiple_strings) (hive_h *, void *opaque, hive_node_h,
hive_value_h, hive_type t, size_t len, const char *key, char **argv);
int (*value_string_invalid_utf16) (hive_h *, void *opaque, hive_node_h,
hive_value_h, hive_type t, size_t len, const char *key,
const char *str);
int (*value_dword) (hive_h *, void *opaque, hive_node_h, hive_value_h,
hive_type t, size_t len, const char *key, int32_t);
int (*value_qword) (hive_h *, void *opaque, hive_node_h, hive_value_h,
hive_type t, size_t len, const char *key, int64_t);
int (*value_binary) (hive_h *, void *opaque, hive_node_h, hive_value_h,
hive_type t, size_t len, const char *key, const char *value);
int (*value_none) (hive_h *, void *opaque, hive_node_h, hive_value_h,
hive_type t, size_t len, const char *key, const char *value);
int (*value_other) (hive_h *, void *opaque, hive_node_h, hive_value_h,
hive_type t, size_t len, const char *key, const char *value);
/* If value_any callback is not NULL, then the other value_*
* callbacks are not used, and value_any is called on all values.
*/
int (*value_any) (hive_h *, void *opaque, hive_node_h, hive_value_h,
hive_type t, size_t len, const char *key, const char *value);
};
Visit all the nodes recursively in the hive h.
visitor should be a hivex_visitor structure with callback
fields filled in as required (unwanted callbacks can be set to
NULL). len must be the length of the 'visitor' struct (you
should pass sizeof (struct hivex_visitor) for this).
This returns 0 if the whole recursive visit was completed successfully. On error this returns -1. If one of the callback functions returned an error than we don't touch errno. If the error was generated internally then we set errno.
You can skip bad registry entries by setting flag to
HIVEX_VISIT_SKIP_BAD. If this flag is not set, then a bad registry
causes the function to return an error immediately.
This function is robust if the registry contains cycles or pointers which are invalid or outside the registry. It detects these cases and returns an error.
Same as hivex_visit but instead of starting out at the root, this
starts at node.
The hivex library supports making limited modifications to hive files. We have tried to implement this very conservatively in order to reduce the chance of corrupting your registry. However you should be careful and take back-ups, since Microsoft has never documented the hive format, and so it is possible there are nuances in the reverse-engineered format that we do not understand.
To be able to modify a hive, you must pass the HIVEX_OPEN_WRITE
flag to hivex_open, otherwise any write operation will return with
errno EROFS.
The write operations shown below do not modify the on-disk file
immediately. You must call hivex_commit in order to write the
changes to disk. If you call hivex_close without committing then
any writes are discarded.
Hive files internally consist of a "memory dump" of binary blocks (like the C heap), and some of these blocks can be unused. The hivex library never reuses these unused blocks. Instead, to ensure robustness in the face of the partially understood on-disk format, hivex only allocates new blocks after the end of the file, and makes minimal modifications to existing structures in the file to point to these new blocks. This makes hivex slightly less disk-efficient than it could be, but disk is cheap, and registry modifications tend to be very small.
When deleting nodes, it is possible that this library may leave unreachable live blocks in the hive. This is because certain parts of the hive disk format such as security (sk) records and big data (db) records and classname fields are not well understood (and not documented at all) and we play it safe by not attempting to modify them. Apart from wasting a little bit of disk space, it is not thought that unreachable blocks are a problem.
Commit (write) any changes which have been made.
filename is the new file to write. If filename == NULL then we
overwrite the original file (ie. the file name that was passed to
hivex_open). flags is not used, always pass 0.
Returns 0 on success. On error this returns -1 and sets errno.
Note this does not close the hive handle. You can perform further
operations on the hive after committing, including making more
modifications. If you no longer wish to use the hive, call
hivex_close after this.
Add a new child node named name to the existing node parent.
The new child initially has no subnodes and contains no keys or
values. The sk-record (security descriptor) is inherited from
the parent.
The parent must not have an existing child called name, so if you
want to overwrite an existing child, call hivex_node_delete_child
first.
Returns the node handle. On error this returns 0 and sets errno.
Delete the node node. All values at the node and all subnodes are
deleted (recursively). The node handle and the handles of all
subnodes become invalid. You cannot delete the root node.
Returns 0 on success. On error this returns -1 and sets errno.
The typedef hive_set_value is used in conjunction with the
hivex_node_set_values call described below.
struct hive_set_value {
char *key; /* key - a UTF-8 encoded ASCIIZ string */
hive_type t; /* type of value field */
size_t len; /* length of value field in bytes */
char *value; /* value field */
};
typedef struct hive_set_value hive_set_value;
To set the default value for a node, you have to pass key = "".
Note that the value field is just treated as a list of bytes, and
is stored directly in the hive. The caller has to ensure correct
encoding and endianness, for example converting dwords to little
endian.
The correct type and encoding for values depends on the node and key in the registry, the version of Windows, and sometimes even changes between versions of Windows for the same key. We don't document it here. Often it's not documented at all.
This call can be used to set all the (key, value) pairs stored in node.
node is the node to modify. values is an array of (key, value)
pairs. There should be nr_values elements in this array. flags
is not used, always pass 0.
Any existing values stored at the node are discarded, and their
hive_value_h handles become invalid. Thus you can remove all
values stored at node by passing nr_values = 0.
Returns 0 on success. On error this returns -1 and sets errno.
Note that this library does not offer a way to modify just a single key at a node. We don't implement a way to do this efficiently.
Changing the root node.
Creating a new hive file from scratch. This is impossible at present because not all fields in the header are understood.
Modifying or deleting single values at a node.
Modifying security key (sk) records or classnames. Previously we did not understand these records. However now they are well-understood and we could add support if it was required (but nothing much really uses them).
Note: To understand the relationship between hives and the common
Windows Registry keys (like HKEY_LOCAL_MACHINE) please see the
Wikipedia page on the Windows Registry.
The Windows Registry is split across various binary files, each file being known as a "hive". This library only handles a single hive file at a time.
Hives are n-ary trees with a single root. Each node in the tree has a name.
Each node in the tree (including non-leaf nodes) may have an arbitrary list of (key, value) pairs attached to it. It may be the case that one of these pairs has an empty key. This is referred to as the default key for the node.
The (key, value) pairs are the place where the useful data is stored in the registry. The key is always a string (possibly the empty string for the default key). The value is a typed object (eg. string, int32, binary, etc.).
Although this library does not care about or deal with Windows reg files, it's useful to look at the relationship between the registry itself and reg files because they are so common.
A reg file is a text representation of the registry, or part of the registry. The actual registry hives that Windows uses are binary files. There are a number of Windows and Linux tools that let you generate reg files, or merge reg files back into the registry hives. Notable amongst them is Microsoft's REGEDIT program (formerly known as REGEDT32).
A typical reg file will contain many sections looking like this:
[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Stack] "@"="Generic Stack" "TileInfo"="prop:System.FileCount" "TilePath"=str(2):"%systemroot%\\system32" "ThumbnailCutoff"=dword:00000000 "FriendlyTypeName"=hex(2):40,00,25,00,53,00,79,00,73,00,74,00,65,00,6d,00,52,00,6f,00,\ 6f,00,74,00,25,00,5c,00,53,00,79,00,73,00,74,00,65,00,6d,00,\ 33,00,32,00,5c,00,73,00,65,00,61,00,72,00,63,00,68,00,66,00,\ 6f,00,6c,00,64,00,65,00,72,00,2e,00,64,00,6c,00,6c,00,2c,00,\ 2d,00,39,00,30,00,32,00,38,00,00,00,d8
Taking this one piece at a time:
[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Stack]
This is the path to this node in the registry tree. The first part,
HKEY_LOCAL_MACHINE\SOFTWARE means that this comes from a hive
(file) called SOFTWARE. \Classes\Stack is the real path part,
starting at the root node of the SOFTWARE hive.
Below the node name is a list of zero or more key-value pairs. Any interior or leaf node in the registry may have key-value pairs attached.
"@"="Generic Stack"
This is the "default key". In reality (ie. inside the binary hive)
the key string is the empty string. In reg files this is written as
@ but this has no meaning either in the hives themselves or in this
library. The value is a string (type 1 - see enum hive_type
above).
"TileInfo"="prop:System.FileCount"
This is a regular (key, value) pair, with the value being a type 1 string. Note that inside the binary file the string is likely to be UTF-16 encoded. This library converts to and from UTF-8 strings transparently.
"TilePath"=str(2):"%systemroot%\\system32"
The value in this case has type 2 (expanded string) meaning that some %...% variables get expanded by Windows. (This library doesn't know or care about variable expansion).
"ThumbnailCutoff"=dword:00000000
The value in this case is a dword (type 4).
"FriendlyTypeName"=hex(2):40,00,....
This value is an expanded string (type 2) represented in the reg file as a series of hex bytes. In this case the string appears to be a UTF-16 string.
Many functions in this library set errno to indicate errors. These are the values of errno you may encounter (this list is not exhaustive):
Corrupt or unsupported Registry file format.
Missing root key.
Passed an invalid argument to the function.
Followed a Registry pointer which goes outside the registry or outside a registry block.
Registry contains cycles.
Field in the registry out of range.
Registry key already exists.
Tried to write to a registry which is not opened for writing.
Setting HIVEX_DEBUG=1 will enable very verbose messages. This is useful for debugging problems with the library itself.
hivexml(1), hivexget(1), virt-win-reg(1), guestfs(3), http://libguestfs.org/, virt-cat(1), virt-edit(1), http://en.wikipedia.org/wiki/Windows_Registry.
Richard W.M. Jones (rjones at redhat dot com)
Copyright (C) 2009-2010 Red Hat Inc.
Derived from code by Petter Nordahl-Hagen under a compatible license: Copyright (C) 1997-2007 Petter Nordahl-Hagen.
Derived from code by Markus Stephany under a compatible license: Copyright (C) 2000-2004 Markus Stephany.
This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; version 2.1 of the License.
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
See file LICENSE for the full license.