X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=hivex%2Fhivex.pod;fp=hivex%2Fhivex.pod;h=1078bf110d5b7a5e341d3373d4de70c38b1bb0f1;hb=792c5283009ed6753239a14df9a6e9c71bea35fd;hp=0000000000000000000000000000000000000000;hpb=d609130cb65fe7795b168a796426e39d64ceda97;p=libguestfs.git diff --git a/hivex/hivex.pod b/hivex/hivex.pod new file mode 100644 index 0000000..1078bf1 --- /dev/null +++ b/hivex/hivex.pod @@ -0,0 +1,396 @@ +=encoding utf8 + +=head1 NAME + +hivex - Windows Registry "hive" extraction library + +=head1 SYNOPSIS + + hive_h *hivex_open (const char *filename, int flags); + int hivex_close (hive_h *h); + +=head1 DESCRIPTION + +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, and to have limited functionality (writing or +modifying these files is not in the scope of this library). + +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 L), or to get individual keys (see +L). + +=head2 OPENING AND CLOSING A HIVE + +=over 4 + +=item hive_h *hivex_open (const char *filename, int flags); + +Opens the hive named C for reading. + +Flags is an ORed list of the open flags (or C<0> if you don't +want to pass any flags). Currently the only +flags defined are: + +=over 4 + +=item HIVEX_OPEN_VERBOSE + +Verbose messages. + +=item HIVEX_OPEN_DEBUG + +Very verbose messages, suitable for debugging problems in the library +itself. + +This is also selected if the C environment variable +is set to 1. + +=back + +C returns a hive handle. On error this returns NULL and +sets C to indicate the error. + +=item int hivex_close (hive_h *h); + +Close a hive handle and free all associated resources. + +Returns 0 on success. On error this returns -1 and sets errno. + +=back + +=head2 NAVIGATING THE TREE OF HIVE SUBKEYS + +=over 4 + +=item hive_node_h hivex_root (hive_h *h); + +Return root node of the hive. All valid registries must contain +a root node. + +On error this returns 0 and sets errno. + +=item char *hivex_node_name (hive_h *h, hive_node_h node); + +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 +C<$$$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. + +=item hive_node_h *hivex_node_children (hive_h *h, hive_node_h node); + +Return a 0-terminated array of nodes which are the subkeys +(children) of C. + +The array should be freed by the caller when it is no longer needed. + +On error this returns NULL and sets errno. + +=item hive_node_h hivex_node_get_child (hive_h *h, hive_node_h node, const char *name); + +Return the child of node with the name C, 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. + +=item hive_node_h hivex_node_parent (hive_h *h, hive_node_h node); + +Return the parent of C. + +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. + +=back + +=head2 GETTING VALUES AT A 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 + }; + +=over 4 + +=item hive_value_h *hivex_node_values (hive_h *h, hive_node_h node); + +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. + +=item hive_value_h hivex_node_get_value (hive_h *h, hive_node_h node, const char *key); + +Return the value attached to this node which has the name C, +if it exists. + +The key name is matched case insensitively. + +Note that to get the default key, you should pass the empty +string C<""> here. The default key is often written C<"@">, 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. + +=item char *hivex_value_key (hive_h *h, hive_value_h value); + +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 C<"@">. + +On error this returns NULL and sets errno. + +=item int hivex_value_type (hive_h *h, hive_value_h value, hive_type *t, size_t *len); + +Return the data type and length of the value in this (key, value) +pair. See also C which returns all this +information, and the value itself. Also, C 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. + +=item char *hivex_value_value (hive_h *h, hive_value_h value, hive_type *t, size_t *len); + +Return the value of this (key, value) pair. The value should +be interpreted according to its type (see C). + +The value is returned in an array of bytes of length C. + +The value should be freed by the caller when it is no longer needed. + +On error this returns NULL and sets errno. + +=item char *hivex_value_string (hive_h *h, hive_value_h value); + +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 +C, C or C. + +The string should be freed by the caller when it is no longer needed. + +On error this returns NULL and sets errno. + +=item char **hivex_value_multiple_strings (hive_h *h, hive_value_h value); + +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 C. + +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. + +=item int32_t hivex_value_dword (hive_h *h, hive_value_h value); + +If this value is a DWORD (Windows int32), return it. This only works +for values which have type C or C. + +=item int64_t hivex_value_qword (hive_h *h, hive_value_h value); + +If this value is a QWORD (Windows int64), return it. This only +works for values which have type C. + +=back + +=head2 VISITING ALL NODES + +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 C 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); + }; + +=over 4 + +=item int hivex_visit (hive_h *h, const struct hivex_visitor *visitor, size_t len, void *opaque, int flags); + +Visit all the nodes recursively in the hive C. + +C should be a C structure with callback +fields filled in as required (unwanted callbacks can be set to +NULL). C must be the length of the 'visitor' struct (you +should pass C 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 C to +C. 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. + +=item int hivex_visit_node (hive_h *h, hive_node_h node, const struct hivex_visitor *visitor, size_t len, void *opaque); + +Same as C but instead of starting out at the root, this +starts at C. + +=back + +=head1 THE STRUCTURE OF THE WINDOWS REGISTRY + +Note: To understand the relationship between hives and the common +Windows Registry keys (like C) 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.). + +=head1 NOTE ON THE USE OF ERRNO + +Many functions in this library set errno to indicate errors. +These are the values of errno you may encounter: + +=over 4 + +=item ENOTSUP + +Corrupt or unsupported Registry file format. + +=item ENOKEY + +Missing root key. + +=item EINVAL + +Passed an invalid argument to the function. + +=item EFAULT + +Followed a Registry pointer which goes outside +the registry or outside a registry block. + +=item ELOOP + +Registry contains cycles. + +=item ERANGE + +Field in the registry out of range. + +=back + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L. + +=head1 AUTHORS + +Richard W.M. Jones (C) + +=head1 COPYRIGHT + +Copyright (C) 2009 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.