rxwing 0.1.0-draft10

Minimalist pure Rust implementation of the X-Wing Key Encapsulation Mechanism (draft 10)
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

# [Handcrafted Security]: rxwing

A minimalist pure Rust implementation of X-Wing, a general-purpose post-quantum/traditional
hybrid key encapsulation mechanism (PQ/T KEM) built on X25519 and ML-KEM-768.
Built on the [rkyber] and [x25519-dalek] crates.

Current implementation matches the [draft RFC][RFC-DRAFT] version 10.

The original paper: [X-Wing The Hybrid KEM You’ve Been Looking For][X-WING-PAPER]


## Features

The following optional features are provided by this crate:
* `portablerandom`: Enables `generate_key_pair` (generate without an explicit RNG)
* `zeroize`: Enables memory zeroing for all cryptographic secrets
* `rfctest`: Enables testing against the [draft RFC][RFC-DRAFT] test values without cluttering your development environment
* `benchmarking` - bring in all the dependencies needed for the benchmarking framework - not needed for development!
* `cyclecount` - enable cycle count benchmarking, currently only really works on x86_64.


## Benchmarking

How to benchmark (on x86_64, Zen 2 and newer optionally with cycle counts):
```shell
sh run_benchmark.sh
```

Results on one developer machine (x86_64, Zen3, no direct assembly except getrandom syscall):

X-Wing keygen time: [46.340 µs 46.498 µs 46.697 µs]  
X-Wing encaps time: [85.701 µs 85.748 µs 85.802 µs]  
X-Wing decaps time: [103.48 µs 103.58 µs 103.68 µs]

X-Wing keygen cycles: [220078.5361 cycles 221510.9805 cycles 223138.8837 cycles]  
X-Wing encaps cycles: [399181.0396 cycles 399379.9701 cycles 399606.1905 cycles]  
X-Wing decaps cycles: [480182.0940 cycles 480540.6919 cycles 480937.0418 cycles]  


## [Reproducible Builds]

You can check (for example in your CI/CD setup) if your build can be reproduced by using the provided script, directly adapted from the R-Bs project documentation for [Rust Reproducible Builds]:
``` shell
sh check_reproducible.sh
```


## ⚠️ Security Warning

The implementation contained in this crate has never been independently audited!

USE AT YOUR OWN RISK!


## License

Currently, unless the contributors decide otherwise, this project is licensed under either of:

- [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
- [MIT license](http://opensource.org/licenses/MIT)

at your option.


### Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.
All contributions have to be with full knowledge and intent.
You can find [Handcrafted Security on Codeberg] and just for `crates.io` integration we have an empty [Handcrafted Security on GitHub].


[//]: # (links)

[RFC-DRAFT]: https://datatracker.ietf.org/doc/html/draft-connolly-cfrg-xwing-kem
[X-WING-PAPER]: https://eprint.iacr.org/2024/039.pdf
[x25519-dalek]: https://crates.io/crates/x25519-dalek
[rkyber]: https://crates.io/crates/rkyber
[Handcrafted Security]: https://handcrafted-security.org
[Handcrafted Security on Codeberg]: https://codeberg.org/handcrafted-security
[Handcrafted Security on GitHub]: https://github.com/handcrafted-security
[Reproducible Builds]: https://reproducible-builds.org
[Rust Reproducible Builds]: https://reproducible-builds.org/docs/rust/