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, and to have limited functionality (writing or
  17 modifying these files is not in the scope of this library).
  18
  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
  24 L<hivexget(1)>).
  25
  26 =head2 OPENING AND CLOSING A HIVE
  27
  28 =over 4
  29
  30 =item hive_h *hivex_open (const char *filename, int flags);
  31
  32 Opens the hive named C<filename> for reading.
  33
  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
  36 flags defined are:
  37
  38 =over 4
  39
  40 =item HIVEX_OPEN_VERBOSE
  41
  42 Verbose messages.
  43
  44 =item HIVEX_OPEN_DEBUG
  45
  46 Very verbose messages, suitable for debugging problems in the library
  47 itself.
  48
  49 This is also selected if the C<HIVEX_DEBUG> environment variable
  50 is set to 1.
  51
  52 =back
  53
  54 C<hivex_open> returns a hive handle.  On error this returns NULL and
  55 sets C<errno> to indicate the error.
  56
  57 =item int hivex_close (hive_h *h);
  58
  59 Close a hive handle and free all associated resources.
  60
  61 Returns 0 on success.  On error this returns -1 and sets errno.
  62
  63 =back
  64
  65 =head2 NAVIGATING THE TREE OF HIVE SUBKEYS
  66
  67 =over 4
  68
  69 =item hive_node_h hivex_root (hive_h *h);
  70
  71 Return root node of the hive.  All valid registries must contain
  72 a root node.
  73
  74 On error this returns 0 and sets errno.
  75
  76 =item char *hivex_node_name (hive_h *h, hive_node_h node);
  77
  78 Return the name of the node.  The name is reencoded as UTF-8
  79 and returned as a C string.
  80
  81 The string should be freed by the caller when it is no longer needed.
  82
  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.
  89
  90 On error this returns NULL and sets errno.
  91
  92 =item hive_node_h *hivex_node_children (hive_h *h, hive_node_h node);
  93
  94 Return a 0-terminated array of nodes which are the subkeys
  95 (children) of C<node>.
  96
  97 The array should be freed by the caller when it is no longer needed.
  98
  99 On error this returns NULL and sets errno.
 100
 101 =item hive_node_h hivex_node_get_child (hive_h *h, hive_node_h node, const char *name);
 102
 103 Return the child of node with the name C<name>, if it exists.
 104
 105 The name is matched case insensitively.
 106
 107 If the child node does not exist, this returns 0 without
 108 setting errno.
 109
 110 On error this returns 0 and sets errno.
 111
 112 =item hive_node_h hivex_node_parent (hive_h *h, hive_node_h node);
 113
 114 Return the parent of C<node>.
 115
 116 On error this returns 0 and sets errno.
 117
 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.
 121
 122 =back
 123
 124 =head2 GETTING VALUES AT A NODE
 125
 126 The enum below describes the possible types for the value(s)
 127 stored at each node.
 128
 129  enum hive_type {
 130    hive_t_none = 0,
 131    hive_t_string = 1,
 132    hive_t_expand_string = 2,
 133    hive_t_binary = 3,
 134    hive_t_dword = 4,
 135    hive_t_dword_be = 5,
 136    hive_t_link = 6,
 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,
 141    hive_t_qword = 11
 142  };
 143
 144 =over 4
 145
 146 =item hive_value_h *hivex_node_values (hive_h *h, hive_node_h node);
 147
 148 Return the 0-terminated array of (key, value) pairs attached to
 149 this node.
 150
 151 The array should be freed by the caller when it is no longer needed.
 152
 153 On error this returns NULL and sets errno.
 154
 155 =item hive_value_h hivex_node_get_value (hive_h *h, hive_node_h node, const char *key);
 156
 157 Return the value attached to this node which has the name C<key>,
 158 if it exists.
 159
 160 The key name is matched case insensitively.
 161
 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
 165 default key.
 166
 167 If no such key exists, this returns 0 and does not set errno.
 168
 169 On error this returns 0 and sets errno.
 170
 171 =item char *hivex_value_key (hive_h *h, hive_value_h value);
 172
 173 Return the key (name) of a (key, value) pair.  The name
 174 is reencoded as UTF-8 and returned as a C string.
 175
 176 The string should be freed by the caller when it is no longer needed.
 177
 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
 181 as C<"@">.
 182
 183 On error this returns NULL and sets errno.
 184
 185 =item int hivex_value_type (hive_h *h, hive_value_h value, hive_type *t, size_t *len);
 186
 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.
 192
 193 Returns 0 on success.  On error this returns -1 and sets errno.
 194
 195 =item char *hivex_value_value (hive_h *h, hive_value_h value, hive_type *t, size_t *len);
 196
 197 Return the value of this (key, value) pair.  The value should
 198 be interpreted according to its type (see C<hive_type>).
 199
 200 The value is returned in an array of bytes of length C<len>.
 201
 202 The value should be freed by the caller when it is no longer needed.
 203
 204 On error this returns NULL and sets errno.
 205
 206 =item char *hivex_value_string (hive_h *h, hive_value_h value);
 207
 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>.
 211
 212 The string should be freed by the caller when it is no longer needed.
 213
 214 On error this returns NULL and sets errno.
 215
 216 =item char **hivex_value_multiple_strings (hive_h *h, hive_value_h value);
 217
 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>.
 221
 222 The string array and each string in it should be freed by the
 223 caller when they are no longer needed.
 224
 225 On error this returns NULL and sets errno.
 226
 227 =item int32_t hivex_value_dword (hive_h *h, hive_value_h value);
 228
 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>.
 231
 232 =item int64_t hivex_value_qword (hive_h *h, hive_value_h value);
 233
 234 If this value is a QWORD (Windows int64), return it.  This only
 235 works for values which have type C<hive_t_qword>.
 236
 237 =back
 238
 239 =head2 VISITING ALL NODES
 240
 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.
 243
 244 First you set up your own C<struct hivex_visitor> with your
 245 callback functions.
 246
 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.
 251
 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,
 261          const char *str);
 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);
 272  };
 273
 274 =over 4
 275
 276 =item int hivex_visit (hive_h *h, const struct hivex_visitor *visitor, size_t len, void *opaque, int flags);
 277
 278 Visit all the nodes recursively in the hive C<h>.
 279
 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).
 284
 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.
 289
 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.
 293
 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.
 297
 298 =item int hivex_visit_node (hive_h *h, hive_node_h node, const struct hivex_visitor *visitor, size_t len, void *opaque);
 299
 300 Same as C<hivex_visit> but instead of starting out at the root, this
 301 starts at C<node>.
 302
 303 =back
 304
 305 =head1 THE STRUCTURE OF THE WINDOWS REGISTRY
 306
 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.
 310
 311 The Windows Registry is split across various binary files, each
 312 file being known as a "hive".  This library only handles a single
 313 hive file at a time.
 314
 315 Hives are n-ary trees with a single root.  Each node in the tree
 316 has a name.
 317
 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.
 322
 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.).
 327
 328 =head1 NOTE ON THE USE OF ERRNO
 329
 330 Many functions in this library set errno to indicate errors.
 331 These are the values of errno you may encounter:
 332
 333 =over 4
 334
 335 =item ENOTSUP
 336
 337 Corrupt or unsupported Registry file format.
 338
 339 =item ENOKEY
 340
 341 Missing root key.
 342
 343 =item EINVAL
 344
 345 Passed an invalid argument to the function.
 346
 347 =item EFAULT
 348
 349 Followed a Registry pointer which goes outside
 350 the registry or outside a registry block.
 351
 352 =item ELOOP
 353
 354 Registry contains cycles.
 355
 356 =item ERANGE
 357
 358 Field in the registry out of range.
 359
 360 =back
 361
 362 =head1 SEE ALSO
 363
 364 L<hivexml(1)>,
 365 L<hivexget(1)>,
 366 L<virt-win-reg(1)>,
 367 L<guestfs(3)>,
 368 L<http://libguestfs.org/>,
 369 L<virt-cat(1)>,
 370 L<virt-edit(1)>.
 371
 372 =head1 AUTHORS
 373
 374 Richard W.M. Jones (C<rjones at redhat dot com>)
 375
 376 =head1 COPYRIGHT
 377
 378 Copyright (C) 2009 Red Hat Inc.
 379
 380 Derived from code by Petter Nordahl-Hagen under a compatible license:
 381 Copyright (c) 1997-2007 Petter Nordahl-Hagen.
 382
 383 Derived from code by Markus Stephany under a compatible license:
 384 Copyright (c)2000-2004, Markus Stephany.
 385
 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.
 390
 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.
 395
 396 See file LICENSE for the full license.