https://github.com/colinfinck/nt-hive
Rust crate for accessing keys, values, and data stored in Windows hive (registry) files.
https://github.com/colinfinck/nt-hive
no-std registry rust windows
Last synced: 10 months ago
JSON representation
Rust crate for accessing keys, values, and data stored in Windows hive (registry) files.
- Host: GitHub
- URL: https://github.com/colinfinck/nt-hive
- Owner: ColinFinck
- License: gpl-2.0
- Created: 2021-02-20T18:37:27.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2025-01-21T20:58:59.000Z (over 1 year ago)
- Last Synced: 2025-06-02T00:26:00.332Z (about 1 year ago)
- Topics: no-std, registry, rust, windows
- Language: Rust
- Homepage:
- Size: 218 KB
- Stars: 47
- Watchers: 5
- Forks: 5
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# nt-hive
[](https://crates.io/crates/nt-hive)
[](https://docs.rs/nt-hive)
[](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html)
*by Colin Finck <>*
The *nt-hive* Rust crate provides a comfortable and safe interface for accessing keys, values, and data stored in *hive* files.
Hive files can be found in `C:\Windows\system32\config` and store what is commonly called the *Windows registry*.
This crate supports the hive format that is used from Windows NT 4.0 up to the current Windows 10.
nt-hive has been developed as part of a Rust bootloader project.
Its current feature set is therefore aligned to the needs of a ReactOS/Windows bootloader.
## Features
* Support for reading keys, values, and data from any byte slice containing hive data (i.e. anything that implements [`zerocopy::SplitByteSlice`](https://docs.rs/zerocopy/0.3.0/zerocopy/trait.ByteSlice.html)).
* Basic in-memory modifications of hive data (as [required for a bootloader](https://github.com/reactos/reactos/pull/1883)).
* Iterators for keys and values to enable writing idiomatic Rust code.
* Functions to find a specific subkey, subkey path, or value as efficient as possible (taking advantage of binary search for keys).
* Error propagation through a custom `NtHiveError` type that implements `Display`.
As a bootloader may hit corrupted hive files at some point, nt-hive outputs precise errors everywhere that refer to the faulty data byte.
* Full functionality even in a `no_std` environment (with `alloc`, some limitations without `alloc`).
* Static borrow checking everywhere. No mutexes or runtime borrowing.
* Zero-copy data representations wherever possible.
* No usage of `unsafe` anywhere. Checked arithmetic where needed.
* Platform and endian independence.
## Non-Goals
Full write support is currently not a goal for nt-hive.
This would require a wholly different architecture, where nt-hive loads a hive into linked in-memory data structures, keeps track of changes, and can write changes back to disk (possibly extending the on-disk file).
The current focus on read-only access allows for a simpler architecture.
## Examples
The following example reads the *List* value from the *ControlSet001\Control\ServiceGroupOrder* subkey of the *SYSTEM* hive, which is a real thing that happens during boot:
```rust,no_run
let mut buffer = Vec::new();
File::open("SYSTEM").unwrap().read_to_end(&mut buffer).unwrap();
let hive = Hive::new(buffer.as_ref()).unwrap();
let root_key_node = hive.root_key_node().unwrap();
let key_node = root_key_node.subpath("ControlSet001\\Control\\ServiceGroupOrder").unwrap().unwrap();
let key_value = key_node.value("List").unwrap().unwrap();
let multi_sz_data = key_value.multi_string_data();
if let Ok(vec) = multi_sz_data {
println!("Vector of REG_MULTI_SZ lines: {vec:?}");
}
```
Check out the [docs](https://docs.rs/nt-hive), the tests, and the supplied *readhive* example application for more ideas how to use nt-hive.
## Contributing and License
Contributions are currently preferred in the form of bug reports.
If you encounter a bug, an unexpected panic, or a potentially unsafe calculation, please [file a bug report](https://github.com/ColinFinck/nt-hive/issues).
nt-hive is available under *GNU General Public License 2.0 or (at your option) any later version*.
This license fits well with the projects I'm planning to use nt-hive for, and should allow integration into any open-source project.
I may however put nt-hive under a more permissive license later if you [give me a good reason](mailto:colin@reactos.org).
As relicensing requires permission from every contributor, I only accept code contributions that are explicitly put under [Creative Commons Zero (CC0)](https://creativecommons.org/publicdomain/zero/1.0/).
If that is not an option for you, you are still very welcome to suggest your change in a bug report.
## Further Resources
* [Windows registry file format specification](https://github.com/msuhanov/regf/blob/master/Windows%20registry%20file%20format%20specification.md) by [Maxim Suhanov](https://dfir.ru/)
* [cmlib library](https://github.com/reactos/reactos/tree/master/sdk/lib/cmlib) by the [ReactOS Project](https://reactos.org)