You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
**liboqs-rust** offers two Rust wrappers for the [Open Quantum Safe](https://openquantumsafe.org/)[liboqs](https://github.com/open-quantum-safe/liboqs/) C library, which is a C library for quantum-resistant cryptographic algorithms.
12
11
13
-
* The ``oqs-sys`` crate compiles and builds ``liboqs`` and generates ``unsafe`` bindings to the C library.
14
-
* The ``oqs`` crate offers a Rust-style safe interface to the schemes included in ``liboqs``.
12
+
- The `oqs-sys` crate compiles and builds `liboqs` and generates `unsafe` bindings to the C library.
13
+
- The `oqs` crate offers a Rust-style safe interface to the schemes included in `liboqs`.
15
14
16
-
Versioning
17
-
----------
15
+
## Versioning
18
16
19
17
The version numbers follow the upstream `liboqs` versions, but with a twist.
20
18
The `liboqs` version `0.7.2` gets released as the `oqs` and `oqs-sys` version `0.7.2xx` series.
21
19
This allows us to release patch versions of the Rust bindings as `0.7.201`, `0.7.202`, and so on.
22
20
23
-
Pre-requisites
24
-
--------------
21
+
## Pre-requisites
25
22
26
-
``oqs-sys`` depends on the [liboqs](https://github.com/open-quantum-safe/liboqs) C library.
27
-
It will build ``liboqs`` automatically.
23
+
`oqs-sys` depends on the [liboqs](https://github.com/open-quantum-safe/liboqs) C library.
24
+
It will build `liboqs` automatically.
28
25
29
-
Contents
30
-
--------
26
+
## Contents
31
27
32
28
This crate provides unsafe `ffi` bindings in the `oqs-sys` crate, and safe wrappers are offered via the `oqs` crate.
33
29
The rendered rustdoc documentation can be [found here](https://open-quantum-safe.github.io/liboqs-rust/oqs/)
34
30
35
-
Usage
36
-
-----
31
+
## Usage
37
32
38
-
Update your ``Cargo.toml`` and include ``oqs``:
33
+
Update your `Cargo.toml` and include `oqs`:
39
34
40
35
```toml
41
36
[dependencies]
42
37
oqs = "*"
43
38
```
44
39
45
-
``oqs-sys`` can be specified equivalently.
40
+
`oqs-sys` can be specified equivalently.
46
41
47
-
Minimal builds
48
-
--------------
42
+
## Minimal builds
49
43
50
44
The default-on `kems` and `sigs` features turn on all supported KEMs and signature schemes. If you want a smaller build, turn off these default features and opt-in to individual algorithms.
51
45
Note that if you specify `default-features = false`, you may also want to re-include the `oqs-sys/openssl` feature.
52
46
53
-
Vendored `liboqs`
54
-
-----------------
47
+
## Vendored `liboqs`
55
48
56
49
By default `oqs-sys` attempts to find a system-provided version of `liboqs` and build against it,
57
50
falling back to vendored from-source build otherwise.
@@ -60,19 +53,17 @@ You can opt into forcing the vendored build by enabling the `vendored` feature.
60
53
Otherwise, if you want to force using the system-provided `liboqs`,
61
54
you can set the `LIBOQS_NO_VENDOR=1` environment variable and the build will fail if the library is not found.
62
55
63
-
Serde support
64
-
-------------
56
+
## Serde support
65
57
66
-
You can enable ``serde`` serialization support by enabling the ``serde`` feature on the ``oqs`` crate.
58
+
You can enable `serde` serialization support by enabling the `serde` feature on the `oqs` crate.
67
59
68
-
``std`` support
69
-
----------------
60
+
## `std` support
70
61
71
-
The ``oqs-sys`` crate does not use `std` at all.
72
-
Note that the default features do enable building liboqs with ``openssl``, so use ``default-features = false``.
62
+
The `oqs-sys` crate does not use `std` at all.
63
+
Note that the default features do enable building liboqs with `openssl`, so use `default-features = false`.
73
64
74
-
To make ``oqs`` a ``#![no_std]`` crate make sure the ``std`` feature is disabled.
75
-
Make sure to also disable the ``oqs-sys/openssl`` feature by specifying ``default-features = false``.
65
+
To make `oqs` a `#![no_std]` crate make sure the `std` feature is disabled.
66
+
Make sure to also disable the `oqs-sys/openssl` feature by specifying `default-features = false`.
76
67
77
68
As `default-features` includes the `kems` and `sigs` features, consider re-adding them as well. This results into:
78
69
@@ -87,41 +78,36 @@ You will probably want to change the random-number generator through the [`OQS_R
If compiled with the ``non_portable`` feature, ``liboqs-sys`` will not enable CPU feature detection and
83
+
If compiled with the `non_portable` feature, `liboqs-sys` will not enable CPU feature detection and
94
84
always use the best implementation on your current platform. This enables support for implementations
95
85
where feature detection is not functional.
96
86
97
-
Stack usage
98
-
-----------
87
+
## Stack usage
99
88
100
-
Some algorithms use large amounts of stack space. This means that you may need to specify ``RUST_MIN_STACK`` in your environment.
89
+
Some algorithms use large amounts of stack space. This means that you may need to specify `RUST_MIN_STACK` in your environment.
101
90
This for example affects tests.
102
91
103
-
Algorithm features
104
-
------------------
105
-
106
-
*`kems` (default): Compile with all KEMs enabled
107
-
*`bike`
108
-
*`classic_mceliece`
109
-
*`frodokem`
110
-
*`hqc`
111
-
*`kyber`
112
-
*`ntru`
113
-
*`ntruprime`
114
-
*`saber`
115
-
*`sigs` (default): Compile with all signature schemes enabled
116
-
*`dilithium`
117
-
*`falcon`
118
-
*`picnic`
119
-
*`rainbow`
120
-
*`sphincs`: SPHINCS+
121
-
122
-
123
-
Running
124
-
-------
92
+
## Algorithm features
93
+
94
+
-`kems` (default): Compile with all KEMs enabled
95
+
-`bike`
96
+
-`classic_mceliece`
97
+
-`frodokem`
98
+
-`hqc`
99
+
-`kyber`
100
+
-`ntru`
101
+
-`ntruprime`
102
+
-`saber`
103
+
-`sigs` (default): Compile with all signature schemes enabled
104
+
-`dilithium`
105
+
-`falcon`
106
+
-`picnic`
107
+
-`rainbow`
108
+
-`sphincs`: SPHINCS+
109
+
110
+
## Running
125
111
126
112
```rust
127
113
/// # Example: Some signed KEX
@@ -157,28 +143,29 @@ fn main() -> Result<()> {
157
143
}
158
144
```
159
145
160
-
161
-
Adding new algorithms
162
-
---------------------
146
+
## Adding new algorithms
163
147
164
148
### KEMs
165
149
166
150
1. Update the Git submodule
167
151
2.`oqs-sys` will now update when you build again
168
-
3. Add it to the ``implement_kems!`` macro call in ``oqs/src/kem.rs``:
169
-
- The structure is a name for the algorithm in CamelCase, and the name of the constant of the algorithm (``OQS_KEM_alg_...``)
152
+
3. Add it to the `implement_kems!` macro call in `oqs/src/kem.rs`:
153
+
154
+
- The structure is a name for the algorithm in CamelCase, and the name of the constant of the algorithm (`OQS_KEM_alg_...`)
155
+
170
156
4. Add the necessary features to `Cargo.toml` and `oqs-sys/build.rs`.
171
157
172
158
### Signature schemes:
173
159
174
160
1. Update the Git submodule
175
161
2.`oqs-sys` is now up-to-date when you build again
176
-
3. Add it to ``implement_sigs!`` macro call in ``oqs/src/sig.rs``.
177
-
- The structure is a name for the algorithm in CamelCase, and the name of the constant of the algorithm (``OQS_SIG_alg_...``)
162
+
3. Add it to `implement_sigs!` macro call in `oqs/src/sig.rs`.
163
+
164
+
- The structure is a name for the algorithm in CamelCase, and the name of the constant of the algorithm (`OQS_SIG_alg_...`)
165
+
178
166
4. Add the necessary features to `Cargo.toml` and `oqs-sys/build.rs`.
179
167
180
-
Limitations and security
181
-
------------------------
168
+
## Limitations and security
182
169
183
170
liboqs is designed for prototyping and evaluating quantum-resistant cryptography. Security of proposed quantum-resistant algorithms may rapidly change as research advances, and may ultimately be completely insecure against either classical or quantum computers.
184
171
@@ -188,15 +175,13 @@ We acknowledge that some parties may want to begin deploying post-quantum crypto
188
175
189
176
Just like liboqs, liboqs-rust is provided "as is", without warranty of any kind. See [LICENSE-MIT](https://github.com/open-quantum-safe/liboqs-rust/blob/main/LICENSE-MIT) for the full disclaimer.
190
177
191
-
License
192
-
-------
178
+
## License
193
179
194
180
liboqs-rust is dual-licensed under the MIT and Apache-2.0 licenses.
195
181
196
-
The included library ``liboqs`` is covered by the [``liboqs`` license](https://github.com/open-quantum-safe/liboqs/blob/main/LICENSE.txt).
182
+
The included library `liboqs` is covered by the [`liboqs` license](https://github.com/open-quantum-safe/liboqs/blob/main/LICENSE.txt).
197
183
198
-
Team
199
-
----
184
+
## Team
200
185
201
186
The Open Quantum Safe project is led by [Douglas Stebila](https://www.douglas.stebila.ca/research/) and [Michele Mosca](http://faculty.iqc.uwaterloo.ca/mmosca/) at the University of Waterloo.
0 commit comments