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
  70
  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.
  74
  75 =item hive_node_h hivex_root (hive_h *h);
  76
  77 Return root node of the hive.  All valid registries must contain
  78 a root node.
  79
  80 On error this returns 0 and sets errno.
  81
  82 =item char *hivex_node_name (hive_h *h, hive_node_h node);
  83
  84 Return the name of the node.  The name is reencoded as UTF-8
  85 and returned as a C string.
  86
  87 The string should be freed by the caller when it is no longer needed.
  88
  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.
  95
  96 On error this returns NULL and sets errno.
  97
  98 =item hive_node_h *hivex_node_children (hive_h *h, hive_node_h node);
  99
 100 Return a 0-terminated array of nodes which are the subkeys
 101 (children) of C<node>.
 102
 103 The array should be freed by the caller when it is no longer needed.
 104
 105 On error this returns NULL and sets errno.
 106
 107 =item hive_node_h hivex_node_get_child (hive_h *h, hive_node_h node, const char *name);
 108
 109 Return the child of node with the name C<name>, if it exists.
 110
 111 The name is matched case insensitively.
 112
 113 If the child node does not exist, this returns 0 without
 114 setting errno.
 115
 116 On error this returns 0 and sets errno.
 117
 118 =item hive_node_h hivex_node_parent (hive_h *h, hive_node_h node);
 119
 120 Return the parent of C<node>.
 121
 122 On error this returns 0 and sets errno.
 123
 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.
 127
 128 =back
 129
 130 =head2 GETTING VALUES AT A NODE
 131
 132 The enum below describes the possible types for the value(s)
 133 stored at each node.
 134
 135  enum hive_type {
 136    hive_t_none = 0,
 137    hive_t_string = 1,
 138    hive_t_expand_string = 2,
 139    hive_t_binary = 3,
 140    hive_t_dword = 4,
 141    hive_t_dword_be = 5,
 142    hive_t_link = 6,
 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,
 147    hive_t_qword = 11
 148  };
 149
 150 =over 4
 151
 152 =item hive_value_h
 153
 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.
 157
 158 =item hive_value_h *hivex_node_values (hive_h *h, hive_node_h node);
 159
 160 Return the 0-terminated array of (key, value) pairs attached to
 161 this node.
 162
 163 The array should be freed by the caller when it is no longer needed.
 164
 165 On error this returns NULL and sets errno.
 166
 167 =item hive_value_h hivex_node_get_value (hive_h *h, hive_node_h node, const char *key);
 168
 169 Return the value attached to this node which has the name C<key>,
 170 if it exists.
 171
 172 The key name is matched case insensitively.
 173
 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
 177 default key.
 178
 179 If no such key exists, this returns 0 and does not set errno.
 180
 181 On error this returns 0 and sets errno.
 182
 183 =item char *hivex_value_key (hive_h *h, hive_value_h value);
 184
 185 Return the key (name) of a (key, value) pair.  The name
 186 is reencoded as UTF-8 and returned as a C string.
 187
 188 The string should be freed by the caller when it is no longer needed.
 189
 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
 193 as C<"@">.
 194
 195 On error this returns NULL and sets errno.
 196
 197 =item int hivex_value_type (hive_h *h, hive_value_h value, hive_type *t, size_t *len);
 198
 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.
 204
 205 Returns 0 on success.  On error this returns -1 and sets errno.
 206
 207 =item char *hivex_value_value (hive_h *h, hive_value_h value, hive_type *t, size_t *len);
 208
 209 Return the value of this (key, value) pair.  The value should
 210 be interpreted according to its type (see C<enum hive_type>).
 211
 212 The value is returned in an array of bytes of length C<len>.
 213
 214 The value should be freed by the caller when it is no longer needed.
 215
 216 On error this returns NULL and sets errno.
 217
 218 =item char *hivex_value_string (hive_h *h, hive_value_h value);
 219
 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>.
 223
 224 The string should be freed by the caller when it is no longer needed.
 225
 226 On error this returns NULL and sets errno.
 227
 228 =item char **hivex_value_multiple_strings (hive_h *h, hive_value_h value);
 229
 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>.
 233
 234 The string array and each string in it should be freed by the
 235 caller when they are no longer needed.
 236
 237 On error this returns NULL and sets errno.
 238
 239 =item int32_t hivex_value_dword (hive_h *h, hive_value_h value);
 240
 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>.
 243
 244 =item int64_t hivex_value_qword (hive_h *h, hive_value_h value);
 245
 246 If this value is a QWORD (Windows int64), return it.  This only
 247 works for values which have type C<hive_t_qword>.
 248
 249 =back
 250
 251 =head2 VISITING ALL NODES
 252
 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.
 255
 256 First you set up your own C<struct hivex_visitor> with your
 257 callback functions.
 258
 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.
 263
 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,
 273          const char *str);
 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.
 286     */
 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);
 289  };
 290
 291 =over 4
 292
 293 =item int hivex_visit (hive_h *h, const struct hivex_visitor *visitor, size_t len, void *opaque, int flags);
 294
 295 Visit all the nodes recursively in the hive C<h>.
 296
 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).
 301
 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.
 306
 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.
 310
 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.
 314
 315 =item int hivex_visit_node (hive_h *h, hive_node_h node, const struct hivex_visitor *visitor, size_t len, void *opaque);
 316
 317 Same as C<hivex_visit> but instead of starting out at the root, this
 318 starts at C<node>.
 319
 320 =back
 321
 322 =head1 THE STRUCTURE OF THE WINDOWS REGISTRY
 323
 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.
 327
 328 The Windows Registry is split across various binary files, each
 329 file being known as a "hive".  This library only handles a single
 330 hive file at a time.
 331
 332 Hives are n-ary trees with a single root.  Each node in the tree
 333 has a name.
 334
 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.
 339
 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.).
 344
 345 =head2 RELATIONSHIP TO .REG FILES
 346
 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.
 350
 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
 356 REGEDT32).
 357
 358 A typical reg file will contain many sections looking like this:
 359
 360  [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Stack]
 361  "@"="Generic 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
 370
 371 Taking this one piece at a time:
 372
 373  [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Stack]
 374
 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.
 379
 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
 382 attached.
 383
 384  "@"="Generic Stack"
 385
 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>
 390 above).
 391
 392  "TileInfo"="prop:System.FileCount"
 393
 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
 397 transparently.
 398
 399  "TilePath"=str(2):"%systemroot%\\system32"
 400
 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).
 404
 405  "ThumbnailCutoff"=dword:00000000
 406
 407 The value in this case is a dword (type 4).
 408
 409  "FriendlyTypeName"=hex(2):40,00,....
 410
 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
 413 UTF-16 string.
 414
 415 =head1 NOTE ON THE USE OF ERRNO
 416
 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
 419 exhaustive):
 420
 421 =over 4
 422
 423 =item ENOTSUP
 424
 425 Corrupt or unsupported Registry file format.
 426
 427 =item ENOKEY
 428
 429 Missing root key.
 430
 431 =item EINVAL
 432
 433 Passed an invalid argument to the function.
 434
 435 =item EFAULT
 436
 437 Followed a Registry pointer which goes outside
 438 the registry or outside a registry block.
 439
 440 =item ELOOP
 441
 442 Registry contains cycles.
 443
 444 =item ERANGE
 445
 446 Field in the registry out of range.
 447
 448 =back
 449
 450 =head1 ENVIRONMENT VARIABLES
 451
 452 =over 4
 453
 454 =item HIVEX_DEBUG
 455
 456 Setting HIVEX_DEBUG=1 will enable very verbose messages.  This is
 457 useful for debugging problems with the library itself.
 458
 459 =back
 460
 461 =head1 SEE ALSO
 462
 463 L<hivexml(1)>,
 464 L<hivexget(1)>,
 465 L<virt-win-reg(1)>,
 466 L<guestfs(3)>,
 467 L<http://libguestfs.org/>,
 468 L<virt-cat(1)>,
 469 L<virt-edit(1)>,
 470 L<http://en.wikipedia.org/wiki/Windows_Registry>.
 471
 472 =head1 AUTHORS
 473
 474 Richard W.M. Jones (C<rjones at redhat dot com>)
 475
 476 =head1 COPYRIGHT
 477
 478 Copyright (C) 2009-2010 Red Hat Inc.
 479
 480 Derived from code by Petter Nordahl-Hagen under a compatible license:
 481 Copyright (C) 1997-2007 Petter Nordahl-Hagen.
 482
 483 Derived from code by Markus Stephany under a compatible license:
 484 Copyright (C) 2000-2004 Markus Stephany.
 485
 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.
 490
 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.
 495
 496 See file LICENSE for the full license.