lib-q-hash 0.0.2

Post-quantum Hash Functions for lib-Q
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159

# lib-q-hash: Post-Quantum Hash Functions

Rust implementation of post-quantum cryptographic hash functions based on SHA-3 and related algorithms. NIST-aligned SHA-3 / SHAKE / cSHAKE / TurboSHAKE are from [`lib-q-sha3`](https://github.com/Enkom-Tech/libQ/tree/main/lib-q-sha3); pre–FIPS **Keccak** fixed digests (`Keccak224` …, `Keccak256Full`) are from [`lib-q-keccak-digest`](https://github.com/Enkom-Tech/libQ/tree/main/lib-q-keccak-digest). This crate integrates them with [`lib-q-core`](https://github.com/Enkom-Tech/libQ/tree/main/lib-q-core) [`Hash`](https://docs.rs/lib-q-core) traits and algorithm identifiers.

## Supported Algorithms

### SHA-3 Family
- **SHA-3-224**, **SHA-3-256**, **SHA-3-384**, **SHA-3-512** - Fixed-length hash functions
- **SHAKE128** and **SHAKE256** - Extendable Output Functions (XOF)

### Customizable Variants
- **cSHAKE128** and **cSHAKE256** - Customizable XOFs
- **TurboSHAKE128** and **TurboSHAKE256** - Accelerated SHAKE variants

### Keccak Variants
- **Keccak-224**, **Keccak-256**, **Keccak-384**, **Keccak-512** - Original Keccak variants
- **Keccak256Full** - CryptoNight variant with 200-byte output

### Modern Functions
- **KT128 / KT256** (RFC 9861 KangarooTwelve) — fast parallel XOF
- **KMAC128** and **KMAC256** - Keyed Message Authentication Code
- **TupleHash128** and **TupleHash256** - Tuple-based hashing
- **ParallelHash128** and **ParallelHash256** - Parallel processing

## Usage

### Fixed-Length Hashing

```rust
use lib_q_hash::{Sha3_256, Digest};

let mut hasher = Sha3_256::new();
hasher.update(b"Hello, World!");
let result = hasher.finalize();
```

### Extendable Output

```rust
use lib_q_hash::{Shake128, digest::{Update, ExtendableOutput, XofReader}};

let mut hasher = Shake128::default();
hasher.update(b"Hello, World!");
let mut reader = hasher.finalize_xof();

let mut output = [0u8; 32];
reader.read(&mut output);
```

### Customizable Hashing

```rust
use lib_q_hash::{CShake256, digest::{Update, ExtendableOutput, XofReader}};

let mut hasher = CShake256::new_customized(b"MyApp");
hasher.update(b"Hello, World!");
let mut reader = hasher.finalize_xof();

let mut output = [0u8; 32];
reader.read(&mut output);
```

### KMAC

```rust
use lib_q_hash::{Kmac128, digest::{Update, ExtendableOutput}};

let mut kmac = Kmac128::new(b"key", b"custom");
kmac.update(b"message");
let mut output = [0u8; 32];
kmac.finalize(&mut output);
```

### TupleHash

```rust
use lib_q_hash::{TupleHash128, digest::{Update, ExtendableOutput}};

let mut tuplehash = TupleHash128::new(b"custom");
let tuple = vec![b"first", b"second"];
tuplehash.update_tuple(&tuple);
let mut output = [0u8; 32];
tuplehash.finalize(&mut output);
```

### ParallelHash

```rust
use lib_q_hash::{ParallelHash128, digest::{Update, ExtendableOutput}};

let mut parallelhash = ParallelHash128::new(b"custom", 8192);
parallelhash.update(b"large data");
let mut output = [0u8; 32];
parallelhash.finalize(&mut output);
```

### KT128 (KangarooTwelve, TurboSHAKE128)

```rust
use lib_q_hash::{Kt128, digest::{Update, ExtendableOutput, XofReader}};

let mut hasher = Kt128::new(b"customization");
hasher.update(b"Hello, World!");
let mut reader = hasher.finalize_xof();

let mut output = [0u8; 32];
reader.read(&mut output);
```

## lib-q-core Hash Trait

All hash functions are available through the unified `lib-q-core::Hash` trait:

```rust
use lib_q_hash::{create_hash, Hash};

let sha3_256 = create_hash("sha3-256").unwrap();
let kmac128 = create_hash("kmac128").unwrap();
let tuplehash128 = create_hash("tuplehash128").unwrap();

let data = b"Hello, World!";
let result = sha3_256.hash(data).unwrap();
```

## Available Algorithms

```rust
use lib_q_hash::available_algorithms;

let algorithms = available_algorithms();
// Returns: ["sha3-224", "sha3-256", "sha3-384", "sha3-512", "shake128", "shake256", 
//           "cshake128", "cshake256", "kangarootwelve", "keccak224", "keccak256", 
//           "keccak384", "keccak512", "kmac128", "kmac256", "tuplehash128", 
//           "tuplehash256", "parallelhash128", "parallelhash256"]
```

## Architecture

- **Shared Core**: All hash functions use the same underlying Keccak permutation
- **Unified API**: Consistent interface through the `lib-q-core::Hash` trait
- **Type Safety**: Strong typing with compile-time guarantees
- **Zero-Copy**: Efficient memory usage with minimal allocations

## Features

- `default` - Enables alloc and OID support
- `alloc` - Heap allocation for dynamic output sizes
- `oid` - Object Identifier support for ASN.1
- `zeroize` - Secure memory wiping
- `parallelhash` - Rayon-based parallel processing
- `asm` - ARMv8 assembly optimizations

## Workspace

This file documents the `lib-q-hash` integration layer; algorithm implementations live in `lib-q-sha3`, `lib-q-keccak`, `lib-q-k12`, and `lib-q-keccak-digest`. See the [crate README](../README.md) and [repository README](../../README.md).

## License

Apache License, Version 2.0