nacl_sealed_box/lib.rs
1#![no_std]
2#![forbid(unsafe_code)]
3#![deny(missing_docs)]
4//! Minimal libsodium-compatible sealed boxes using the fixed NaCl
5//! XSalsa20-Poly1305 `crypto_box` suite.
6//!
7//! Sealing uses caller-supplied cryptographic randomness. Authenticated
8//! opening returns a redacted, zeroizing plaintext owner.
9//!
10//! # Features
11//!
12//! No feature is enabled by default. The optional `getrandom` feature adds only
13//! the `seal` convenience, which delegates to [`seal_with_rng`] with the
14//! operating-system generator and never falls back to a seeded generator.
15//!
16//! The default set stays empty on purpose: the operating-system generator has no
17//! bare-metal backend and needs a consumer-enabled backend on WebAssembly, so
18//! enabling it by default would remove targets from every dependent.
19//!
20//! # Supported targets
21//!
22//! The library is `no_std` and needs only `alloc`; every public operation
23//! allocates, so allocation is not optional.
24//!
25//! With optional features disabled, continuous integration compiles the library
26//! for `thumbv7em-none-eabi`, `wasm32-unknown-unknown`, and
27//! `x86_64-unknown-linux-musl`, and runs the complete test suite on
28//! `x86_64-unknown-linux-gnu`. Compiling is the claim those targets carry; the
29//! suite itself is executed only on host targets.
30//!
31//! The `getrandom` feature narrows that set. It cannot build for
32//! `thumbv7em-none-eabi` without a custom backend, and on
33//! `wasm32-unknown-unknown` the final binary must also enable
34//! `getrandom/wasm_js`.
35
36extern crate alloc;
37
38mod error;
39mod key;
40mod sealed_box;
41mod secretbox;
42
43pub use error::Error;
44pub use key::{PublicKey, SecretKey};
45pub use sealed_box::{Plaintext, seal_with_rng, unseal};
46
47#[cfg(feature = "getrandom")]
48pub use sealed_box::seal;
49
50// Provenance: RustCrypto nacl-compat crypto_box/src/lib.rs::{KEY_SIZE,
51// TAG_SIZE,SEALBYTES} at 9d021008360d05bc27ff248f33eb6123da0214ac,
52// reconciled with libsodium 1.0.22 crypto_box.h.
53/// Size in bytes of an X25519 recipient public key.
54pub const PUBLIC_KEY_SIZE: usize = 32;
55
56/// Size in bytes of an X25519 recipient secret key.
57pub const SECRET_KEY_SIZE: usize = 32;
58
59/// Number of bytes added to a plaintext by the sealed-box wire format.
60///
61/// The overhead is a 32-byte ephemeral public key followed by a 16-byte
62/// Poly1305 authentication tag.
63pub const SEAL_OVERHEAD: usize = 48;
64
65pub(crate) fn checked_seal_len(plaintext_len: usize) -> Result<usize, Error> {
66 plaintext_len
67 .checked_add(SEAL_OVERHEAD)
68 .ok_or(Error::LengthOverflow)
69}
70
71pub(crate) fn checked_plaintext_len(ciphertext_len: usize) -> Result<usize, Error> {
72 ciphertext_len
73 .checked_sub(SEAL_OVERHEAD)
74 .ok_or(Error::CiphertextTooShort)
75}
76
77#[cfg(test)]
78mod tests {
79 use super::{Error, SEAL_OVERHEAD, checked_plaintext_len, checked_seal_len};
80
81 #[test]
82 fn checked_seal_length_accepts_exact_boundary() {
83 let largest_plaintext = match usize::MAX.checked_sub(SEAL_OVERHEAD) {
84 Some(length) => length,
85 None => return,
86 };
87 assert_eq!(checked_seal_len(0), Ok(SEAL_OVERHEAD));
88 assert_eq!(checked_seal_len(largest_plaintext), Ok(usize::MAX));
89 }
90
91 #[test]
92 fn checked_seal_length_rejects_overflow() {
93 let first_overflow = match usize::MAX
94 .checked_sub(SEAL_OVERHEAD)
95 .and_then(|length| length.checked_add(1))
96 {
97 Some(length) => length,
98 None => return,
99 };
100 assert_eq!(checked_seal_len(first_overflow), Err(Error::LengthOverflow));
101 assert_eq!(checked_seal_len(usize::MAX), Err(Error::LengthOverflow));
102 }
103
104 #[test]
105 fn checked_plaintext_length_rejects_every_short_ciphertext() {
106 for ciphertext_len in 0..SEAL_OVERHEAD {
107 assert_eq!(
108 checked_plaintext_len(ciphertext_len),
109 Err(Error::CiphertextTooShort)
110 );
111 }
112 }
113
114 #[test]
115 fn checked_plaintext_length_accepts_minimum_and_larger_inputs() {
116 let largest_plaintext = match usize::MAX.checked_sub(SEAL_OVERHEAD) {
117 Some(length) => length,
118 None => return,
119 };
120 assert_eq!(checked_plaintext_len(SEAL_OVERHEAD), Ok(0));
121 assert_eq!(checked_plaintext_len(usize::MAX), Ok(largest_plaintext));
122 }
123}