crypto_box

crypto_box is a pure Rust implementation of NaCl’s crypto_box construction, providing public-key authenticated encryption by combining X25519 Diffie-Hellman key agreement with the XSalsa20Poly1305 (or ChaCha20Poly1305) authenticated cipher into an Elliptic Curve Integrated Encryption Scheme (ECIES).

Part of the RustCrypto nacl-compat workspace, it is a #![no_std] crate that has undergone an independent Cure53 security audit, and offers both SalsaBox and ChaChaBox constructions, sealed-box anonymous encryption, and in-place buffer APIs for allocation-free environments.

What You Get

• SalsaBox and ChaChaBox authenticated encryption schemes compatible with libsodium’s crypto_box
• X25519 key agreement via curve25519-dalek with automatic scalar clamping
• Sealed-box (crypto_box_seal) anonymous encryption via PublicKey::seal and SecretKey::unseal
• no_std support with optional alloc/heapless features for embedded and constrained environments
• Optional serde support for hex/binary key serialization behind a feature flag

Common Use Cases

• Encrypting messages between two parties who exchange public keys, such as secure messaging apps
• Interop with libsodium/NaCl-based systems that need a pure-Rust implementation
• Anonymous sender encryption to a known recipient using sealed boxes
• Embedded/no_std cryptographic applications needing authenticated public-key encryption

Under The Hood

Architecture: The crate’s core type is a generic CryptoBox<C> (src/lib.rs) parameterized over a stream cipher C implementing Kdf + KeyIvInit + KeySizeUser + StreamCipher; the SalsaBox = CryptoBox<Salsa20> and ChaChaBox = CryptoBox<ChaCha20Legacy> type aliases select the concrete cipher via Cargo features. CryptoBox::new performs X25519 Diffie-Hellman (MontgomeryPoint::mul_clamped) between a PublicKey (src/public_key.rs, wrapping curve25519_dalek::MontgomeryPoint) and SecretKey (src/secret_key.rs, wrapping a raw 32-byte array plus a pre-computed clamped Scalar), derives a uniform key via the cipher’s Kdf::kdf (HChaCha20/HSalsa20), and wraps the result in a crypto_secretbox::SecretBox<C> that implements the actual AEAD operations, delegating detached in-place encrypt/decrypt straight through to that inner box. Sealed-box support (PublicKey::seal / SecretKey::unseal, gated behind the seal feature) layers an ephemeral SalsaBox on top: it generates a throwaway keypair, derives a nonce by BLAKE2b-hashing the ephemeral and recipient public keys, and prepends the ephemeral public key to the ciphertext so the recipient can reconstruct the box.

Tech Stack: Rust 2021 edition, MSRV 1.85, #![no_std] by default. Core deps are aead 0.6.0-rc.2 for the Aead/AeadCore/AeadInOut trait surface, curve25519-dalek 5.0.0-pre.1 for the X25519 Montgomery-ladder arithmetic and Scalar clamping, the sibling crypto_secretbox crate (pinned via a workspace path dependency) for the underlying XSalsa20/ChaCha20-Poly1305 cipher and Kdf trait, subtle for constant-time equality, and zeroize for wiping key material on drop. Optional deps gated by features: chacha20/salsa20 (the two supported stream ciphers), blake2 (seal only), and serdect (constant-time-aware serde support). The crate is currently on a 0.10.0-pre.0 pre-release tracking matching -pre/-rc versions of its sibling crates across the workspace.

Code Quality: A small, focused surface — three source files totaling under 700 lines (lib.rs 359, secret_key.rs 203, public_key.rs 134) plus a 200+ line integration test file built from ported PHP Sodium Compat test vectors (hardcoded Alice/Bob keypairs, nonce, and plaintext verified against known ciphertexts) and a unit test covering PublicKey::from_slice boundary lengths. Fallible constructors return Result<_, TryFromSliceError> rather than panicking, and AEAD operations return aead::Result. SecretKey has a hand-rolled Drop impl that zeroizes its Scalar, Debug is manually implemented via finish_non_exhaustive() to avoid leaking key bytes, and PartialEq for SecretKey is constant-time via subtle::ConstantTimeEq. The crate enables #![warn(missing_docs, rust_2018_idioms)] and every public item is documented, including explicit warning callouts on methods that expose raw key bytes. The crate has had one independent Cure53 security audit (2022, on v0.7.1) with no significant findings.

API Design: The lib.rs doc comment doubles as the crate’s rustdoc landing page and includes full compiling usage examples for both SalsaBox and ChaChaBox, showing the complete Alice/Bob key-exchange-then-encrypt/decrypt flow in roughly 20 lines. PublicKey/SecretKey expose matching from_bytes/from_slice/as_bytes/to_bytes constructors and From/TryFrom conversions, and encryption itself is exposed through the standard RustCrypto aead::Aead trait, so callers already familiar with other AEAD crates (aes-gcm, chacha20poly1305) get a zero-boilerplate encrypt()/decrypt() call. The generic CryptoBox<C> design lets SalsaBox and ChaChaBox share their entire implementation while remaining distinct types, and feature flags (alloc, std, heapless, serde, seal) let consumers opt into exactly the capabilities and allocation model they need for no_std targets.