Skip to main content

ascon/
lib.rs

1//! Byte-oriented Ascon algorithms from NIST SP 800-232 (August 2025).
2//!
3//! All operations use caller-owned buffers and work without allocation. Disable
4//! default features for `no_std`. See [`Aead128`], [`Hash256`], [`Xof128`], and
5//! [`Cxof128`]. Nonces must never repeat under the same encryption key.
6//!
7//! ```
8//! use ascon::{Aead128, hash256};
9//! let cipher = Aead128::new(&[7; 16]);
10//! let nonce = [1; 16]; // Use a unique nonce for every encryption with this key.
11//! let mut message = *b"hello";
12//! let tag = cipher.encrypt_in_place(&nonce, b"metadata", &mut message);
13//! cipher.decrypt_in_place(&nonce, b"metadata", &mut message, &tag)?;
14//! assert_eq!(&message, b"hello");
15//! assert_eq!(hash256(&message).len(), 32);
16//! # Ok::<(), ascon::Error>(())
17//! ```
18
19#![cfg_attr(not(feature = "std"), no_std)]
20#![forbid(unsafe_code)]
21#![warn(missing_docs)]
22
23mod aead;
24mod hash;
25mod permutation;
26
27pub use aead::{Aead128, KEY_SIZE, NONCE_SIZE, TAG_SIZE};
28pub use hash::{cxof128, hash256, xof128, Cxof128, Hash256, Xof128, XofReader};
29
30/// Errors from the public cryptographic API.
31#[derive(Clone, Copy, Debug, Eq, PartialEq)]
32pub enum Error {
33    /// Authentication failed; the output buffer has not been modified.
34    AuthenticationFailed,
35    /// Input and output lengths differ.
36    InvalidLength,
37    /// CXOF customization exceeds 256 bytes (2048 bits).
38    CustomizationTooLong,
39}
40
41impl core::fmt::Display for Error {
42    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
43        f.write_str(match self {
44            Self::AuthenticationFailed => "authentication failed",
45            Self::InvalidLength => "input and output lengths differ",
46            Self::CustomizationTooLong => "customization exceeds 256 bytes",
47        })
48    }
49}
50
51#[cfg(feature = "std")]
52impl std::error::Error for Error {}