Skip to main content

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}