# `webbuf_blake3` Library
`webbuf_blake3` is a Rust library that provides an easy-to-use interface for
computing BLAKE3 hashes, double hashes, and Message Authentication Codes (MAC)
using the BLAKE3 algorithm. This library is designed to work with both Rust and
JavaScript/TypeScript by enabling WASM support with an optional feature.
## Features
- **BLAKE3 Hashing**: Compute hashes with the BLAKE3 algorithm for data
integrity and verification.
- **Double Hashing**: Hash a message twice to provide enhanced security (e.g.,
for blockchain applications).
- **MAC Generation**: Create a keyed MAC using BLAKE3 to verify data integrity
and authenticity.
- **WASM Support**: Build the library for WebAssembly with the `wasm` feature,
enabling usage in JavaScript environments.
---
## Installation
Add the following dependency to your `Cargo.toml`:
```toml
[dependencies]
webbuf_blake3 = { version = "0.8.0", features = ["wasm"] } # Enable WASM if needed
```
To build the library for **Rust-only** usage, skip the `wasm` feature:
```toml
[dependencies]
webbuf_blake3 = "0.8.0"
```
---
## Usage
### Rust Example
```rust
use webbuf_blake3::{blake3_hash, double_blake3_hash, blake3_mac};
// Compute a BLAKE3 hash
let data = b"hello world";
let hash = blake3_hash(data).unwrap();
println!("BLAKE3 hash: {:?}", hash);
// Compute a double BLAKE3 hash
let double_hash = double_blake3_hash(data).unwrap();
println!("Double BLAKE3 hash: {:?}", double_hash);
// Generate a keyed MAC
let key = [0x00; 32]; // 32-byte key
let mac = blake3_mac(&key, data).unwrap();
println!("BLAKE3 MAC: {:?}", mac);
```
### JavaScript/TypeScript Example (with WASM)
When building with `wasm-pack`, the functions are exposed to JavaScript.
Example:
```javascript
import init, {
blake3_hash,
double_blake3_hash,
blake3_mac,
} from "./your-wasm-package";
async function example() {
await init(); // Initialize the WASM module
const data = new TextEncoder().encode("hello world");
const hash = blake3_hash(data);
console.log("BLAKE3 hash:", new Uint8Array(hash));
const doubleHash = double_blake3_hash(data);
console.log("Double BLAKE3 hash:", new Uint8Array(doubleHash));
const key = new Uint8Array(32); // 32-byte key
const mac = blake3_mac(key, data);
console.log("BLAKE3 MAC:", new Uint8Array(mac));
}
example();
```
---
## Building with WASM
To build the library for WebAssembly, use:
```bash
wasm-pack build -- --features wasm
```
To build the library for native Rust usage (without WASM):
```bash
cargo build
```
---
## API
### `blake3_hash(data: &[u8]) -> Result<Vec<u8>, String>`
Computes a BLAKE3 hash for the given data.
### `double_blake3_hash(data: &[u8]) -> Result<Vec<u8>, String>`
Computes a double BLAKE3 hash by hashing the input twice.
### `blake3_mac(key: &[u8], data: &[u8]) -> Result<Vec<u8>, String>`
Generates a keyed MAC using the BLAKE3 algorithm. The key must be exactly 32
bytes.
---
## Tests
The library includes unit tests to ensure correctness. Run tests with:
```bash
cargo test
```
Example Test Case:
```rust
#[test]
fn test_blake3_mac() {
let key = blake3_hash(b"key").unwrap();
let mac = blake3_mac(&key, b"data").unwrap();
let expected_mac = hex::decode("438f903a8fc5997489497c30477dc32c5ece10f44049e302b85a83603960ec27").unwrap();
assert_eq!(mac, expected_mac);
}
```
---
## License
This project is licensed under the MIT License. See the `LICENSE` file for
details.
---
## Contributing
Feel free to open issues and submit pull requests. Contributions are welcome!