tcg-log-core-rs 0.1.2

# tcg-log-core-rs


A small Rust library for parsing Trusted Computing Group (TCG) Windows Boot Configuration Logs (WBCL). It provides a safe, idiomatic wrapper for iterating through PCR event entries from a WBCL buffer, supporting legacy PC Client (TCG1.2) and TCG2 formats with multiple digest algorithms.

## Features

- Zero-copy iteration over WBCL buffers provided as `&[u8]`.
- Supports TCG EFI SpecID events and TCG2 multi-digest headers.
- Extracts per-entry metadata:
  - PCR index
  - Event type
  - Digest(s) slice
  - Event data size and slice
- Simple API surface with `WbclIterator` and helper free functions.
- Minimal dependencies (once_cell only).

## Status

This is an early crate (0.1.2) intended for experimentation, learning, or narrow tooling purposes. The public API may change.

## Installation

Add to your `Cargo.toml`:

```toml
[dependencies]
tcg-log-core-rs = "0.1.2"
```

Rust edition: 2024 (as per Cargo.toml).

## Quick Start

The API works over an in-memory WBCL buffer, commonly read from a file (on Windows, for example, from the WBCL exported by system tools).

```rust
use tcg_log_core_rs::{parse, EventRecord}; // crate name is tcg-log-core-rs in Cargo.toml

fn main() {
    let path = "//your//wbcl.file"; // adjust to your WBCL path
    match parse(path) {
        Ok(events) => {
            for e in events {
                println!("PCR: {}, Type: 0x{:x}", e.pcr_index, e.event_type);
            }
        }
        Err(err) => eprintln!("Error: {}", err),
    }
}
```

## Concepts and API


### Core Types

- Internal: `wbcl::WbclIterator<'a>`: Stateful iterator over a WBCL byte buffer used by the crate internally. It validates headers, keeps current offset, and exposes helpers to read the current element. Its module is not currently public; prefer the high-level `parse` function.

### Constructor

- `WbclIterator::new(log_buffer: &'a [u8]) -> Result<Self, u32>`
  - Validates the buffer, parses initial headers (e.g., SpecID event and TCG2 algorithm table), and positions before the first real event.

### Iteration

- `has_next(&self) -> bool` — Whether another event can be read.
- `move_to_next_element(&mut self) -> Result<(), u32>` — Advance to the next event.
- `get_current_element(&self) -> Result<(u32, u32, Option<&'a [u8]>, u32, Option<&'a [u8]>), u32>`
  - Returns a tuple:
    - `(pcr_index, event_type, digest_slice_opt, event_data_size, event_data_slice_opt)`
  - When multiple digests are present (TCG2), this returns the combined/selected digest region for the current element. Consult the source for details.

### Internal Helpers

The crate contains internal helper functions around the WBCL iterator for experimentation. These are not part of the public API and may change or be made public in a future release.

## Error Handling

- High-level API: `parse(path: &str) -> Result<Vec<EventRecord>, String>` returns a String on error (e.g., I/O issues, parse failures).
- Internal iterator: functions return `Result<_, u32>` where the `u32` is an error code. Common conditions include:
  - Invalid or too-small buffer
  - Unsupported or malformed WBCL headers
  - Out-of-bounds sizes when parsing elements

During development, you can consult the tests in `src/lib.rs` for behavior expectations. If working with internal error codes, they are hex-friendly; when printing, use `0x{code:08x}` to make debugging easier.

## Examples

- Reading from a file and printing PCR and event type: see Quick Start.

## Windows Notes

- Paths in examples use forward slashes (e.g., `D:/temp/your.log`) which work on Windows Rust as well; backslashes also work if properly escaped.

## Testing

Run the test suite:

```bash
cargo test
```

Note: Some tests assume presence of a local WBCL file; you may skip or adjust those if you do not have one.

## Safety Notes

- All parsing operates on borrowed byte slices; no unsafe memory ownership tricks are required by the user of the API.
- Internally, bounds are checked before slicing to prevent panics.
- The crate aims to avoid allocations during iteration.

## Limitations and Roadmap

- The iterator currently exposes only a single digest slice per element even in multi-digest TCG2 scenarios; richer per-algorithm access may be added later.
- The public API and error codes may evolve prior to 1.0.

## Contributing

Issues and PRs are welcome. Please:
- Include a clear description and, where possible, a reproducible case.
- Add tests covering new functionality or bug fixes.

## License

Licensed under either of
- Apache License, Version 2.0, or
- MIT license
at your option. See the LICENSE files if present or Cargo.toml’s `license` field.

## Acknowledgements

- TCG specifications for PC Client and EFI are the basis of the formats handled here.
- Inspiration from platform attestation tooling and WBCL readers in other languages.