tacet-macros 0.4.2

Proc macros for tacet timing side-channel detection
Documentation 
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

<p align="center">
  <img src="https://raw.githubusercontent.com/agucova/tacet/main/website/public/logo-dark-bg.svg" alt="tacet-macros" width="340" />
</p>

<p align="center">
  <strong>Proc macros for side-channel tests.</strong>
</p>

<p align="center">
  <a href="https://crates.io/crates/tacet-macros"><img src="https://img.shields.io/crates/v/tacet-macros" alt="crates.io"></a>
  <a href="https://docs.rs/tacet-macros"><img src="https://img.shields.io/docsrs/tacet-macros" alt="docs.rs"></a>
  <a href="https://github.com/agucova/tacet/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MPL--2.0-blue" alt="License"></a>
</p>

---

This crate provides the `timing_test!` and `timing_test_checked!` macros for [`tacet`](https://lib.rs/crates/tacet). You typically don't need to depend on this crate directly.

## Installation

The macros are included when you enable the `macros` feature on `tacet` (enabled by default):

```toml
[dev-dependencies]
tacet = "0.1"
```

## Usage

### `timing_test!`

Returns `Outcome` for pattern matching on all four variants:

```rust
use tacet::{timing_test, Outcome};

let outcome = timing_test! {
    baseline: || [0u8; 32],
    sample: || rand::random::<[u8; 32]>(),
    measure: |input| {
        my_crypto_function(&input);
    },
};

match outcome {
    Outcome::Pass { leak_probability, .. } => {
        println!("No leak: {:.1}%", leak_probability * 100.0);
    }
    Outcome::Fail { exploitability, .. } => {
        panic!("Timing leak detected: {:?}", exploitability);
    }
    Outcome::Inconclusive { reason, .. } => {
        println!("Inconclusive: {:?}", reason);
    }
    Outcome::Unmeasurable { recommendation, .. } => {
        println!("Skipped: {}", recommendation);
    }
}
```

### `timing_test_checked!`

Same as `timing_test!` but panics on `Fail`:

```rust
use tacet::{timing_test_checked, Outcome};

// Panics if timing leak detected
let outcome = timing_test_checked! {
    baseline: || [0u8; 32],
    sample: || rand::random::<[u8; 32]>(),
    measure: |input| {
        constant_time_eq(&secret, &input);
    },
};
```

### Custom Oracle Configuration

```rust
use tacet::{timing_test, TimingOracle, AttackerModel};

let outcome = timing_test! {
    oracle: TimingOracle::for_attacker(AttackerModel::SharedHardware)
        .pass_threshold(0.01)
        .fail_threshold(0.99),
    baseline: || [0u8; 32],
    sample: || rand::random::<[u8; 32]>(),
    measure: |input| operation(&input),
};
```

## Syntax

```rust
timing_test! {
    // Optional: oracle configuration (defaults to AdjacentNetwork)
    oracle: TimingOracle::for_attacker(AttackerModel::AdjacentNetwork),

    // Required: baseline input generator
    baseline: || fixed_input,

    // Required: sample input generator
    sample: || random_input(),

    // Required: operation to measure
    measure: |input| operation(&input),
}
```

## Documentation

- [API Documentation](https://docs.rs/tacet-macros)
- [Main crate](https://lib.rs/crates/tacet)
- [GitHub Repository](https://github.com/agucova/tacet)

## License

MPL-2.0