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.
  17
  18 Unlike many other tools in this area, it doesn't use the textual .REG
  19 format for output, because parsing that is as much trouble as parsing
  20 the original binary format.  Instead it makes the file available
  21 through a C API, or there is a separate program to export the hive as
  22 XML (see L<hivexml(1)>), or to get individual keys (see
  23 L<hivexget(1)>).
  24
  25 =head2 OPENING AND CLOSING A HIVE
  26
  27 =over 4
  28
  29 =item hive_h *hivex_open (const char *filename, int flags);
  30
  31 Opens the hive named C<filename> for reading.
  32
  33 Flags is an ORed list of the open flags (or C<0> if you don't
  34 want to pass any flags).  These flags are defined:
  35
  36 =over 4
  37
  38 =item HIVEX_OPEN_VERBOSE
  39
  40 Verbose messages.
  41
  42 =item HIVEX_OPEN_DEBUG
  43
  44 Very verbose messages, suitable for debugging problems in the library
  45 itself.
  46
  47 This is also selected if the C<HIVEX_DEBUG> environment variable
  48 is set to 1.
  49
  50 =item HIVEX_OPEN_WRITE
  51
  52 Open the hive for writing.  If omitted, the hive is read-only.
  53
  54 See L</WRITING TO HIVE FILES>.
  55
  56 =back
  57
  58 C<hivex_open> returns a hive handle.  On error this returns NULL and
  59 sets C<errno> to indicate the error.
  60
  61 =item int hivex_close (hive_h *h);
  62
  63 Close a hive handle and free all associated resources.
  64
  65 Note that any uncommitted writes are I<not> committed by this call,
  66 but instead are lost.  See L</WRITING TO HIVE FILES>.
  67
  68 Returns 0 on success.  On error this returns -1 and sets errno.
  69
  70 =back
  71
  72 =head2 NAVIGATING THE TREE OF HIVE SUBKEYS
  73
  74 =over 4
  75
  76 =item hive_node_h
  77
  78 This is a node handle, an integer but opaque outside the library.
  79 Valid node handles cannot be 0.  The library returns 0 in some
  80 situations to indicate an error.
  81
  82 =item hive_node_h hivex_root (hive_h *h);
  83
  84 Return root node of the hive.  All valid registries must contain
  85 a root node.
  86
  87 On error this returns 0 and sets errno.
  88
  89 =item char *hivex_node_name (hive_h *h, hive_node_h node);
  90
  91 Return the name of the node.  The name is reencoded as UTF-8
  92 and returned as a C string.
  93
  94 The string should be freed by the caller when it is no longer needed.
  95
  96 Note that the name of the root node is a dummy, such as
  97 C<$$$PROTO.HIV> (other names are possible: it seems to depend on the
  98 tool or program that created the hive in the first place).  You can
  99 only know the "real" name of the root node by knowing which registry
 100 file this hive originally comes from, which is knowledge that is
 101 outside the scope of this library.
 102
 103 On error this returns NULL and sets errno.
 104
 105 =item hive_node_h *hivex_node_children (hive_h *h, hive_node_h node);
 106
 107 Return a 0-terminated array of nodes which are the subkeys
 108 (children) of C<node>.
 109
 110 The array should be freed by the caller when it is no longer needed.
 111
 112 On error this returns NULL and sets errno.
 113
 114 =item hive_node_h hivex_node_get_child (hive_h *h, hive_node_h node, const char *name);
 115
 116 Return the child of node with the name C<name>, if it exists.
 117
 118 The name is matched case insensitively.
 119
 120 If the child node does not exist, this returns 0 without
 121 setting errno.
 122
 123 On error this returns 0 and sets errno.
 124
 125 =item hive_node_h hivex_node_parent (hive_h *h, hive_node_h node);
 126
 127 Return the parent of C<node>.
 128
 129 On error this returns 0 and sets errno.
 130
 131 The parent pointer of the root node in registry files that we
 132 have examined seems to be invalid, and so this function will
 133 return an error if called on the root node.
 134
 135 =back
 136
 137 =head2 GETTING VALUES AT A NODE
 138
 139 The enum below describes the possible types for the value(s)
 140 stored at each node.
 141
 142  enum hive_type {
 143    hive_t_none = 0,
 144    hive_t_string = 1,
 145    hive_t_expand_string = 2,
 146    hive_t_binary = 3,
 147    hive_t_dword = 4,
 148    hive_t_dword_be = 5,
 149    hive_t_link = 6,
 150    hive_t_multiple_strings = 7,
 151    hive_t_resource_list = 8,
 152    hive_t_full_resource_description = 9,
 153    hive_t_resource_requirements_list = 10,
 154    hive_t_qword = 11
 155  };
 156
 157 =over 4
 158
 159 =item hive_value_h
 160
 161 This is a value handle, an integer but opaque outside the library.
 162 Valid value handles cannot be 0.  The library returns 0 in some
 163 situations to indicate an error.
 164
 165 =item hive_value_h *hivex_node_values (hive_h *h, hive_node_h node);
 166
 167 Return the 0-terminated array of (key, value) pairs attached to
 168 this node.
 169
 170 The array should be freed by the caller when it is no longer needed.
 171
 172 On error this returns NULL and sets errno.
 173
 174 =item hive_value_h hivex_node_get_value (hive_h *h, hive_node_h node, const char *key);
 175
 176 Return the value attached to this node which has the name C<key>,
 177 if it exists.
 178
 179 The key name is matched case insensitively.
 180
 181 Note that to get the default key, you should pass the empty
 182 string C<""> here.  The default key is often written C<"@">, but
 183 inside hives that has no meaning and won't give you the
 184 default key.
 185
 186 If no such key exists, this returns 0 and does not set errno.
 187
 188 On error this returns 0 and sets errno.
 189
 190 =item char *hivex_value_key (hive_h *h, hive_value_h value);
 191
 192 Return the key (name) of a (key, value) pair.  The name
 193 is reencoded as UTF-8 and returned as a C string.
 194
 195 The string should be freed by the caller when it is no longer needed.
 196
 197 Note that this function can return a zero-length string.  In the
 198 context of Windows Registries, this means that this value is the
 199 default key for this node in the tree.  This is usually written
 200 as C<"@">.
 201
 202 On error this returns NULL and sets errno.
 203
 204 =item int hivex_value_type (hive_h *h, hive_value_h value, hive_type *t, size_t *len);
 205
 206 Return the data type and length of the value in this (key, value)
 207 pair.  See also C<hivex_value_value> which returns all this
 208 information, and the value itself.  Also, C<hivex_value_*> functions
 209 below which can be used to return the value in a more useful form when
 210 you know the type in advance.
 211
 212 Returns 0 on success.  On error this returns -1 and sets errno.
 213
 214 =item char *hivex_value_value (hive_h *h, hive_value_h value, hive_type *t, size_t *len);
 215
 216 Return the value of this (key, value) pair.  The value should
 217 be interpreted according to its type (see C<enum hive_type>).
 218
 219 The value is returned in an array of bytes of length C<len>.
 220
 221 The value should be freed by the caller when it is no longer needed.
 222
 223 On error this returns NULL and sets errno.
 224
 225 =item char *hivex_value_string (hive_h *h, hive_value_h value);
 226
 227 If this value is a string, return the string reencoded as UTF-8
 228 (as a C string).  This only works for values which have type
 229 C<hive_t_string>, C<hive_t_expand_string> or C<hive_t_link>.
 230
 231 The string should be freed by the caller when it is no longer needed.
 232
 233 On error this returns NULL and sets errno.
 234
 235 =item char **hivex_value_multiple_strings (hive_h *h, hive_value_h value);
 236
 237 If this value is a multiple-string, return the strings reencoded
 238 as UTF-8 (as a NULL-terminated array of C strings).  This only
 239 works for values which have type C<hive_t_multiple_strings>.
 240
 241 The string array and each string in it should be freed by the
 242 caller when they are no longer needed.
 243
 244 On error this returns NULL and sets errno.
 245
 246 =item int32_t hivex_value_dword (hive_h *h, hive_value_h value);
 247
 248 If this value is a DWORD (Windows int32), return it.  This only works
 249 for values which have type C<hive_t_dword> or C<hive_t_dword_be>.
 250
 251 =item int64_t hivex_value_qword (hive_h *h, hive_value_h value);
 252
 253 If this value is a QWORD (Windows int64), return it.  This only
 254 works for values which have type C<hive_t_qword>.
 255
 256 =back
 257
 258 =head2 VISITING ALL NODES
 259
 260 The visitor pattern is useful if you want to visit all nodes
 261 in the tree or all nodes below a certain point in the tree.
 262
 263 First you set up your own C<struct hivex_visitor> with your
 264 callback functions.
 265
 266 Each of these callback functions should return 0 on success or -1
 267 on error.  If any callback returns -1, then the entire visit
 268 terminates immediately.  If you don't need a callback function at
 269 all, set the function pointer to NULL.
 270
 271  struct hivex_visitor {
 272    int (*node_start) (hive_h *, void *opaque, hive_node_h, const char *name);
 273    int (*node_end) (hive_h *, void *opaque, hive_node_h, const char *name);
 274    int (*value_string) (hive_h *, void *opaque, hive_node_h, hive_value_h,
 275          hive_type t, size_t len, const char *key, const char *str);
 276    int (*value_multiple_strings) (hive_h *, void *opaque, hive_node_h,
 277          hive_value_h, hive_type t, size_t len, const char *key, char **argv);
 278    int (*value_string_invalid_utf16) (hive_h *, void *opaque, hive_node_h,
 279          hive_value_h, hive_type t, size_t len, const char *key,
 280          const char *str);
 281    int (*value_dword) (hive_h *, void *opaque, hive_node_h, hive_value_h,
 282          hive_type t, size_t len, const char *key, int32_t);
 283    int (*value_qword) (hive_h *, void *opaque, hive_node_h, hive_value_h,
 284          hive_type t, size_t len, const char *key, int64_t);
 285    int (*value_binary) (hive_h *, void *opaque, hive_node_h, hive_value_h,
 286          hive_type t, size_t len, const char *key, const char *value);
 287    int (*value_none) (hive_h *, void *opaque, hive_node_h, hive_value_h,
 288          hive_type t, size_t len, const char *key, const char *value);
 289    int (*value_other) (hive_h *, void *opaque, hive_node_h, hive_value_h,
 290          hive_type t, size_t len, const char *key, const char *value);
 291    /* If value_any callback is not NULL, then the other value_*
 292     * callbacks are not used, and value_any is called on all values.
 293     */
 294    int (*value_any) (hive_h *, void *opaque, hive_node_h, hive_value_h,
 295          hive_type t, size_t len, const char *key, const char *value);
 296  };
 297
 298 =over 4
 299
 300 =item int hivex_visit (hive_h *h, const struct hivex_visitor *visitor, size_t len, void *opaque, int flags);
 301
 302 Visit all the nodes recursively in the hive C<h>.
 303
 304 C<visitor> should be a C<hivex_visitor> structure with callback
 305 fields filled in as required (unwanted callbacks can be set to
 306 NULL).  C<len> must be the length of the 'visitor' struct (you
 307 should pass C<sizeof (struct hivex_visitor)> for this).
 308
 309 This returns 0 if the whole recursive visit was completed
 310 successfully.  On error this returns -1.  If one of the callback
 311 functions returned an error than we don't touch errno.  If the
 312 error was generated internally then we set errno.
 313
 314 You can skip bad registry entries by setting C<flag> to
 315 C<HIVEX_VISIT_SKIP_BAD>.  If this flag is not set, then a bad registry
 316 causes the function to return an error immediately.
 317
 318 This function is robust if the registry contains cycles or
 319 pointers which are invalid or outside the registry.  It detects
 320 these cases and returns an error.
 321
 322 =item int hivex_visit_node (hive_h *h, hive_node_h node, const struct hivex_visitor *visitor, size_t len, void *opaque);
 323
 324 Same as C<hivex_visit> but instead of starting out at the root, this
 325 starts at C<node>.
 326
 327 =back
 328
 329 =head2 WRITING TO HIVE FILES
 330
 331 The hivex library supports making limited modifications to hive files.
 332 We have tried to implement this very conservatively in order to reduce
 333 the chance of corrupting your registry.  However you should be careful
 334 and take back-ups, since Microsoft has never documented the hive
 335 format, and so it is possible there are nuances in the
 336 reverse-engineered format that we do not understand.
 337
 338 To be able to modify a hive, you must pass the C<HIVEX_OPEN_WRITE>
 339 flag to C<hivex_open>, otherwise any write operation will return with
 340 errno C<EROFS>.
 341
 342 The write operations shown below do not modify the on-disk file
 343 immediately.  You must call C<hivex_commit> in order to write the
 344 changes to disk.  If you call C<hivex_close> without committing then
 345 any writes are discarded.
 346
 347 Hive files internally consist of a "memory dump" of binary blocks
 348 (like the C heap), and some of these blocks can be unused.  The hivex
 349 library never reuses these unused blocks.  Instead, to ensure
 350 robustness in the face of the partially understood on-disk format,
 351 hivex only allocates new blocks after the end of the file, and makes
 352 minimal modifications to existing structures in the file to point to
 353 these new blocks.  This makes hivex slightly less disk-efficient than
 354 it could be, but disk is cheap, and registry modifications tend to be
 355 very small.
 356
 357 When deleting nodes, it is possible that this library may leave
 358 unreachable live blocks in the hive.  This is because certain parts of
 359 the hive disk format such as security (sk) records and big data (db)
 360 records and classname fields are not well understood (and not
 361 documented at all) and we play it safe by not attempting to modify
 362 them.  Apart from wasting a little bit of disk space, it is not
 363 thought that unreachable blocks are a problem.
 364
 365 =over 4
 366
 367 =item int hivex_commit (hive_h *h, const char *filename, int flags);
 368
 369 Commit (write) any changes which have been made.
 370
 371 C<filename> is the new file to write.  If C<filename == NULL> then we
 372 overwrite the original file (ie. the file name that was passed to
 373 C<hivex_open>).  C<flags> is not used, always pass 0.
 374
 375 Returns 0 on success.  On error this returns -1 and sets errno.
 376
 377 Note this does not close the hive handle.  You can perform further
 378 operations on the hive after committing, including making more
 379 modifications.  If you no longer wish to use the hive, call
 380 C<hivex_close> after this.
 381
 382 =item hive_set_value
 383
 384 The typedef C<hive_set_value> is used in conjunction with the
 385 C<hivex_node_set_values> call described below.
 386
 387  struct hive_set_value {
 388    char *key;     /* key - a UTF-8 encoded ASCIIZ string */
 389    hive_type t;   /* type of value field */
 390    size_t len;    /* length of value field in bytes */
 391    char *value;   /* value field */
 392  };
 393  typedef struct hive_set_value hive_set_value;
 394
 395 To set the default value for a node, you have to pass C<key = "">.
 396
 397 Note that the C<value> field is just treated as a list of bytes, and
 398 is stored directly in the hive.  The caller has to ensure correct
 399 encoding and endianness, for example converting dwords to little
 400 endian.
 401
 402 The correct type and encoding for values depends on the node and key
 403 in the registry, the version of Windows, and sometimes even changes
 404 between versions of Windows for the same key.  We don't document it
 405 here.  Often it's not documented at all.
 406
 407 =item int hivex_node_set_values (hive_h *h, hive_node_h node, size_t nr_values, const hive_set_value *values, int flags);
 408
 409 This call can be used to set all the (key, value) pairs stored in C<node>.
 410
 411 C<node> is the node to modify.  C<values> is an array of (key, value)
 412 pairs.  There should be C<nr_values> elements in this array.  C<flags>
 413 is not used, always pass 0.
 414
 415 Any existing values stored at the node are discarded, and their
 416 C<hive_value_h> handles become invalid.  Thus you can remove all
 417 values stored at C<node> by passing C<nr_values = 0>.
 418
 419 Returns 0 on success.  On error this returns -1 and sets errno.
 420
 421 Note that this library does not offer a way to modify just a single
 422 key at a node.  We don't implement a way to do this efficiently.
 423
 424 =back
 425
 426 =head3 WRITE OPERATIONS WHICH ARE NOT SUPPORTED
 427
 428 =over 4
 429
 430 =item *
 431
 432 Changing the root node.
 433
 434 =item *
 435
 436 Creating a new hive file from scratch.  This is impossible at present
 437 because not all fields in the header are understood.
 438
 439 =item *
 440
 441 Modifying or deleting single values at a node.
 442
 443 =item *
 444
 445 Modifying security key (sk) records or classnames.  These are not
 446 well understood.
 447
 448 =back
 449
 450 =head1 THE STRUCTURE OF THE WINDOWS REGISTRY
 451
 452 Note: To understand the relationship between hives and the common
 453 Windows Registry keys (like C<HKEY_LOCAL_MACHINE>) please see the
 454 Wikipedia page on the Windows Registry.
 455
 456 The Windows Registry is split across various binary files, each
 457 file being known as a "hive".  This library only handles a single
 458 hive file at a time.
 459
 460 Hives are n-ary trees with a single root.  Each node in the tree
 461 has a name.
 462
 463 Each node in the tree (including non-leaf nodes) may have an
 464 arbitrary list of (key, value) pairs attached to it.  It may
 465 be the case that one of these pairs has an empty key.  This
 466 is referred to as the default key for the node.
 467
 468 The (key, value) pairs are the place where the useful data is
 469 stored in the registry.  The key is always a string (possibly the
 470 empty string for the default key).  The value is a typed object
 471 (eg. string, int32, binary, etc.).
 472
 473 =head2 RELATIONSHIP TO .REG FILES
 474
 475 Although this library does not care about or deal with Windows reg
 476 files, it's useful to look at the relationship between the registry
 477 itself and reg files because they are so common.
 478
 479 A reg file is a text representation of the registry, or part of the
 480 registry.  The actual registry hives that Windows uses are binary
 481 files.  There are a number of Windows and Linux tools that let you
 482 generate reg files, or merge reg files back into the registry hives.
 483 Notable amongst them is Microsoft's REGEDIT program (formerly known as
 484 REGEDT32).
 485
 486 A typical reg file will contain many sections looking like this:
 487
 488  [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Stack]
 489  "@"="Generic Stack"
 490  "TileInfo"="prop:System.FileCount"
 491  "TilePath"=str(2):"%systemroot%\\system32"
 492  "ThumbnailCutoff"=dword:00000000
 493  "FriendlyTypeName"=hex(2):40,00,25,00,53,00,79,00,73,00,74,00,65,00,6d,00,52,00,6f,00,\
 494   6f,00,74,00,25,00,5c,00,53,00,79,00,73,00,74,00,65,00,6d,00,\
 495   33,00,32,00,5c,00,73,00,65,00,61,00,72,00,63,00,68,00,66,00,\
 496   6f,00,6c,00,64,00,65,00,72,00,2e,00,64,00,6c,00,6c,00,2c,00,\
 497   2d,00,39,00,30,00,32,00,38,00,00,00,d8
 498
 499 Taking this one piece at a time:
 500
 501  [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Stack]
 502
 503 This is the path to this node in the registry tree.  The first part,
 504 C<HKEY_LOCAL_MACHINE\SOFTWARE> means that this comes from a hive
 505 (file) called C<SOFTWARE>.  C<\Classes\Stack> is the real path part,
 506 starting at the root node of the C<SOFTWARE> hive.
 507
 508 Below the node name is a list of zero or more key-value pairs.  Any
 509 interior or leaf node in the registry may have key-value pairs
 510 attached.
 511
 512  "@"="Generic Stack"
 513
 514 This is the "default key".  In reality (ie. inside the binary hive)
 515 the key string is the empty string.  In reg files this is written as
 516 C<@> but this has no meaning either in the hives themselves or in this
 517 library.  The value is a string (type 1 - see C<enum hive_type>
 518 above).
 519
 520  "TileInfo"="prop:System.FileCount"
 521
 522 This is a regular (key, value) pair, with the value being a type 1
 523 string.  Note that inside the binary file the string is likely to be
 524 UTF-16 encoded.  This library converts to and from UTF-8 strings
 525 transparently.
 526
 527  "TilePath"=str(2):"%systemroot%\\system32"
 528
 529 The value in this case has type 2 (expanded string) meaning that some
 530 %...% variables get expanded by Windows.  (This library doesn't know
 531 or care about variable expansion).
 532
 533  "ThumbnailCutoff"=dword:00000000
 534
 535 The value in this case is a dword (type 4).
 536
 537  "FriendlyTypeName"=hex(2):40,00,....
 538
 539 This value is an expanded string (type 2) represented in the reg file
 540 as a series of hex bytes.  In this case the string appears to be a
 541 UTF-16 string.
 542
 543 =head1 NOTE ON THE USE OF ERRNO
 544
 545 Many functions in this library set errno to indicate errors.  These
 546 are the values of errno you may encounter (this list is not
 547 exhaustive):
 548
 549 =over 4
 550
 551 =item ENOTSUP
 552
 553 Corrupt or unsupported Registry file format.
 554
 555 =item ENOKEY
 556
 557 Missing root key.
 558
 559 =item EINVAL
 560
 561 Passed an invalid argument to the function.
 562
 563 =item EFAULT
 564
 565 Followed a Registry pointer which goes outside
 566 the registry or outside a registry block.
 567
 568 =item ELOOP
 569
 570 Registry contains cycles.
 571
 572 =item ERANGE
 573
 574 Field in the registry out of range.
 575
 576 =item EROFS
 577
 578 Tried to write to a registry which is not opened for writing.
 579
 580 =back
 581
 582 =head1 ENVIRONMENT VARIABLES
 583
 584 =over 4
 585
 586 =item HIVEX_DEBUG
 587
 588 Setting HIVEX_DEBUG=1 will enable very verbose messages.  This is
 589 useful for debugging problems with the library itself.
 590
 591 =back
 592
 593 =head1 SEE ALSO
 594
 595 L<hivexml(1)>,
 596 L<hivexget(1)>,
 597 L<virt-win-reg(1)>,
 598 L<guestfs(3)>,
 599 L<http://libguestfs.org/>,
 600 L<virt-cat(1)>,
 601 L<virt-edit(1)>,
 602 L<http://en.wikipedia.org/wiki/Windows_Registry>.
 603
 604 =head1 AUTHORS
 605
 606 Richard W.M. Jones (C<rjones at redhat dot com>)
 607
 608 =head1 COPYRIGHT
 609
 610 Copyright (C) 2009-2010 Red Hat Inc.
 611
 612 Derived from code by Petter Nordahl-Hagen under a compatible license:
 613 Copyright (C) 1997-2007 Petter Nordahl-Hagen.
 614
 615 Derived from code by Markus Stephany under a compatible license:
 616 Copyright (C) 2000-2004 Markus Stephany.
 617
 618 This library is free software; you can redistribute it and/or
 619 modify it under the terms of the GNU Lesser General Public
 620 License as published by the Free Software Foundation;
 621 version 2.1 of the License.
 622
 623 This library is distributed in the hope that it will be useful,
 624 but WITHOUT ANY WARRANTY; without even the implied warranty of
 625 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 626 Lesser General Public License for more details.
 627
 628 See file LICENSE for the full license.