Skip to content

Commit f6d9547

Browse files
tarcieritarcieri
committed
alloc-free usage notes and fixups for all crates
All crates in this repo now have an optional `alloc` feature which can be disabled for use in heapless environments.
1 parent 2ac7696 commit f6d9547

File tree

7 files changed

+161
-4
lines changed

7 files changed

+161
-4
lines changed

‎aes-gcm-siv/Cargo.toml‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,16 +19,20 @@ categories = ["cryptography", "no-std"]
1919
maintenance = { status = "experimental" }
2020

2121
[dependencies]
22-
aead = "0.2"
22+
aead = { version = "0.2", default-features = false }
2323
aes = "0.3"
24-
polyval = "0.3"
24+
polyval = { version = "0.3", default-features = false }
2525
subtle = { version = "2", default-features = false }
2626
zeroize = { version = "1", default-features = false }
2727

2828
[dev-dependencies]
2929
criterion = "0.3.0"
3030
criterion-cycles-per-byte = "0.1.1"
3131

32+
[features]
33+
default = ["alloc"]
34+
alloc = ["aead/alloc"]
35+
3236
[[bench]]
3337
name = "aes-gcm-siv"
3438
harness = false

‎aes-gcm-siv/src/lib.rs‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,12 +53,43 @@
5353
//! assert_eq!(&plaintext, b"plaintext message");
5454
//! ```
5555
//!
56+
//! ## In-place Usage (eliminates `alloc` requirement)
57+
//!
58+
//! This crate has an optional `alloc` feature which can be disabled in e.g.
59+
//! microcontroller environments that don't have a heap.
60+
//!
61+
//! The [`Aead::encrypt_in_place`][7] and [`Aead::decrypt_in_place`][8]
62+
//! methods accept any type that impls the [`aead::Buffer`][9] trait which
63+
//! contains the plaintext for encryption or ciphertext for decryption.
64+
//!
65+
//! Note that if you enable the `heapless` feature of the `aead` crate,
66+
//! you will receive an impl of `aead::Buffer` for the [`heapless::Vec`][10]
67+
//! type, which can then be passed as the `buffer` parameter to the
68+
//! in-place encrypt and decrypt methods.
69+
//!
70+
//! In `Cargo.toml`, add:
71+
//!
72+
//! ```toml
73+
//! [dependencies.aead]
74+
//! version = "0.2"
75+
//! default-features = false
76+
//! features = ["heapless"]
77+
//!
78+
//! [dependencies.aes-gcm-siv]
79+
//! version = "0.2"
80+
//! default-features = false
81+
//! ```
82+
//!
5683
//! [1]: https://en.wikipedia.org/wiki/AES-GCM-SIV
5784
//! [2]: https://tools.ietf.org/html/rfc8452
5885
//! [3]: https://en.wikipedia.org/wiki/Authenticated_encryption
5986
//! [4]: https://github.com/miscreant/meta/wiki/Nonce-Reuse-Misuse-Resistance
6087
//! [5]: https://www.imperialviolet.org/2017/05/14/aesgcmsiv.html
6188
//! [6]: https://codahale.com/towards-a-safer-footgun/
89+
//! [7]: https://docs.rs/aead/latest/aead/trait.Aead.html#method.encrypt_in_place
90+
//! [8]: https://docs.rs/aead/latest/aead/trait.Aead.html#method.decrypt_in_place
91+
//! [9]: https://docs.rs/aead/latest/aead/trait.Buffer.html
92+
//! [10]: https://docs.rs/heapless/latest/heapless/struct.Vec.html
6293
6394
#![no_std]
6495
#![doc(html_logo_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo_small.png")]

‎aes-gcm/src/lib.rs‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,8 +39,39 @@
3939
//! assert_eq!(&plaintext, b"plaintext message");
4040
//! ```
4141
//!
42+
//! ## In-place Usage (eliminates `alloc` requirement)
43+
//!
44+
//! This crate has an optional `alloc` feature which can be disabled in e.g.
45+
//! microcontroller environments that don't have a heap.
46+
//!
47+
//! The [`Aead::encrypt_in_place`][3] and [`Aead::decrypt_in_place`][4]
48+
//! methods accept any type that impls the [`aead::Buffer`][5] trait which
49+
//! contains the plaintext for encryption or ciphertext for decryption.
50+
//!
51+
//! Note that if you enable the `heapless` feature of the `aead` crate,
52+
//! you will receive an impl of `aead::Buffer` for the [`heapless::Vec`][6]
53+
//! type, which can then be passed as the `buffer` parameter to the
54+
//! in-place encrypt and decrypt methods.
55+
//!
56+
//! In `Cargo.toml`, add:
57+
//!
58+
//! ```toml
59+
//! [dependencies.aead]
60+
//! version = "0.2"
61+
//! default-features = false
62+
//! features = ["heapless"]
63+
//!
64+
//! [dependencies.aes-gcm]
65+
//! version = "0.2"
66+
//! default-features = false
67+
//! ```
68+
//!
4269
//! [1]: https://en.wikipedia.org/wiki/Authenticated_encryption
4370
//! [2]: https://en.wikipedia.org/wiki/Galois/Counter_Mode
71+
//! [3]: https://docs.rs/aead/latest/aead/trait.Aead.html#method.encrypt_in_place
72+
//! [4]: https://docs.rs/aead/latest/aead/trait.Aead.html#method.decrypt_in_place
73+
//! [5]: https://docs.rs/aead/latest/aead/trait.Buffer.html
74+
//! [6]: https://docs.rs/heapless/latest/heapless/struct.Vec.html
4475
4576
#![no_std]
4677
#![doc(html_logo_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo_small.png")]

‎aes-siv/src/lib.rs‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,42 @@
22
//! [Authenticated Encryption with Associated Data (AEAD)][3] cipher which also
33
//! provides [nonce reuse misuse resistance][4].
44
//!
5+
//!
6+
//! ## In-place Usage (eliminates `alloc` requirement)
7+
//!
8+
//! This crate has an optional `alloc` feature which can be disabled in e.g.
9+
//! microcontroller environments that don't have a heap.
10+
//!
11+
//! The [`Aead::encrypt_in_place`][5] and [`Aead::decrypt_in_place`][6]
12+
//! methods accept any type that impls the [`aead::Buffer`][7] trait which
13+
//! contains the plaintext for encryption or ciphertext for decryption.
14+
//!
15+
//! Note that if you enable the `heapless` feature of the `aead` crate,
16+
//! you will receive an impl of `aead::Buffer` for the [`heapless::Vec`][8]
17+
//! type, which can then be passed as the `buffer` parameter to the
18+
//! in-place encrypt and decrypt methods.
19+
//!
20+
//! In `Cargo.toml`, add:
21+
//!
22+
//! ```toml
23+
//! [dependencies.aead]
24+
//! version = "0.2"
25+
//! default-features = false
26+
//! features = ["heapless"]
27+
//!
28+
//! [dependencies.aes-siv]
29+
//! version = "0.2"
30+
//! default-features = false
31+
//! ```
32+
//!
533
//! [1]: https://github.com/miscreant/meta/wiki/AES-SIV
634
//! [2]: https://tools.ietf.org/html/rfc5297
735
//! [3]: https://en.wikipedia.org/wiki/Authenticated_encryption
836
//! [4]: https://github.com/miscreant/meta/wiki/Nonce-Reuse-Misuse-Resistance
37+
//! [5]: https://docs.rs/aead/latest/aead/trait.Aead.html#method.encrypt_in_place
38+
//! [6]: https://docs.rs/aead/latest/aead/trait.Aead.html#method.decrypt_in_place
39+
//! [7]: https://docs.rs/aead/latest/aead/trait.Buffer.html
40+
//! [8]: https://docs.rs/heapless/latest/heapless/struct.Vec.html
941
1042
#![no_std]
1143
#![doc(html_logo_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo_small.png")]

‎chacha20poly1305/Cargo.toml‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,11 +19,12 @@ categories = ["cryptography", "no-std"]
1919
maintenance = { status = "experimental" }
2020

2121
[dependencies]
22-
aead = "0.2"
22+
aead = { version = "0.2", default-features = false }
2323
chacha20 = { version = "0.2.1", features = ["zeroize"] }
2424
poly1305 = "0.5"
2525
zeroize = { version = "1", default-features = false }
2626

2727
[features]
28-
default = ["xchacha20poly1305"]
28+
default = ["alloc", "xchacha20poly1305"]
29+
alloc = ["aead/alloc"]
2930
xchacha20poly1305 = ["chacha20/xchacha20"]

‎chacha20poly1305/src/lib.rs‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,10 +32,41 @@
3232
//! assert_eq!(&plaintext, b"plaintext message");
3333
//! ```
3434
//!
35+
//! ## In-place Usage (eliminates `alloc` requirement)
36+
//!
37+
//! This crate has an optional `alloc` feature which can be disabled in e.g.
38+
//! microcontroller environments that don't have a heap.
39+
//!
40+
//! The [`Aead::encrypt_in_place`][5] and [`Aead::decrypt_in_place`][6]
41+
//! methods accept any type that impls the [`aead::Buffer`][7] trait which
42+
//! contains the plaintext for encryption or ciphertext for decryption.
43+
//!
44+
//! Note that if you enable the `heapless` feature of the `aead` crate,
45+
//! you will receive an impl of `aead::Buffer` for the [`heapless::Vec`][8]
46+
//! type, which can then be passed as the `buffer` parameter to the
47+
//! in-place encrypt and decrypt methods.
48+
//!
49+
//! In `Cargo.toml`, add:
50+
//!
51+
//! ```toml
52+
//! [dependencies.aead]
53+
//! version = "0.2"
54+
//! default-features = false
55+
//! features = ["heapless"]
56+
//!
57+
//! [dependencies.chacha20poly1305]
58+
//! version = "0.2"
59+
//! default-features = false
60+
//! ```
61+
//!
3562
//! [1]: https://tools.ietf.org/html/rfc8439
3663
//! [2]: https://en.wikipedia.org/wiki/Authenticated_encryption
3764
//! [3]: https://github.com/RustCrypto/stream-ciphers/tree/master/chacha20
3865
//! [4]: https://github.com/RustCrypto/universal-hashes/tree/master/poly1305
66+
//! [5]: https://docs.rs/aead/latest/aead/trait.Aead.html#method.encrypt_in_place
67+
//! [6]: https://docs.rs/aead/latest/aead/trait.Aead.html#method.decrypt_in_place
68+
//! [7]: https://docs.rs/aead/latest/aead/trait.Buffer.html
69+
//! [8]: https://docs.rs/heapless/latest/heapless/struct.Vec.html
3970
4071
#![no_std]
4172
#![doc(html_logo_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo_small.png")]

‎xsalsa20poly1305/src/lib.rs‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,33 @@
3434
//! assert_eq!(&plaintext, b"plaintext message");
3535
//! ```
3636
//!
37+
//! ## In-place Usage (eliminates `alloc` requirement)
38+
//!
39+
//! This crate has an optional `alloc` feature which can be disabled in e.g.
40+
//! microcontroller environments that don't have a heap.
41+
//!
42+
//! The [`Aead::encrypt_in_place`][3] and [`Aead::decrypt_in_place`][4]
43+
//! methods accept any type that impls the [`aead::Buffer`][5] trait which
44+
//! contains the plaintext for encryption or ciphertext for decryption.
45+
//!
46+
//! Note that if you enable the `heapless` feature of the `aead` crate,
47+
//! you will receive an impl of `aead::Buffer` for the [`heapless::Vec`][6]
48+
//! type, which can then be passed as the `buffer` parameter to the
49+
//! in-place encrypt and decrypt methods.
50+
//!
51+
//! In `Cargo.toml`, add:
52+
//!
53+
//! ```toml
54+
//! [dependencies.aead]
55+
//! version = "0.2"
56+
//! default-features = false
57+
//! features = ["heapless"]
58+
//!
59+
//! [dependencies.xsalsa20poly1305]
60+
//! version = "0.2"
61+
//! default-features = false
62+
//! ```
63+
//!
3764
//! [1]: https://nacl.cr.yp.to/secretbox.html
3865
//! [2]: https://en.wikipedia.org/wiki/Authenticated_encryption
3966
//! [3]: https://github.com/RustCrypto/stream-ciphers/tree/master/salsa20

0 commit comments

Comments
 (0)