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 {}