Feat: Implement ASCON Lightweight Cryptographic Libraries

.gitignore

@@ -5,3 +5,5 @@ mutants.out*/
 
 .idea/
 .vscode/
+
+.claude/*

Cargo.toml

@@ -9,6 +9,7 @@ version = "0.1.3"
 
 # *** Internal Dependencies ***
 bouncycastle = { path = "./" }
+bouncycastle-ascon = { path = "./crypto/ascon" }
 bouncycastle-base64 = { path = "./crypto/base64" }
 bouncycastle-core = { path = "crypto/core" }
 bouncycastle-core-test-framework = { path = "./crypto/core-test-framework" }
@@ -41,6 +42,7 @@ version.workspace = true
 edition.workspace = true
 
 [dependencies]
+bouncycastle-ascon.workspace = true
 bouncycastle-base64.workspace = true
 bouncycastle-core.workspace = true
 bouncycastle-factory.workspace = true

cli/src/ascon_cmd.rs

@@ -0,0 +1,152 @@
+use std::io::{Read, Write};
+use std::process::exit;
+use std::{fs, io};
+
+use bouncycastle::ascon::ascon_aead128::AsconAead128;
+use bouncycastle::ascon::ascon_cxof128::AsconCXof128;
+use bouncycastle::ascon::ascon_hash256::AsconHash256;
+use bouncycastle::ascon::ascon_xof128::AsconXof128;
+use bouncycastle::core::traits::{Hash, XOF};
+use bouncycastle::hex;
+
+/// Write `data` to stdout, either as hex or raw binary, followed by a newline.
+fn emit(data: &[u8], output_hex: bool) {
+ if output_hex {
+ for b in data.iter() {
+ print!("{b:02x}");
+ }
+ } else {
+ io::stdout().write_all(data).unwrap();
+ }
+ println!();
+}
+
+/// Read all of stdin into a Vec.
+fn read_stdin() -> Vec<u8> {
+ let mut data = Vec::new();
+ io::stdin().read_to_end(&mut data).expect("Failed to read from stdin");
+ data
+}
+
+/// Load a hex string or a binary file into bytes; exits with an error if neither is supplied.
+fn load_bytes(value: &Option<String>, value_file: &Option<String>, label: &str) -> Vec<u8> {
+ if let Some(file) = value_file {
+ fs::read(file).unwrap_or_else(|e| {
+ eprintln!("Error: failed to read {label} file: {e}");
+ exit(-1)
+ })
+ } else if let Some(v) = value {
+ hex::decode(v).unwrap_or_else(|_| {
+ eprintln!("Error: {label} is not valid hex.");
+ exit(-1)
+ })
+ } else {
+ eprintln!("Error: {label} must be supplied.");
+ exit(-1)
+ }
+}
+
+fn require_16(bytes: Vec<u8>, label: &str) -> [u8; 16] {
+ bytes.try_into().unwrap_or_else(|_: Vec<u8>| {
+ eprintln!("Error: {label} must be exactly 16 bytes.");
+ exit(-1)
+ })
+}
+
+/// Ascon-Hash256 of stdin. Streaming update; 256-bit digest.
+pub(crate) fn hash256_cmd(output_hex: bool) {
+ let mut h = AsconHash256::new();
+ let mut buf = [0u8; 1024];
+ let mut bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ while bytes_read != 0 {
+ h.do_update(&buf[..bytes_read]);
+ bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ }
+ let out = h.do_final();
+ emit(&out, output_hex);
+}
+
+/// Ascon-XOF128 of stdin, producing `output_len` bytes. Streaming absorb.
+pub(crate) fn xof128_cmd(output_len: usize, output_hex: bool) {
+ let mut x = AsconXof128::new();
+ let mut buf = [0u8; 1024];
+ let mut bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ while bytes_read != 0 {
+ // Absorb cannot fail here: we only absorb before any squeeze.
+ x.absorb(&buf[..bytes_read]).expect("absorb before squeeze is infallible");
+ bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ }
+ let out = x.squeeze(output_len);
+ emit(&out, output_hex);
+}
+
+/// Ascon-CXOF128 of stdin with a hex customization string, producing `output_len` bytes.
+pub(crate) fn cxof128_cmd(customization: &Option<String>, output_len: usize, output_hex: bool) {
+ let z = match customization {
+ Some(v) => hex::decode(v).unwrap_or_else(|_| {
+ eprintln!("Error: customization is not valid hex.");
+ exit(-1)
+ }),
+ None => Vec::new(),
+ };
+ let mut x = AsconCXof128::with_customization(&z);
+ let mut buf = [0u8; 1024];
+ let mut bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ while bytes_read != 0 {
+ // Absorb cannot fail here: we only absorb before any squeeze.
+ x.absorb(&buf[..bytes_read]).expect("absorb before squeeze is infallible");
+ bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ }
+ let out = x.squeeze(output_len);
+ emit(&out, output_hex);
+}
+
+/// Ascon-AEAD128 of stdin. Encrypts (stdin = plaintext, output = ciphertext||tag) or, with
+/// `decrypt`, decrypts (stdin = ciphertext||tag, output = plaintext). Decryption exits with a
+/// non-zero status if the authentication tag does not verify.
+#[allow(clippy::too_many_arguments)]
+pub(crate) fn aead128_cmd(
+ key: &Option<String>,
+ key_file: &Option<String>,
+ nonce: &Option<String>,
+ nonce_file: &Option<String>,
+ ad: &Option<String>,
+ decrypt: bool,
+ output_hex: bool,
+) {
+ let key = require_16(load_bytes(key, key_file, "key"), "key");
+ let nonce = require_16(load_bytes(nonce, nonce_file, "nonce"), "nonce");
+ let ad_bytes = match ad {
+ Some(v) => hex::decode(v).unwrap_or_else(|_| {
+ eprintln!("Error: associated data is not valid hex.");
+ exit(-1)
+ }),
+ None => Vec::new(),
+ };
+ let ad_opt = if ad_bytes.is_empty() { None } else { Some(ad_bytes.as_slice()) };
+
+ let input = read_stdin();
+
+ if decrypt {
+ if input.len() < 16 {
+ eprintln!("Error: ciphertext is shorter than the 16-byte tag.");
+ exit(-1);
+ }
+ let mut out = vec![0u8; input.len() - 16];
+ match AsconAead128::decrypt(&key, &nonce, ad_opt, &input, &mut out) {
+ Ok(n) => {
+ out.truncate(n);
+ emit(&out, output_hex);
+ }
+ Err(_) => {
+ eprintln!("Error: Ascon-AEAD128 authentication failed.");
+ exit(-1);
+ }
+ }
+ } else {
+ let mut out = vec![0u8; input.len() + 16];
+ let n = AsconAead128::encrypt(&key, &nonce, ad_opt, &input, &mut out);
+ out.truncate(n);
+ emit(&out, output_hex);
+ }
+}

cli/src/main.rs

@@ -1,3 +1,4 @@
+mod ascon_cmd;
 mod encoders_cmd;
 mod helpers;
 mod hkdf_cmd;
@@ -124,6 +125,76 @@ enum Subcommands {
  x: bool,
  },
 
+ /// Perform Ascon-Hash256 of the content provided on stdin.
+ /// Supports streaming update for low memory footprint.
+ AsconHash256 {
+ #[arg(short)]
+ /// Output the digest in hex format.
+ x: bool,
+ },
+
+ /// Perform Ascon-XOF128 of the content provided on stdin. Requires the output length in bytes.
+ /// Supports streaming update for low memory footprint.
+ AsconXOF128 {
+ /// Length of the output in bytes.
+ length: usize,
+
+ #[arg(short)]
+ /// Output in hex format.
+ x: bool,
+ },
+
+ /// Perform Ascon-CXOF128 of the content provided on stdin. Requires the output length in bytes.
+ /// Supports streaming update for low memory footprint.
+ AsconCXOF128 {
+ /// Length of the output in bytes.
+ length: usize,
+
+ /// Customization string in hex (optional).
+ #[arg(long)]
+ customization: Option<String>,
+
+ #[arg(short)]
+ /// Output in hex format.
+ x: bool,
+ },
+
+ /// Ascon-AEAD128 authenticated encryption/decryption of the content provided on stdin.
+ /// Encrypts by default (stdin = plaintext, output = ciphertext||tag); with --decrypt the
+ /// reverse. Decryption fails with a non-zero exit status if the tag does not verify.
+ /// Note: in production uses, secrets should not be passed on the command-line because they get
+ /// logged in shell history. Use the file-based input instead.
+ AsconAEAD128 {
+ /// The 128-bit key in hex.
+ /// The `key_file` option is preferred to avoid leaving key material in command history.
+ #[arg(long)]
+ key: Option<String>,
+
+ /// A file containing the 128-bit key in binary.
+ #[arg(long)]
+ key_file: Option<String>,
+
+ /// The 128-bit nonce in hex. Must be unique per encryption under a given key.
+ #[arg(long)]
+ nonce: Option<String>,
+
+ /// A file containing the 128-bit nonce in binary.
+ #[arg(long)]
+ nonce_file: Option<String>,
+
+ /// Associated data in hex (authenticated but not encrypted).
+ #[arg(long)]
+ ad: Option<String>,
+
+ /// Decrypt instead of encrypt.
+ #[arg(short, long)]
+ decrypt: bool,
+
+ #[arg(short)]
+ /// Output in hex format.
+ x: bool,
+ },
+
  /// Perform HMAC-SHA256 of the content provided on stdin.
  /// Supports streaming update for low memory footprint.
  /// Note: in production uses, secrets should not be passed on the command-line because they get
@@ -531,6 +602,18 @@ fn main() {
  Some(Subcommands::SHAKE256 { length, x }) => {
  sha3_cmd::shake_cmd(256, *length, *x);
  }
+ Some(Subcommands::AsconHash256 { x }) => {
+ ascon_cmd::hash256_cmd(*x);
+ }
+ Some(Subcommands::AsconXOF128 { length, x }) => {
+ ascon_cmd::xof128_cmd(*length, *x);
+ }
+ Some(Subcommands::AsconCXOF128 { length, customization, x }) => {
+ ascon_cmd::cxof128_cmd(customization, *length, *x);
+ }
+ Some(Subcommands::AsconAEAD128 { key, key_file, nonce, nonce_file, ad, decrypt, x }) => {
+ ascon_cmd::aead128_cmd(key, key_file, nonce, nonce_file, ad, *decrypt, *x);
+ }
  Some(Subcommands::HMAC_SHA256 { key, key_file, verify, x }) => {
  mac_cmd::mac_cmd(HMACVariant::SHA256, key, key_file, verify, *x)
  }

crypto/ascon/Cargo.toml

@@ -0,0 +1,27 @@
+[package]
+name = "bouncycastle-ascon"
+version.workspace = true
+edition.workspace = true
+
+[features]
+# `std` gates the ergonomic, allocating (`Vec`-returning) one-shot cipher APIs, mirroring the
+# `std` feature of `bouncycastle-core`. On by default; a future `--no-default-features` build is
+# what will let the crate move toward `#![no_std]`.
+default = ["std"]
+std = ["bouncycastle-core/std"]
+
+[dependencies]
+bouncycastle-core.workspace = true
+bouncycastle-rng.workspace = true
+bouncycastle-utils.workspace = true
+
+[dev-dependencies]
+bouncycastle-core-test-framework.workspace = true
+bouncycastle-hex.workspace = true
+bouncycastle-rng.workspace = true
+criterion.workspace = true
+serde_json = "1.0" # todo -- why?
+
+[[bench]]
+name = "ascon_benches"
+harness = false

crypto/ascon/benches/ascon_benches.rs

@@ -0,0 +1,90 @@
+use bouncycastle_rng as rng;
+use criterion::{Criterion, Throughput, criterion_group, criterion_main};
+use std::hint::black_box;
+
+use bouncycastle_ascon::ascon_aead128::AsconAead128;
+use bouncycastle_ascon::ascon_cxof128::AsconCXof128;
+use bouncycastle_ascon::ascon_hash256::AsconHash256;
+use bouncycastle_ascon::ascon_xof128::AsconXof128;
+use bouncycastle_core::traits::{Hash, RNG, XOF};
+
+const DATA_LEN: usize = 16 * 1024;
+
+fn random_data(len: usize) -> Vec<u8> {
+ let mut data = vec![0u8; len];
+ rng::DefaultRNG::default().next_bytes_out(&mut data).unwrap();
+ data
+}
+
+fn bench_aead128_encrypt(c: &mut Criterion) {
+ let key = [0x42u8; 16];
+ let nonce = [0x24u8; 16];
+ let data = random_data(DATA_LEN);
+ let mut out = vec![0u8; DATA_LEN + 16];
+
+ let mut group = c.benchmark_group("ascon::AsconAead128");
+ group.throughput(Throughput::Bytes(DATA_LEN as u64));
+ group.bench_function(format!("{DATA_LEN} bytes -- ::encrypt()"), |b| {
+ b.iter(|| {
+ AsconAead128::encrypt(&key, &nonce, None, black_box(&data), &mut out);
+ black_box(&out);
+ })
+ });
+ group.finish();
+}
+
+fn bench_hash256(c: &mut Criterion) {
+ let data = random_data(DATA_LEN);
+ let mut digest = [0u8; 32];
+
+ let mut group = c.benchmark_group("ascon::AsconHash256");
+ group.throughput(Throughput::Bytes(DATA_LEN as u64));
+ group.bench_function(format!("{DATA_LEN} bytes -- ::hash_out()"), |b| {
+ b.iter(|| {
+ AsconHash256::new().hash_out(black_box(&data), &mut digest);
+ black_box(&digest);
+ })
+ });
+ group.finish();
+}
+
+fn bench_xof128(c: &mut Criterion) {
+ let data = random_data(DATA_LEN);
+ let mut out = [0u8; 64];
+
+ let mut group = c.benchmark_group("ascon::AsconXof128");
+ group.throughput(Throughput::Bytes((DATA_LEN + out.len()) as u64));
+ group.bench_function(
+ format!("input: {DATA_LEN} bytes, output: 64 bytes -- ::hash_xof_out()"),
+ |b| {
+ b.iter(|| {
+ AsconXof128::new().hash_xof_out(black_box(&data), &mut out);
+ black_box(&out);
+ })
+ },
+ );
+ group.finish();
+}
+
+fn bench_cxof128(c: &mut Criterion) {
+ let data = random_data(DATA_LEN);
+ let customization = b"bench-customization";
+ let mut out = [0u8; 64];
+
+ let mut group = c.benchmark_group("ascon::AsconCXof128");
+ group.throughput(Throughput::Bytes((DATA_LEN + out.len()) as u64));
+ group.bench_function(
+ format!("input: {DATA_LEN} bytes, output: 64 bytes -- ::hash_xof_out()"),
+ |b| {
+ b.iter(|| {
+ AsconCXof128::with_customization(customization)
+ .hash_xof_out(black_box(&data), &mut out);
+ black_box(&out);
+ })
+ },
+ );
+ group.finish();
+}
+
+criterion_group!(benches, bench_aead128_encrypt, bench_hash256, bench_xof128, bench_cxof128);
+criterion_main!(benches);

.gitignore

@@ -5,3 +5,5 @@ mutants.out*/
 
 .idea/
 .vscode/
+
+.claude/*

Cargo.toml

@@ -9,6 +9,7 @@ version = "0.1.3"
 
 # *** Internal Dependencies ***
 bouncycastle = { path = "./" }
+bouncycastle-ascon = { path = "./crypto/ascon" }
 bouncycastle-base64 = { path = "./crypto/base64" }
 bouncycastle-core = { path = "crypto/core" }
 bouncycastle-core-test-framework = { path = "./crypto/core-test-framework" }
@@ -41,6 +42,7 @@ version.workspace = true
 edition.workspace = true
 
 [dependencies]
+bouncycastle-ascon.workspace = true
 bouncycastle-base64.workspace = true
 bouncycastle-core.workspace = true
 bouncycastle-factory.workspace = true

cli/src/ascon_cmd.rs

@@ -0,0 +1,152 @@
+use std::io::{Read, Write};
+use std::process::exit;
+use std::{fs, io};
+
+use bouncycastle::ascon::ascon_aead128::AsconAead128;
+use bouncycastle::ascon::ascon_cxof128::AsconCXof128;
+use bouncycastle::ascon::ascon_hash256::AsconHash256;
+use bouncycastle::ascon::ascon_xof128::AsconXof128;
+use bouncycastle::core::traits::{Hash, XOF};
+use bouncycastle::hex;
+
+/// Write `data` to stdout, either as hex or raw binary, followed by a newline.
+fn emit(data: &[u8], output_hex: bool) {
+ if output_hex {
+ for b in data.iter() {
+ print!("{b:02x}");
+ }
+ } else {
+ io::stdout().write_all(data).unwrap();
+ }
+ println!();
+}
+
+/// Read all of stdin into a Vec.
+fn read_stdin() -> Vec<u8> {
+ let mut data = Vec::new();
+ io::stdin().read_to_end(&mut data).expect("Failed to read from stdin");
+ data
+}
+
+/// Load a hex string or a binary file into bytes; exits with an error if neither is supplied.
+fn load_bytes(value: &Option<String>, value_file: &Option<String>, label: &str) -> Vec<u8> {
+ if let Some(file) = value_file {
+ fs::read(file).unwrap_or_else(|e| {
+ eprintln!("Error: failed to read {label} file: {e}");
+ exit(-1)
+ })
+ } else if let Some(v) = value {
+ hex::decode(v).unwrap_or_else(|_| {
+ eprintln!("Error: {label} is not valid hex.");
+ exit(-1)
+ })
+ } else {
+ eprintln!("Error: {label} must be supplied.");
+ exit(-1)
+ }
+}
+
+fn require_16(bytes: Vec<u8>, label: &str) -> [u8; 16] {
+ bytes.try_into().unwrap_or_else(|_: Vec<u8>| {
+ eprintln!("Error: {label} must be exactly 16 bytes.");
+ exit(-1)
+ })
+}
+
+/// Ascon-Hash256 of stdin. Streaming update; 256-bit digest.
+pub(crate) fn hash256_cmd(output_hex: bool) {
+ let mut h = AsconHash256::new();
+ let mut buf = [0u8; 1024];
+ let mut bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ while bytes_read != 0 {
+ h.do_update(&buf[..bytes_read]);
+ bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ }
+ let out = h.do_final();
+ emit(&out, output_hex);
+}
+
+/// Ascon-XOF128 of stdin, producing `output_len` bytes. Streaming absorb.
+pub(crate) fn xof128_cmd(output_len: usize, output_hex: bool) {
+ let mut x = AsconXof128::new();
+ let mut buf = [0u8; 1024];
+ let mut bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ while bytes_read != 0 {
+ // Absorb cannot fail here: we only absorb before any squeeze.
+ x.absorb(&buf[..bytes_read]).expect("absorb before squeeze is infallible");
+ bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ }
+ let out = x.squeeze(output_len);
+ emit(&out, output_hex);
+}
+
+/// Ascon-CXOF128 of stdin with a hex customization string, producing `output_len` bytes.
+pub(crate) fn cxof128_cmd(customization: &Option<String>, output_len: usize, output_hex: bool) {
+ let z = match customization {
+ Some(v) => hex::decode(v).unwrap_or_else(|_| {
+ eprintln!("Error: customization is not valid hex.");
+ exit(-1)
+ }),
+ None => Vec::new(),
+ };
+ let mut x = AsconCXof128::with_customization(&z);
+ let mut buf = [0u8; 1024];
+ let mut bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ while bytes_read != 0 {
+ // Absorb cannot fail here: we only absorb before any squeeze.
+ x.absorb(&buf[..bytes_read]).expect("absorb before squeeze is infallible");
+ bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ }
+ let out = x.squeeze(output_len);
+ emit(&out, output_hex);
+}
+
+/// Ascon-AEAD128 of stdin. Encrypts (stdin = plaintext, output = ciphertext||tag) or, with
+/// `decrypt`, decrypts (stdin = ciphertext||tag, output = plaintext). Decryption exits with a
+/// non-zero status if the authentication tag does not verify.
+#[allow(clippy::too_many_arguments)]
+pub(crate) fn aead128_cmd(
+ key: &Option<String>,
+ key_file: &Option<String>,
+ nonce: &Option<String>,
+ nonce_file: &Option<String>,
+ ad: &Option<String>,
+ decrypt: bool,
+ output_hex: bool,
+) {
+ let key = require_16(load_bytes(key, key_file, "key"), "key");
+ let nonce = require_16(load_bytes(nonce, nonce_file, "nonce"), "nonce");
+ let ad_bytes = match ad {
+ Some(v) => hex::decode(v).unwrap_or_else(|_| {
+ eprintln!("Error: associated data is not valid hex.");
+ exit(-1)
+ }),
+ None => Vec::new(),
+ };
+ let ad_opt = if ad_bytes.is_empty() { None } else { Some(ad_bytes.as_slice()) };
+
+ let input = read_stdin();
+
+ if decrypt {
+ if input.len() < 16 {
+ eprintln!("Error: ciphertext is shorter than the 16-byte tag.");
+ exit(-1);
+ }
+ let mut out = vec![0u8; input.len() - 16];
+ match AsconAead128::decrypt(&key, &nonce, ad_opt, &input, &mut out) {
+ Ok(n) => {
+ out.truncate(n);
+ emit(&out, output_hex);
+ }
+ Err(_) => {
+ eprintln!("Error: Ascon-AEAD128 authentication failed.");
+ exit(-1);
+ }
+ }
+ } else {
+ let mut out = vec![0u8; input.len() + 16];
+ let n = AsconAead128::encrypt(&key, &nonce, ad_opt, &input, &mut out);
+ out.truncate(n);
+ emit(&out, output_hex);
+ }
+}

cli/src/main.rs

@@ -1,3 +1,4 @@
+mod ascon_cmd;
 mod encoders_cmd;
 mod helpers;
 mod hkdf_cmd;
@@ -124,6 +125,76 @@ enum Subcommands {
  x: bool,
  },
 
+ /// Perform Ascon-Hash256 of the content provided on stdin.
+ /// Supports streaming update for low memory footprint.
+ AsconHash256 {
+ #[arg(short)]
+ /// Output the digest in hex format.
+ x: bool,
+ },
+
+ /// Perform Ascon-XOF128 of the content provided on stdin. Requires the output length in bytes.
+ /// Supports streaming update for low memory footprint.
+ AsconXOF128 {
+ /// Length of the output in bytes.
+ length: usize,
+
+ #[arg(short)]
+ /// Output in hex format.
+ x: bool,
+ },
+
+ /// Perform Ascon-CXOF128 of the content provided on stdin. Requires the output length in bytes.
+ /// Supports streaming update for low memory footprint.
+ AsconCXOF128 {
+ /// Length of the output in bytes.
+ length: usize,
+
+ /// Customization string in hex (optional).
+ #[arg(long)]
+ customization: Option<String>,
+
+ #[arg(short)]
+ /// Output in hex format.
+ x: bool,
+ },
+
+ /// Ascon-AEAD128 authenticated encryption/decryption of the content provided on stdin.
+ /// Encrypts by default (stdin = plaintext, output = ciphertext||tag); with --decrypt the
+ /// reverse. Decryption fails with a non-zero exit status if the tag does not verify.
+ /// Note: in production uses, secrets should not be passed on the command-line because they get
+ /// logged in shell history. Use the file-based input instead.
+ AsconAEAD128 {
+ /// The 128-bit key in hex.
+ /// The `key_file` option is preferred to avoid leaving key material in command history.
+ #[arg(long)]
+ key: Option<String>,
+
+ /// A file containing the 128-bit key in binary.
+ #[arg(long)]
+ key_file: Option<String>,
+
+ /// The 128-bit nonce in hex. Must be unique per encryption under a given key.
+ #[arg(long)]
+ nonce: Option<String>,
+
+ /// A file containing the 128-bit nonce in binary.
+ #[arg(long)]
+ nonce_file: Option<String>,
+
+ /// Associated data in hex (authenticated but not encrypted).
+ #[arg(long)]
+ ad: Option<String>,
+
+ /// Decrypt instead of encrypt.
+ #[arg(short, long)]
+ decrypt: bool,
+
+ #[arg(short)]
+ /// Output in hex format.
+ x: bool,
+ },
+
  /// Perform HMAC-SHA256 of the content provided on stdin.
  /// Supports streaming update for low memory footprint.
  /// Note: in production uses, secrets should not be passed on the command-line because they get
@@ -531,6 +602,18 @@ fn main() {
  Some(Subcommands::SHAKE256 { length, x }) => {
  sha3_cmd::shake_cmd(256, *length, *x);
  }
+ Some(Subcommands::AsconHash256 { x }) => {
+ ascon_cmd::hash256_cmd(*x);
+ }
+ Some(Subcommands::AsconXOF128 { length, x }) => {
+ ascon_cmd::xof128_cmd(*length, *x);
+ }
+ Some(Subcommands::AsconCXOF128 { length, customization, x }) => {
+ ascon_cmd::cxof128_cmd(customization, *length, *x);
+ }
+ Some(Subcommands::AsconAEAD128 { key, key_file, nonce, nonce_file, ad, decrypt, x }) => {
+ ascon_cmd::aead128_cmd(key, key_file, nonce, nonce_file, ad, *decrypt, *x);
+ }
  Some(Subcommands::HMAC_SHA256 { key, key_file, verify, x }) => {
  mac_cmd::mac_cmd(HMACVariant::SHA256, key, key_file, verify, *x)
  }

crypto/ascon/Cargo.toml

@@ -0,0 +1,27 @@
+[package]
+name = "bouncycastle-ascon"
+version.workspace = true
+edition.workspace = true
+
+[features]
+# `std` gates the ergonomic, allocating (`Vec`-returning) one-shot cipher APIs, mirroring the
+# `std` feature of `bouncycastle-core`. On by default; a future `--no-default-features` build is
+# what will let the crate move toward `#![no_std]`.
+default = ["std"]
+std = ["bouncycastle-core/std"]
+
+[dependencies]
+bouncycastle-core.workspace = true
+bouncycastle-rng.workspace = true
+bouncycastle-utils.workspace = true
+
+[dev-dependencies]
+bouncycastle-core-test-framework.workspace = true
+bouncycastle-hex.workspace = true
+bouncycastle-rng.workspace = true
+criterion.workspace = true
+serde_json = "1.0" # todo -- why?
+
+[[bench]]
+name = "ascon_benches"
+harness = false

crypto/ascon/benches/ascon_benches.rs

@@ -0,0 +1,90 @@
+use bouncycastle_rng as rng;
+use criterion::{Criterion, Throughput, criterion_group, criterion_main};
+use std::hint::black_box;
+
+use bouncycastle_ascon::ascon_aead128::AsconAead128;
+use bouncycastle_ascon::ascon_cxof128::AsconCXof128;
+use bouncycastle_ascon::ascon_hash256::AsconHash256;
+use bouncycastle_ascon::ascon_xof128::AsconXof128;
+use bouncycastle_core::traits::{Hash, RNG, XOF};
+
+const DATA_LEN: usize = 16 * 1024;
+
+fn random_data(len: usize) -> Vec<u8> {
+ let mut data = vec![0u8; len];
+ rng::DefaultRNG::default().next_bytes_out(&mut data).unwrap();
+ data
+}
+
+fn bench_aead128_encrypt(c: &mut Criterion) {
+ let key = [0x42u8; 16];
+ let nonce = [0x24u8; 16];
+ let data = random_data(DATA_LEN);
+ let mut out = vec![0u8; DATA_LEN + 16];
+
+ let mut group = c.benchmark_group("ascon::AsconAead128");
+ group.throughput(Throughput::Bytes(DATA_LEN as u64));
+ group.bench_function(format!("{DATA_LEN} bytes -- ::encrypt()"), |b| {
+ b.iter(|| {
+ AsconAead128::encrypt(&key, &nonce, None, black_box(&data), &mut out);
+ black_box(&out);
+ })
+ });
+ group.finish();
+}
+
+fn bench_hash256(c: &mut Criterion) {
+ let data = random_data(DATA_LEN);
+ let mut digest = [0u8; 32];
+
+ let mut group = c.benchmark_group("ascon::AsconHash256");
+ group.throughput(Throughput::Bytes(DATA_LEN as u64));
+ group.bench_function(format!("{DATA_LEN} bytes -- ::hash_out()"), |b| {
+ b.iter(|| {
+ AsconHash256::new().hash_out(black_box(&data), &mut digest);
+ black_box(&digest);
+ })
+ });
+ group.finish();
+}
+
+fn bench_xof128(c: &mut Criterion) {
+ let data = random_data(DATA_LEN);
+ let mut out = [0u8; 64];
+
+ let mut group = c.benchmark_group("ascon::AsconXof128");
+ group.throughput(Throughput::Bytes((DATA_LEN + out.len()) as u64));
+ group.bench_function(
+ format!("input: {DATA_LEN} bytes, output: 64 bytes -- ::hash_xof_out()"),
+ |b| {
+ b.iter(|| {
+ AsconXof128::new().hash_xof_out(black_box(&data), &mut out);
+ black_box(&out);
+ })
+ },
+ );
+ group.finish();
+}
+
+fn bench_cxof128(c: &mut Criterion) {
+ let data = random_data(DATA_LEN);
+ let customization = b"bench-customization";
+ let mut out = [0u8; 64];
+
+ let mut group = c.benchmark_group("ascon::AsconCXof128");
+ group.throughput(Throughput::Bytes((DATA_LEN + out.len()) as u64));
+ group.bench_function(
+ format!("input: {DATA_LEN} bytes, output: 64 bytes -- ::hash_xof_out()"),
+ |b| {
+ b.iter(|| {
+ AsconCXof128::with_customization(customization)
+ .hash_xof_out(black_box(&data), &mut out);
+ black_box(&out);
+ })
+ },
+ );
+ group.finish();
+}
+
+criterion_group!(benches, bench_aead128_encrypt, bench_hash256, bench_xof128, bench_cxof128);
+criterion_main!(benches);

.gitignore

@@ -5,3 +5,5 @@ mutants.out*/
 
 .idea/
 .vscode/
+
+.claude/*

Cargo.toml

@@ -9,6 +9,7 @@ version = "0.1.3"
 
 # *** Internal Dependencies ***
 bouncycastle = { path = "./" }
+bouncycastle-ascon = { path = "./crypto/ascon" }
 bouncycastle-base64 = { path = "./crypto/base64" }
 bouncycastle-core = { path = "crypto/core" }
 bouncycastle-core-test-framework = { path = "./crypto/core-test-framework" }
@@ -41,6 +42,7 @@ version.workspace = true
 edition.workspace = true
 
 [dependencies]
+bouncycastle-ascon.workspace = true
 bouncycastle-base64.workspace = true
 bouncycastle-core.workspace = true
 bouncycastle-factory.workspace = true

cli/src/ascon_cmd.rs

@@ -0,0 +1,152 @@
+use std::io::{Read, Write};
+use std::process::exit;
+use std::{fs, io};
+
+use bouncycastle::ascon::ascon_aead128::AsconAead128;
+use bouncycastle::ascon::ascon_cxof128::AsconCXof128;
+use bouncycastle::ascon::ascon_hash256::AsconHash256;
+use bouncycastle::ascon::ascon_xof128::AsconXof128;
+use bouncycastle::core::traits::{Hash, XOF};
+use bouncycastle::hex;
+
+/// Write `data` to stdout, either as hex or raw binary, followed by a newline.
+fn emit(data: &[u8], output_hex: bool) {
+ if output_hex {
+ for b in data.iter() {
+ print!("{b:02x}");
+ }
+ } else {
+ io::stdout().write_all(data).unwrap();
+ }
+ println!();
+}
+
+/// Read all of stdin into a Vec.
+fn read_stdin() -> Vec<u8> {
+ let mut data = Vec::new();
+ io::stdin().read_to_end(&mut data).expect("Failed to read from stdin");
+ data
+}
+
+/// Load a hex string or a binary file into bytes; exits with an error if neither is supplied.
+fn load_bytes(value: &Option<String>, value_file: &Option<String>, label: &str) -> Vec<u8> {
+ if let Some(file) = value_file {
+ fs::read(file).unwrap_or_else(|e| {
+ eprintln!("Error: failed to read {label} file: {e}");
+ exit(-1)
+ })
+ } else if let Some(v) = value {
+ hex::decode(v).unwrap_or_else(|_| {
+ eprintln!("Error: {label} is not valid hex.");
+ exit(-1)
+ })
+ } else {
+ eprintln!("Error: {label} must be supplied.");
+ exit(-1)
+ }
+}
+
+fn require_16(bytes: Vec<u8>, label: &str) -> [u8; 16] {
+ bytes.try_into().unwrap_or_else(|_: Vec<u8>| {
+ eprintln!("Error: {label} must be exactly 16 bytes.");
+ exit(-1)
+ })
+}
+
+/// Ascon-Hash256 of stdin. Streaming update; 256-bit digest.
+pub(crate) fn hash256_cmd(output_hex: bool) {
+ let mut h = AsconHash256::new();
+ let mut buf = [0u8; 1024];
+ let mut bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ while bytes_read != 0 {
+ h.do_update(&buf[..bytes_read]);
+ bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ }
+ let out = h.do_final();
+ emit(&out, output_hex);
+}
+
+/// Ascon-XOF128 of stdin, producing `output_len` bytes. Streaming absorb.
+pub(crate) fn xof128_cmd(output_len: usize, output_hex: bool) {
+ let mut x = AsconXof128::new();
+ let mut buf = [0u8; 1024];
+ let mut bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ while bytes_read != 0 {
+ // Absorb cannot fail here: we only absorb before any squeeze.
+ x.absorb(&buf[..bytes_read]).expect("absorb before squeeze is infallible");
+ bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ }
+ let out = x.squeeze(output_len);
+ emit(&out, output_hex);
+}
+
+/// Ascon-CXOF128 of stdin with a hex customization string, producing `output_len` bytes.
+pub(crate) fn cxof128_cmd(customization: &Option<String>, output_len: usize, output_hex: bool) {
+ let z = match customization {
+ Some(v) => hex::decode(v).unwrap_or_else(|_| {
+ eprintln!("Error: customization is not valid hex.");
+ exit(-1)
+ }),
+ None => Vec::new(),
+ };
+ let mut x = AsconCXof128::with_customization(&z);
+ let mut buf = [0u8; 1024];
+ let mut bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ while bytes_read != 0 {
+ // Absorb cannot fail here: we only absorb before any squeeze.
+ x.absorb(&buf[..bytes_read]).expect("absorb before squeeze is infallible");
+ bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ }
+ let out = x.squeeze(output_len);
+ emit(&out, output_hex);
+}
+
+/// Ascon-AEAD128 of stdin. Encrypts (stdin = plaintext, output = ciphertext||tag) or, with
+/// `decrypt`, decrypts (stdin = ciphertext||tag, output = plaintext). Decryption exits with a
+/// non-zero status if the authentication tag does not verify.
+#[allow(clippy::too_many_arguments)]
+pub(crate) fn aead128_cmd(
+ key: &Option<String>,
+ key_file: &Option<String>,
+ nonce: &Option<String>,
+ nonce_file: &Option<String>,
+ ad: &Option<String>,
+ decrypt: bool,
+ output_hex: bool,
+) {
+ let key = require_16(load_bytes(key, key_file, "key"), "key");
+ let nonce = require_16(load_bytes(nonce, nonce_file, "nonce"), "nonce");
+ let ad_bytes = match ad {
+ Some(v) => hex::decode(v).unwrap_or_else(|_| {
+ eprintln!("Error: associated data is not valid hex.");
+ exit(-1)
+ }),
+ None => Vec::new(),
+ };
+ let ad_opt = if ad_bytes.is_empty() { None } else { Some(ad_bytes.as_slice()) };
+
+ let input = read_stdin();
+
+ if decrypt {
+ if input.len() < 16 {
+ eprintln!("Error: ciphertext is shorter than the 16-byte tag.");
+ exit(-1);
+ }
+ let mut out = vec![0u8; input.len() - 16];
+ match AsconAead128::decrypt(&key, &nonce, ad_opt, &input, &mut out) {
+ Ok(n) => {
+ out.truncate(n);
+ emit(&out, output_hex);
+ }
+ Err(_) => {
+ eprintln!("Error: Ascon-AEAD128 authentication failed.");
+ exit(-1);
+ }
+ }
+ } else {
+ let mut out = vec![0u8; input.len() + 16];
+ let n = AsconAead128::encrypt(&key, &nonce, ad_opt, &input, &mut out);
+ out.truncate(n);
+ emit(&out, output_hex);
+ }
+}

cli/src/main.rs

@@ -1,3 +1,4 @@
+mod ascon_cmd;
 mod encoders_cmd;
 mod helpers;
 mod hkdf_cmd;
@@ -124,6 +125,76 @@ enum Subcommands {
  x: bool,
  },
 
+ /// Perform Ascon-Hash256 of the content provided on stdin.
+ /// Supports streaming update for low memory footprint.
+ AsconHash256 {
+ #[arg(short)]
+ /// Output the digest in hex format.
+ x: bool,
+ },
+
+ /// Perform Ascon-XOF128 of the content provided on stdin. Requires the output length in bytes.
+ /// Supports streaming update for low memory footprint.
+ AsconXOF128 {
+ /// Length of the output in bytes.
+ length: usize,
+
+ #[arg(short)]
+ /// Output in hex format.
+ x: bool,
+ },
+
+ /// Perform Ascon-CXOF128 of the content provided on stdin. Requires the output length in bytes.
+ /// Supports streaming update for low memory footprint.
+ AsconCXOF128 {
+ /// Length of the output in bytes.
+ length: usize,
+
+ /// Customization string in hex (optional).
+ #[arg(long)]
+ customization: Option<String>,
+
+ #[arg(short)]
+ /// Output in hex format.
+ x: bool,
+ },
+
+ /// Ascon-AEAD128 authenticated encryption/decryption of the content provided on stdin.
+ /// Encrypts by default (stdin = plaintext, output = ciphertext||tag); with --decrypt the
+ /// reverse. Decryption fails with a non-zero exit status if the tag does not verify.
+ /// Note: in production uses, secrets should not be passed on the command-line because they get
+ /// logged in shell history. Use the file-based input instead.
+ AsconAEAD128 {
+ /// The 128-bit key in hex.
+ /// The `key_file` option is preferred to avoid leaving key material in command history.
+ #[arg(long)]
+ key: Option<String>,
+
+ /// A file containing the 128-bit key in binary.
+ #[arg(long)]
+ key_file: Option<String>,
+
+ /// The 128-bit nonce in hex. Must be unique per encryption under a given key.
+ #[arg(long)]
+ nonce: Option<String>,
+
+ /// A file containing the 128-bit nonce in binary.
+ #[arg(long)]
+ nonce_file: Option<String>,
+
+ /// Associated data in hex (authenticated but not encrypted).
+ #[arg(long)]
+ ad: Option<String>,
+
+ /// Decrypt instead of encrypt.
+ #[arg(short, long)]
+ decrypt: bool,
+
+ #[arg(short)]
+ /// Output in hex format.
+ x: bool,
+ },
+
  /// Perform HMAC-SHA256 of the content provided on stdin.
  /// Supports streaming update for low memory footprint.
  /// Note: in production uses, secrets should not be passed on the command-line because they get
@@ -531,6 +602,18 @@ fn main() {
  Some(Subcommands::SHAKE256 { length, x }) => {
  sha3_cmd::shake_cmd(256, *length, *x);
  }
+ Some(Subcommands::AsconHash256 { x }) => {
+ ascon_cmd::hash256_cmd(*x);
+ }
+ Some(Subcommands::AsconXOF128 { length, x }) => {
+ ascon_cmd::xof128_cmd(*length, *x);
+ }
+ Some(Subcommands::AsconCXOF128 { length, customization, x }) => {
+ ascon_cmd::cxof128_cmd(customization, *length, *x);
+ }
+ Some(Subcommands::AsconAEAD128 { key, key_file, nonce, nonce_file, ad, decrypt, x }) => {
+ ascon_cmd::aead128_cmd(key, key_file, nonce, nonce_file, ad, *decrypt, *x);
+ }
  Some(Subcommands::HMAC_SHA256 { key, key_file, verify, x }) => {
  mac_cmd::mac_cmd(HMACVariant::SHA256, key, key_file, verify, *x)
  }

crypto/ascon/Cargo.toml

@@ -0,0 +1,27 @@
+[package]
+name = "bouncycastle-ascon"
+version.workspace = true
+edition.workspace = true
+
+[features]
+# `std` gates the ergonomic, allocating (`Vec`-returning) one-shot cipher APIs, mirroring the
+# `std` feature of `bouncycastle-core`. On by default; a future `--no-default-features` build is
+# what will let the crate move toward `#![no_std]`.
+default = ["std"]
+std = ["bouncycastle-core/std"]
+
+[dependencies]
+bouncycastle-core.workspace = true
+bouncycastle-rng.workspace = true
+bouncycastle-utils.workspace = true
+
+[dev-dependencies]
+bouncycastle-core-test-framework.workspace = true
+bouncycastle-hex.workspace = true
+bouncycastle-rng.workspace = true
+criterion.workspace = true
+serde_json = "1.0" # todo -- why?
+
+[[bench]]
+name = "ascon_benches"
+harness = false

crypto/ascon/benches/ascon_benches.rs

@@ -0,0 +1,90 @@
+use bouncycastle_rng as rng;
+use criterion::{Criterion, Throughput, criterion_group, criterion_main};
+use std::hint::black_box;
+
+use bouncycastle_ascon::ascon_aead128::AsconAead128;
+use bouncycastle_ascon::ascon_cxof128::AsconCXof128;
+use bouncycastle_ascon::ascon_hash256::AsconHash256;
+use bouncycastle_ascon::ascon_xof128::AsconXof128;
+use bouncycastle_core::traits::{Hash, RNG, XOF};
+
+const DATA_LEN: usize = 16 * 1024;
+
+fn random_data(len: usize) -> Vec<u8> {
+ let mut data = vec![0u8; len];
+ rng::DefaultRNG::default().next_bytes_out(&mut data).unwrap();
+ data
+}
+
+fn bench_aead128_encrypt(c: &mut Criterion) {
+ let key = [0x42u8; 16];
+ let nonce = [0x24u8; 16];
+ let data = random_data(DATA_LEN);
+ let mut out = vec![0u8; DATA_LEN + 16];
+
+ let mut group = c.benchmark_group("ascon::AsconAead128");
+ group.throughput(Throughput::Bytes(DATA_LEN as u64));
+ group.bench_function(format!("{DATA_LEN} bytes -- ::encrypt()"), |b| {
+ b.iter(|| {
+ AsconAead128::encrypt(&key, &nonce, None, black_box(&data), &mut out);
+ black_box(&out);
+ })
+ });
+ group.finish();
+}
+
+fn bench_hash256(c: &mut Criterion) {
+ let data = random_data(DATA_LEN);
+ let mut digest = [0u8; 32];
+
+ let mut group = c.benchmark_group("ascon::AsconHash256");
+ group.throughput(Throughput::Bytes(DATA_LEN as u64));
+ group.bench_function(format!("{DATA_LEN} bytes -- ::hash_out()"), |b| {
+ b.iter(|| {
+ AsconHash256::new().hash_out(black_box(&data), &mut digest);
+ black_box(&digest);
+ })
+ });
+ group.finish();
+}
+
+fn bench_xof128(c: &mut Criterion) {
+ let data = random_data(DATA_LEN);
+ let mut out = [0u8; 64];
+
+ let mut group = c.benchmark_group("ascon::AsconXof128");
+ group.throughput(Throughput::Bytes((DATA_LEN + out.len()) as u64));
+ group.bench_function(
+ format!("input: {DATA_LEN} bytes, output: 64 bytes -- ::hash_xof_out()"),
+ |b| {
+ b.iter(|| {
+ AsconXof128::new().hash_xof_out(black_box(&data), &mut out);
+ black_box(&out);
+ })
+ },
+ );
+ group.finish();
+}
+
+fn bench_cxof128(c: &mut Criterion) {
+ let data = random_data(DATA_LEN);
+ let customization = b"bench-customization";
+ let mut out = [0u8; 64];
+
+ let mut group = c.benchmark_group("ascon::AsconCXof128");
+ group.throughput(Throughput::Bytes((DATA_LEN + out.len()) as u64));
+ group.bench_function(
+ format!("input: {DATA_LEN} bytes, output: 64 bytes -- ::hash_xof_out()"),
+ |b| {
+ b.iter(|| {
+ AsconCXof128::with_customization(customization)
+ .hash_xof_out(black_box(&data), &mut out);
+ black_box(&out);
+ })
+ },
+ );
+ group.finish();
+}
+
+criterion_group!(benches, bench_aead128_encrypt, bench_hash256, bench_xof128, bench_cxof128);
+criterion_main!(benches);

.gitignore

@@ -5,3 +5,5 @@ mutants.out*/
 
 .idea/
 .vscode/
+
+.claude/*

Cargo.toml

@@ -9,6 +9,7 @@ version = "0.1.3"
 
 # *** Internal Dependencies ***
 bouncycastle = { path = "./" }
+bouncycastle-ascon = { path = "./crypto/ascon" }
 bouncycastle-base64 = { path = "./crypto/base64" }
 bouncycastle-core = { path = "crypto/core" }
 bouncycastle-core-test-framework = { path = "./crypto/core-test-framework" }
@@ -41,6 +42,7 @@ version.workspace = true
 edition.workspace = true
 
 [dependencies]
+bouncycastle-ascon.workspace = true
 bouncycastle-base64.workspace = true
 bouncycastle-core.workspace = true
 bouncycastle-factory.workspace = true

cli/src/ascon_cmd.rs

@@ -0,0 +1,152 @@
+use std::io::{Read, Write};
+use std::process::exit;
+use std::{fs, io};
+
+use bouncycastle::ascon::ascon_aead128::AsconAead128;
+use bouncycastle::ascon::ascon_cxof128::AsconCXof128;
+use bouncycastle::ascon::ascon_hash256::AsconHash256;
+use bouncycastle::ascon::ascon_xof128::AsconXof128;
+use bouncycastle::core::traits::{Hash, XOF};
+use bouncycastle::hex;
+
+/// Write `data` to stdout, either as hex or raw binary, followed by a newline.
+fn emit(data: &[u8], output_hex: bool) {
+ if output_hex {
+ for b in data.iter() {
+ print!("{b:02x}");
+ }
+ } else {
+ io::stdout().write_all(data).unwrap();
+ }
+ println!();
+}
+
+/// Read all of stdin into a Vec.
+fn read_stdin() -> Vec<u8> {
+ let mut data = Vec::new();
+ io::stdin().read_to_end(&mut data).expect("Failed to read from stdin");
+ data
+}
+
+/// Load a hex string or a binary file into bytes; exits with an error if neither is supplied.
+fn load_bytes(value: &Option<String>, value_file: &Option<String>, label: &str) -> Vec<u8> {
+ if let Some(file) = value_file {
+ fs::read(file).unwrap_or_else(|e| {
+ eprintln!("Error: failed to read {label} file: {e}");
+ exit(-1)
+ })
+ } else if let Some(v) = value {
+ hex::decode(v).unwrap_or_else(|_| {
+ eprintln!("Error: {label} is not valid hex.");
+ exit(-1)
+ })
+ } else {
+ eprintln!("Error: {label} must be supplied.");
+ exit(-1)
+ }
+}
+
+fn require_16(bytes: Vec<u8>, label: &str) -> [u8; 16] {
+ bytes.try_into().unwrap_or_else(|_: Vec<u8>| {
+ eprintln!("Error: {label} must be exactly 16 bytes.");
+ exit(-1)
+ })
+}
+
+/// Ascon-Hash256 of stdin. Streaming update; 256-bit digest.
+pub(crate) fn hash256_cmd(output_hex: bool) {
+ let mut h = AsconHash256::new();
+ let mut buf = [0u8; 1024];
+ let mut bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ while bytes_read != 0 {
+ h.do_update(&buf[..bytes_read]);
+ bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ }
+ let out = h.do_final();
+ emit(&out, output_hex);
+}
+
+/// Ascon-XOF128 of stdin, producing `output_len` bytes. Streaming absorb.
+pub(crate) fn xof128_cmd(output_len: usize, output_hex: bool) {
+ let mut x = AsconXof128::new();
+ let mut buf = [0u8; 1024];
+ let mut bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ while bytes_read != 0 {
+ // Absorb cannot fail here: we only absorb before any squeeze.
+ x.absorb(&buf[..bytes_read]).expect("absorb before squeeze is infallible");
+ bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ }
+ let out = x.squeeze(output_len);
+ emit(&out, output_hex);
+}
+
+/// Ascon-CXOF128 of stdin with a hex customization string, producing `output_len` bytes.
+pub(crate) fn cxof128_cmd(customization: &Option<String>, output_len: usize, output_hex: bool) {
+ let z = match customization {
+ Some(v) => hex::decode(v).unwrap_or_else(|_| {
+ eprintln!("Error: customization is not valid hex.");
+ exit(-1)
+ }),
+ None => Vec::new(),
+ };
+ let mut x = AsconCXof128::with_customization(&z);
+ let mut buf = [0u8; 1024];
+ let mut bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ while bytes_read != 0 {
+ // Absorb cannot fail here: we only absorb before any squeeze.
+ x.absorb(&buf[..bytes_read]).expect("absorb before squeeze is infallible");
+ bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ }
+ let out = x.squeeze(output_len);
+ emit(&out, output_hex);
+}
+
+/// Ascon-AEAD128 of stdin. Encrypts (stdin = plaintext, output = ciphertext||tag) or, with
+/// `decrypt`, decrypts (stdin = ciphertext||tag, output = plaintext). Decryption exits with a
+/// non-zero status if the authentication tag does not verify.
+#[allow(clippy::too_many_arguments)]
+pub(crate) fn aead128_cmd(
+ key: &Option<String>,
+ key_file: &Option<String>,
+ nonce: &Option<String>,
+ nonce_file: &Option<String>,
+ ad: &Option<String>,
+ decrypt: bool,
+ output_hex: bool,
+) {
+ let key = require_16(load_bytes(key, key_file, "key"), "key");
+ let nonce = require_16(load_bytes(nonce, nonce_file, "nonce"), "nonce");
+ let ad_bytes = match ad {
+ Some(v) => hex::decode(v).unwrap_or_else(|_| {
+ eprintln!("Error: associated data is not valid hex.");
+ exit(-1)
+ }),
+ None => Vec::new(),
+ };
+ let ad_opt = if ad_bytes.is_empty() { None } else { Some(ad_bytes.as_slice()) };
+
+ let input = read_stdin();
+
+ if decrypt {
+ if input.len() < 16 {
+ eprintln!("Error: ciphertext is shorter than the 16-byte tag.");
+ exit(-1);
+ }
+ let mut out = vec![0u8; input.len() - 16];
+ match AsconAead128::decrypt(&key, &nonce, ad_opt, &input, &mut out) {
+ Ok(n) => {
+ out.truncate(n);
+ emit(&out, output_hex);
+ }
+ Err(_) => {
+ eprintln!("Error: Ascon-AEAD128 authentication failed.");
+ exit(-1);
+ }
+ }
+ } else {
+ let mut out = vec![0u8; input.len() + 16];
+ let n = AsconAead128::encrypt(&key, &nonce, ad_opt, &input, &mut out);
+ out.truncate(n);
+ emit(&out, output_hex);
+ }
+}

cli/src/main.rs

@@ -1,3 +1,4 @@
+mod ascon_cmd;
 mod encoders_cmd;
 mod helpers;
 mod hkdf_cmd;
@@ -124,6 +125,76 @@ enum Subcommands {
  x: bool,
  },
 
+ /// Perform Ascon-Hash256 of the content provided on stdin.
+ /// Supports streaming update for low memory footprint.
+ AsconHash256 {
+ #[arg(short)]
+ /// Output the digest in hex format.
+ x: bool,
+ },
+
+ /// Perform Ascon-XOF128 of the content provided on stdin. Requires the output length in bytes.
+ /// Supports streaming update for low memory footprint.
+ AsconXOF128 {
+ /// Length of the output in bytes.
+ length: usize,
+
+ #[arg(short)]
+ /// Output in hex format.
+ x: bool,
+ },
+
+ /// Perform Ascon-CXOF128 of the content provided on stdin. Requires the output length in bytes.
+ /// Supports streaming update for low memory footprint.
+ AsconCXOF128 {
+ /// Length of the output in bytes.
+ length: usize,
+
+ /// Customization string in hex (optional).
+ #[arg(long)]
+ customization: Option<String>,
+
+ #[arg(short)]
+ /// Output in hex format.
+ x: bool,
+ },
+
+ /// Ascon-AEAD128 authenticated encryption/decryption of the content provided on stdin.
+ /// Encrypts by default (stdin = plaintext, output = ciphertext||tag); with --decrypt the
+ /// reverse. Decryption fails with a non-zero exit status if the tag does not verify.
+ /// Note: in production uses, secrets should not be passed on the command-line because they get
+ /// logged in shell history. Use the file-based input instead.
+ AsconAEAD128 {
+ /// The 128-bit key in hex.
+ /// The `key_file` option is preferred to avoid leaving key material in command history.
+ #[arg(long)]
+ key: Option<String>,
+
+ /// A file containing the 128-bit key in binary.
+ #[arg(long)]
+ key_file: Option<String>,
+
+ /// The 128-bit nonce in hex. Must be unique per encryption under a given key.
+ #[arg(long)]
+ nonce: Option<String>,
+
+ /// A file containing the 128-bit nonce in binary.
+ #[arg(long)]
+ nonce_file: Option<String>,
+
+ /// Associated data in hex (authenticated but not encrypted).
+ #[arg(long)]
+ ad: Option<String>,
+
+ /// Decrypt instead of encrypt.
+ #[arg(short, long)]
+ decrypt: bool,
+
+ #[arg(short)]
+ /// Output in hex format.
+ x: bool,
+ },
+
  /// Perform HMAC-SHA256 of the content provided on stdin.
  /// Supports streaming update for low memory footprint.
  /// Note: in production uses, secrets should not be passed on the command-line because they get
@@ -531,6 +602,18 @@ fn main() {
  Some(Subcommands::SHAKE256 { length, x }) => {
  sha3_cmd::shake_cmd(256, *length, *x);
  }
+ Some(Subcommands::AsconHash256 { x }) => {
+ ascon_cmd::hash256_cmd(*x);
+ }
+ Some(Subcommands::AsconXOF128 { length, x }) => {
+ ascon_cmd::xof128_cmd(*length, *x);
+ }
+ Some(Subcommands::AsconCXOF128 { length, customization, x }) => {
+ ascon_cmd::cxof128_cmd(customization, *length, *x);
+ }
+ Some(Subcommands::AsconAEAD128 { key, key_file, nonce, nonce_file, ad, decrypt, x }) => {
+ ascon_cmd::aead128_cmd(key, key_file, nonce, nonce_file, ad, *decrypt, *x);
+ }
  Some(Subcommands::HMAC_SHA256 { key, key_file, verify, x }) => {
  mac_cmd::mac_cmd(HMACVariant::SHA256, key, key_file, verify, *x)
  }

crypto/ascon/Cargo.toml

@@ -0,0 +1,27 @@
+[package]
+name = "bouncycastle-ascon"
+version.workspace = true
+edition.workspace = true
+
+[features]
+# `std` gates the ergonomic, allocating (`Vec`-returning) one-shot cipher APIs, mirroring the
+# `std` feature of `bouncycastle-core`. On by default; a future `--no-default-features` build is
+# what will let the crate move toward `#![no_std]`.
+default = ["std"]
+std = ["bouncycastle-core/std"]
+
+[dependencies]
+bouncycastle-core.workspace = true
+bouncycastle-rng.workspace = true
+bouncycastle-utils.workspace = true
+
+[dev-dependencies]
+bouncycastle-core-test-framework.workspace = true
+bouncycastle-hex.workspace = true
+bouncycastle-rng.workspace = true
+criterion.workspace = true
+serde_json = "1.0" # todo -- why?
+
+[[bench]]
+name = "ascon_benches"
+harness = false

crypto/ascon/benches/ascon_benches.rs

@@ -0,0 +1,90 @@
+use bouncycastle_rng as rng;
+use criterion::{Criterion, Throughput, criterion_group, criterion_main};
+use std::hint::black_box;
+
+use bouncycastle_ascon::ascon_aead128::AsconAead128;
+use bouncycastle_ascon::ascon_cxof128::AsconCXof128;
+use bouncycastle_ascon::ascon_hash256::AsconHash256;
+use bouncycastle_ascon::ascon_xof128::AsconXof128;
+use bouncycastle_core::traits::{Hash, RNG, XOF};
+
+const DATA_LEN: usize = 16 * 1024;
+
+fn random_data(len: usize) -> Vec<u8> {
+ let mut data = vec![0u8; len];
+ rng::DefaultRNG::default().next_bytes_out(&mut data).unwrap();
+ data
+}
+
+fn bench_aead128_encrypt(c: &mut Criterion) {
+ let key = [0x42u8; 16];
+ let nonce = [0x24u8; 16];
+ let data = random_data(DATA_LEN);
+ let mut out = vec![0u8; DATA_LEN + 16];
+
+ let mut group = c.benchmark_group("ascon::AsconAead128");
+ group.throughput(Throughput::Bytes(DATA_LEN as u64));
+ group.bench_function(format!("{DATA_LEN} bytes -- ::encrypt()"), |b| {
+ b.iter(|| {
+ AsconAead128::encrypt(&key, &nonce, None, black_box(&data), &mut out);
+ black_box(&out);
+ })
+ });
+ group.finish();
+}
+
+fn bench_hash256(c: &mut Criterion) {
+ let data = random_data(DATA_LEN);
+ let mut digest = [0u8; 32];
+
+ let mut group = c.benchmark_group("ascon::AsconHash256");
+ group.throughput(Throughput::Bytes(DATA_LEN as u64));
+ group.bench_function(format!("{DATA_LEN} bytes -- ::hash_out()"), |b| {
+ b.iter(|| {
+ AsconHash256::new().hash_out(black_box(&data), &mut digest);
+ black_box(&digest);
+ })
+ });
+ group.finish();
+}
+
+fn bench_xof128(c: &mut Criterion) {
+ let data = random_data(DATA_LEN);
+ let mut out = [0u8; 64];
+
+ let mut group = c.benchmark_group("ascon::AsconXof128");
+ group.throughput(Throughput::Bytes((DATA_LEN + out.len()) as u64));
+ group.bench_function(
+ format!("input: {DATA_LEN} bytes, output: 64 bytes -- ::hash_xof_out()"),
+ |b| {
+ b.iter(|| {
+ AsconXof128::new().hash_xof_out(black_box(&data), &mut out);
+ black_box(&out);
+ })
+ },
+ );
+ group.finish();
+}
+
+fn bench_cxof128(c: &mut Criterion) {
+ let data = random_data(DATA_LEN);
+ let customization = b"bench-customization";
+ let mut out = [0u8; 64];
+
+ let mut group = c.benchmark_group("ascon::AsconCXof128");
+ group.throughput(Throughput::Bytes((DATA_LEN + out.len()) as u64));
+ group.bench_function(
+ format!("input: {DATA_LEN} bytes, output: 64 bytes -- ::hash_xof_out()"),
+ |b| {
+ b.iter(|| {
+ AsconCXof128::with_customization(customization)
+ .hash_xof_out(black_box(&data), &mut out);
+ black_box(&out);
+ })
+ },
+ );
+ group.finish();
+}
+
+criterion_group!(benches, bench_aead128_encrypt, bench_hash256, bench_xof128, bench_cxof128);
+criterion_main!(benches);

.gitignore

@@ -5,3 +5,5 @@ mutants.out*/
 
 .idea/
 .vscode/
+
+.claude/*

Cargo.toml

@@ -9,6 +9,7 @@ version = "0.1.3"
 
 # *** Internal Dependencies ***
 bouncycastle = { path = "./" }
+bouncycastle-ascon = { path = "./crypto/ascon" }
 bouncycastle-base64 = { path = "./crypto/base64" }
 bouncycastle-core = { path = "crypto/core" }
 bouncycastle-core-test-framework = { path = "./crypto/core-test-framework" }
@@ -41,6 +42,7 @@ version.workspace = true
 edition.workspace = true
 
 [dependencies]
+bouncycastle-ascon.workspace = true
 bouncycastle-base64.workspace = true
 bouncycastle-core.workspace = true
 bouncycastle-factory.workspace = true

cli/src/ascon_cmd.rs

@@ -0,0 +1,152 @@
+use std::io::{Read, Write};
+use std::process::exit;
+use std::{fs, io};
+
+use bouncycastle::ascon::ascon_aead128::AsconAead128;
+use bouncycastle::ascon::ascon_cxof128::AsconCXof128;
+use bouncycastle::ascon::ascon_hash256::AsconHash256;
+use bouncycastle::ascon::ascon_xof128::AsconXof128;
+use bouncycastle::core::traits::{Hash, XOF};
+use bouncycastle::hex;
+
+/// Write `data` to stdout, either as hex or raw binary, followed by a newline.
+fn emit(data: &[u8], output_hex: bool) {
+ if output_hex {
+ for b in data.iter() {
+ print!("{b:02x}");
+ }
+ } else {
+ io::stdout().write_all(data).unwrap();
+ }
+ println!();
+}
+
+/// Read all of stdin into a Vec.
+fn read_stdin() -> Vec<u8> {
+ let mut data = Vec::new();
+ io::stdin().read_to_end(&mut data).expect("Failed to read from stdin");
+ data
+}
+
+/// Load a hex string or a binary file into bytes; exits with an error if neither is supplied.
+fn load_bytes(value: &Option<String>, value_file: &Option<String>, label: &str) -> Vec<u8> {
+ if let Some(file) = value_file {
+ fs::read(file).unwrap_or_else(|e| {
+ eprintln!("Error: failed to read {label} file: {e}");
+ exit(-1)
+ })
+ } else if let Some(v) = value {
+ hex::decode(v).unwrap_or_else(|_| {
+ eprintln!("Error: {label} is not valid hex.");
+ exit(-1)
+ })
+ } else {
+ eprintln!("Error: {label} must be supplied.");
+ exit(-1)
+ }
+}
+
+fn require_16(bytes: Vec<u8>, label: &str) -> [u8; 16] {
+ bytes.try_into().unwrap_or_else(|_: Vec<u8>| {
+ eprintln!("Error: {label} must be exactly 16 bytes.");
+ exit(-1)
+ })
+}
+
+/// Ascon-Hash256 of stdin. Streaming update; 256-bit digest.
+pub(crate) fn hash256_cmd(output_hex: bool) {
+ let mut h = AsconHash256::new();
+ let mut buf = [0u8; 1024];
+ let mut bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ while bytes_read != 0 {
+ h.do_update(&buf[..bytes_read]);
+ bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ }
+ let out = h.do_final();
+ emit(&out, output_hex);
+}
+
+/// Ascon-XOF128 of stdin, producing `output_len` bytes. Streaming absorb.
+pub(crate) fn xof128_cmd(output_len: usize, output_hex: bool) {
+ let mut x = AsconXof128::new();
+ let mut buf = [0u8; 1024];
+ let mut bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ while bytes_read != 0 {
+ // Absorb cannot fail here: we only absorb before any squeeze.
+ x.absorb(&buf[..bytes_read]).expect("absorb before squeeze is infallible");
+ bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ }
+ let out = x.squeeze(output_len);
+ emit(&out, output_hex);
+}
+
+/// Ascon-CXOF128 of stdin with a hex customization string, producing `output_len` bytes.
+pub(crate) fn cxof128_cmd(customization: &Option<String>, output_len: usize, output_hex: bool) {
+ let z = match customization {
+ Some(v) => hex::decode(v).unwrap_or_else(|_| {
+ eprintln!("Error: customization is not valid hex.");
+ exit(-1)
+ }),
+ None => Vec::new(),
+ };
+ let mut x = AsconCXof128::with_customization(&z);
+ let mut buf = [0u8; 1024];
+ let mut bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ while bytes_read != 0 {
+ // Absorb cannot fail here: we only absorb before any squeeze.
+ x.absorb(&buf[..bytes_read]).expect("absorb before squeeze is infallible");
+ bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ }
+ let out = x.squeeze(output_len);
+ emit(&out, output_hex);
+}
+
+/// Ascon-AEAD128 of stdin. Encrypts (stdin = plaintext, output = ciphertext||tag) or, with
+/// `decrypt`, decrypts (stdin = ciphertext||tag, output = plaintext). Decryption exits with a
+/// non-zero status if the authentication tag does not verify.
+#[allow(clippy::too_many_arguments)]
+pub(crate) fn aead128_cmd(
+ key: &Option<String>,
+ key_file: &Option<String>,
+ nonce: &Option<String>,
+ nonce_file: &Option<String>,
+ ad: &Option<String>,
+ decrypt: bool,
+ output_hex: bool,
+) {
+ let key = require_16(load_bytes(key, key_file, "key"), "key");
+ let nonce = require_16(load_bytes(nonce, nonce_file, "nonce"), "nonce");
+ let ad_bytes = match ad {
+ Some(v) => hex::decode(v).unwrap_or_else(|_| {
+ eprintln!("Error: associated data is not valid hex.");
+ exit(-1)
+ }),
+ None => Vec::new(),
+ };
+ let ad_opt = if ad_bytes.is_empty() { None } else { Some(ad_bytes.as_slice()) };
+
+ let input = read_stdin();
+
+ if decrypt {
+ if input.len() < 16 {
+ eprintln!("Error: ciphertext is shorter than the 16-byte tag.");
+ exit(-1);
+ }
+ let mut out = vec![0u8; input.len() - 16];
+ match AsconAead128::decrypt(&key, &nonce, ad_opt, &input, &mut out) {
+ Ok(n) => {
+ out.truncate(n);
+ emit(&out, output_hex);
+ }
+ Err(_) => {
+ eprintln!("Error: Ascon-AEAD128 authentication failed.");
+ exit(-1);
+ }
+ }
+ } else {
+ let mut out = vec![0u8; input.len() + 16];
+ let n = AsconAead128::encrypt(&key, &nonce, ad_opt, &input, &mut out);
+ out.truncate(n);
+ emit(&out, output_hex);
+ }
+}

cli/src/main.rs

@@ -1,3 +1,4 @@
+mod ascon_cmd;
 mod encoders_cmd;
 mod helpers;
 mod hkdf_cmd;
@@ -124,6 +125,76 @@ enum Subcommands {
  x: bool,
  },
 
+ /// Perform Ascon-Hash256 of the content provided on stdin.
+ /// Supports streaming update for low memory footprint.
+ AsconHash256 {
+ #[arg(short)]
+ /// Output the digest in hex format.
+ x: bool,
+ },
+
+ /// Perform Ascon-XOF128 of the content provided on stdin. Requires the output length in bytes.
+ /// Supports streaming update for low memory footprint.
+ AsconXOF128 {
+ /// Length of the output in bytes.
+ length: usize,
+
+ #[arg(short)]
+ /// Output in hex format.
+ x: bool,
+ },
+
+ /// Perform Ascon-CXOF128 of the content provided on stdin. Requires the output length in bytes.
+ /// Supports streaming update for low memory footprint.
+ AsconCXOF128 {
+ /// Length of the output in bytes.
+ length: usize,
+
+ /// Customization string in hex (optional).
+ #[arg(long)]
+ customization: Option<String>,
+
+ #[arg(short)]
+ /// Output in hex format.
+ x: bool,
+ },
+
+ /// Ascon-AEAD128 authenticated encryption/decryption of the content provided on stdin.
+ /// Encrypts by default (stdin = plaintext, output = ciphertext||tag); with --decrypt the
+ /// reverse. Decryption fails with a non-zero exit status if the tag does not verify.
+ /// Note: in production uses, secrets should not be passed on the command-line because they get
+ /// logged in shell history. Use the file-based input instead.
+ AsconAEAD128 {
+ /// The 128-bit key in hex.
+ /// The `key_file` option is preferred to avoid leaving key material in command history.
+ #[arg(long)]
+ key: Option<String>,
+
+ /// A file containing the 128-bit key in binary.
+ #[arg(long)]
+ key_file: Option<String>,
+
+ /// The 128-bit nonce in hex. Must be unique per encryption under a given key.
+ #[arg(long)]
+ nonce: Option<String>,
+
+ /// A file containing the 128-bit nonce in binary.
+ #[arg(long)]
+ nonce_file: Option<String>,
+
+ /// Associated data in hex (authenticated but not encrypted).
+ #[arg(long)]
+ ad: Option<String>,
+
+ /// Decrypt instead of encrypt.
+ #[arg(short, long)]
+ decrypt: bool,
+
+ #[arg(short)]
+ /// Output in hex format.
+ x: bool,
+ },
+
  /// Perform HMAC-SHA256 of the content provided on stdin.
  /// Supports streaming update for low memory footprint.
  /// Note: in production uses, secrets should not be passed on the command-line because they get
@@ -531,6 +602,18 @@ fn main() {
  Some(Subcommands::SHAKE256 { length, x }) => {
  sha3_cmd::shake_cmd(256, *length, *x);
  }
+ Some(Subcommands::AsconHash256 { x }) => {
+ ascon_cmd::hash256_cmd(*x);
+ }
+ Some(Subcommands::AsconXOF128 { length, x }) => {
+ ascon_cmd::xof128_cmd(*length, *x);
+ }
+ Some(Subcommands::AsconCXOF128 { length, customization, x }) => {
+ ascon_cmd::cxof128_cmd(customization, *length, *x);
+ }
+ Some(Subcommands::AsconAEAD128 { key, key_file, nonce, nonce_file, ad, decrypt, x }) => {
+ ascon_cmd::aead128_cmd(key, key_file, nonce, nonce_file, ad, *decrypt, *x);
+ }
  Some(Subcommands::HMAC_SHA256 { key, key_file, verify, x }) => {
  mac_cmd::mac_cmd(HMACVariant::SHA256, key, key_file, verify, *x)
  }

crypto/ascon/Cargo.toml

@@ -0,0 +1,27 @@
+[package]
+name = "bouncycastle-ascon"
+version.workspace = true
+edition.workspace = true
+
+[features]
+# `std` gates the ergonomic, allocating (`Vec`-returning) one-shot cipher APIs, mirroring the
+# `std` feature of `bouncycastle-core`. On by default; a future `--no-default-features` build is
+# what will let the crate move toward `#![no_std]`.
+default = ["std"]
+std = ["bouncycastle-core/std"]
+
+[dependencies]
+bouncycastle-core.workspace = true
+bouncycastle-rng.workspace = true
+bouncycastle-utils.workspace = true
+
+[dev-dependencies]
+bouncycastle-core-test-framework.workspace = true
+bouncycastle-hex.workspace = true
+bouncycastle-rng.workspace = true
+criterion.workspace = true
+serde_json = "1.0" # todo -- why?
+
+[[bench]]
+name = "ascon_benches"
+harness = false

crypto/ascon/benches/ascon_benches.rs

@@ -0,0 +1,90 @@
+use bouncycastle_rng as rng;
+use criterion::{Criterion, Throughput, criterion_group, criterion_main};
+use std::hint::black_box;
+
+use bouncycastle_ascon::ascon_aead128::AsconAead128;
+use bouncycastle_ascon::ascon_cxof128::AsconCXof128;
+use bouncycastle_ascon::ascon_hash256::AsconHash256;
+use bouncycastle_ascon::ascon_xof128::AsconXof128;
+use bouncycastle_core::traits::{Hash, RNG, XOF};
+
+const DATA_LEN: usize = 16 * 1024;
+
+fn random_data(len: usize) -> Vec<u8> {
+ let mut data = vec![0u8; len];
+ rng::DefaultRNG::default().next_bytes_out(&mut data).unwrap();
+ data
+}
+
+fn bench_aead128_encrypt(c: &mut Criterion) {
+ let key = [0x42u8; 16];
+ let nonce = [0x24u8; 16];
+ let data = random_data(DATA_LEN);
+ let mut out = vec![0u8; DATA_LEN + 16];
+
+ let mut group = c.benchmark_group("ascon::AsconAead128");
+ group.throughput(Throughput::Bytes(DATA_LEN as u64));
+ group.bench_function(format!("{DATA_LEN} bytes -- ::encrypt()"), |b| {
+ b.iter(|| {
+ AsconAead128::encrypt(&key, &nonce, None, black_box(&data), &mut out);
+ black_box(&out);
+ })
+ });
+ group.finish();
+}
+
+fn bench_hash256(c: &mut Criterion) {
+ let data = random_data(DATA_LEN);
+ let mut digest = [0u8; 32];
+
+ let mut group = c.benchmark_group("ascon::AsconHash256");
+ group.throughput(Throughput::Bytes(DATA_LEN as u64));
+ group.bench_function(format!("{DATA_LEN} bytes -- ::hash_out()"), |b| {
+ b.iter(|| {
+ AsconHash256::new().hash_out(black_box(&data), &mut digest);
+ black_box(&digest);
+ })
+ });
+ group.finish();
+}
+
+fn bench_xof128(c: &mut Criterion) {
+ let data = random_data(DATA_LEN);
+ let mut out = [0u8; 64];
+
+ let mut group = c.benchmark_group("ascon::AsconXof128");
+ group.throughput(Throughput::Bytes((DATA_LEN + out.len()) as u64));
+ group.bench_function(
+ format!("input: {DATA_LEN} bytes, output: 64 bytes -- ::hash_xof_out()"),
+ |b| {
+ b.iter(|| {
+ AsconXof128::new().hash_xof_out(black_box(&data), &mut out);
+ black_box(&out);
+ })
+ },
+ );
+ group.finish();
+}
+
+fn bench_cxof128(c: &mut Criterion) {
+ let data = random_data(DATA_LEN);
+ let customization = b"bench-customization";
+ let mut out = [0u8; 64];
+
+ let mut group = c.benchmark_group("ascon::AsconCXof128");
+ group.throughput(Throughput::Bytes((DATA_LEN + out.len()) as u64));
+ group.bench_function(
+ format!("input: {DATA_LEN} bytes, output: 64 bytes -- ::hash_xof_out()"),
+ |b| {
+ b.iter(|| {
+ AsconCXof128::with_customization(customization)
+ .hash_xof_out(black_box(&data), &mut out);
+ black_box(&out);
+ })
+ },
+ );
+ group.finish();
+}
+
+criterion_group!(benches, bench_aead128_encrypt, bench_hash256, bench_xof128, bench_cxof128);
+criterion_main!(benches);

.gitignore

@@ -5,3 +5,5 @@ mutants.out*/
 
 .idea/
 .vscode/
+
+.claude/*

Cargo.toml

@@ -9,6 +9,7 @@ version = "0.1.3"
 
 # *** Internal Dependencies ***
 bouncycastle = { path = "./" }
+bouncycastle-ascon = { path = "./crypto/ascon" }
 bouncycastle-base64 = { path = "./crypto/base64" }
 bouncycastle-core = { path = "crypto/core" }
 bouncycastle-core-test-framework = { path = "./crypto/core-test-framework" }
@@ -41,6 +42,7 @@ version.workspace = true
 edition.workspace = true
 
 [dependencies]
+bouncycastle-ascon.workspace = true
 bouncycastle-base64.workspace = true
 bouncycastle-core.workspace = true
 bouncycastle-factory.workspace = true

cli/src/ascon_cmd.rs

@@ -0,0 +1,152 @@
+use std::io::{Read, Write};
+use std::process::exit;
+use std::{fs, io};
+
+use bouncycastle::ascon::ascon_aead128::AsconAead128;
+use bouncycastle::ascon::ascon_cxof128::AsconCXof128;
+use bouncycastle::ascon::ascon_hash256::AsconHash256;
+use bouncycastle::ascon::ascon_xof128::AsconXof128;
+use bouncycastle::core::traits::{Hash, XOF};
+use bouncycastle::hex;
+
+/// Write `data` to stdout, either as hex or raw binary, followed by a newline.
+fn emit(data: &[u8], output_hex: bool) {
+ if output_hex {
+ for b in data.iter() {
+ print!("{b:02x}");
+ }
+ } else {
+ io::stdout().write_all(data).unwrap();
+ }
+ println!();
+}
+
+/// Read all of stdin into a Vec.
+fn read_stdin() -> Vec<u8> {
+ let mut data = Vec::new();
+ io::stdin().read_to_end(&mut data).expect("Failed to read from stdin");
+ data
+}
+
+/// Load a hex string or a binary file into bytes; exits with an error if neither is supplied.
+fn load_bytes(value: &Option<String>, value_file: &Option<String>, label: &str) -> Vec<u8> {
+ if let Some(file) = value_file {
+ fs::read(file).unwrap_or_else(|e| {
+ eprintln!("Error: failed to read {label} file: {e}");
+ exit(-1)
+ })
+ } else if let Some(v) = value {
+ hex::decode(v).unwrap_or_else(|_| {
+ eprintln!("Error: {label} is not valid hex.");
+ exit(-1)
+ })
+ } else {
+ eprintln!("Error: {label} must be supplied.");
+ exit(-1)
+ }
+}
+
+fn require_16(bytes: Vec<u8>, label: &str) -> [u8; 16] {
+ bytes.try_into().unwrap_or_else(|_: Vec<u8>| {
+ eprintln!("Error: {label} must be exactly 16 bytes.");
+ exit(-1)
+ })
+}
+
+/// Ascon-Hash256 of stdin. Streaming update; 256-bit digest.
+pub(crate) fn hash256_cmd(output_hex: bool) {
+ let mut h = AsconHash256::new();
+ let mut buf = [0u8; 1024];
+ let mut bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ while bytes_read != 0 {
+ h.do_update(&buf[..bytes_read]);
+ bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ }
+ let out = h.do_final();
+ emit(&out, output_hex);
+}
+
+/// Ascon-XOF128 of stdin, producing `output_len` bytes. Streaming absorb.
+pub(crate) fn xof128_cmd(output_len: usize, output_hex: bool) {
+ let mut x = AsconXof128::new();
+ let mut buf = [0u8; 1024];
+ let mut bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ while bytes_read != 0 {
+ // Absorb cannot fail here: we only absorb before any squeeze.
+ x.absorb(&buf[..bytes_read]).expect("absorb before squeeze is infallible");
+ bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ }
+ let out = x.squeeze(output_len);
+ emit(&out, output_hex);
+}
+
+/// Ascon-CXOF128 of stdin with a hex customization string, producing `output_len` bytes.
+pub(crate) fn cxof128_cmd(customization: &Option<String>, output_len: usize, output_hex: bool) {
+ let z = match customization {
+ Some(v) => hex::decode(v).unwrap_or_else(|_| {
+ eprintln!("Error: customization is not valid hex.");
+ exit(-1)
+ }),
+ None => Vec::new(),
+ };
+ let mut x = AsconCXof128::with_customization(&z);
+ let mut buf = [0u8; 1024];
+ let mut bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ while bytes_read != 0 {
+ // Absorb cannot fail here: we only absorb before any squeeze.
+ x.absorb(&buf[..bytes_read]).expect("absorb before squeeze is infallible");
+ bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ }
+ let out = x.squeeze(output_len);
+ emit(&out, output_hex);
+}
+
+/// Ascon-AEAD128 of stdin. Encrypts (stdin = plaintext, output = ciphertext||tag) or, with
+/// `decrypt`, decrypts (stdin = ciphertext||tag, output = plaintext). Decryption exits with a
+/// non-zero status if the authentication tag does not verify.
+#[allow(clippy::too_many_arguments)]
+pub(crate) fn aead128_cmd(
+ key: &Option<String>,
+ key_file: &Option<String>,
+ nonce: &Option<String>,
+ nonce_file: &Option<String>,
+ ad: &Option<String>,
+ decrypt: bool,
+ output_hex: bool,
+) {
+ let key = require_16(load_bytes(key, key_file, "key"), "key");
+ let nonce = require_16(load_bytes(nonce, nonce_file, "nonce"), "nonce");
+ let ad_bytes = match ad {
+ Some(v) => hex::decode(v).unwrap_or_else(|_| {
+ eprintln!("Error: associated data is not valid hex.");
+ exit(-1)
+ }),
+ None => Vec::new(),
+ };
+ let ad_opt = if ad_bytes.is_empty() { None } else { Some(ad_bytes.as_slice()) };
+
+ let input = read_stdin();
+
+ if decrypt {
+ if input.len() < 16 {
+ eprintln!("Error: ciphertext is shorter than the 16-byte tag.");
+ exit(-1);
+ }
+ let mut out = vec![0u8; input.len() - 16];
+ match AsconAead128::decrypt(&key, &nonce, ad_opt, &input, &mut out) {
+ Ok(n) => {
+ out.truncate(n);
+ emit(&out, output_hex);
+ }
+ Err(_) => {
+ eprintln!("Error: Ascon-AEAD128 authentication failed.");
+ exit(-1);
+ }
+ }
+ } else {
+ let mut out = vec![0u8; input.len() + 16];
+ let n = AsconAead128::encrypt(&key, &nonce, ad_opt, &input, &mut out);
+ out.truncate(n);
+ emit(&out, output_hex);
+ }
+}

cli/src/main.rs

@@ -1,3 +1,4 @@
+mod ascon_cmd;
 mod encoders_cmd;
 mod helpers;
 mod hkdf_cmd;
@@ -124,6 +125,76 @@ enum Subcommands {
  x: bool,
  },
 
+ /// Perform Ascon-Hash256 of the content provided on stdin.
+ /// Supports streaming update for low memory footprint.
+ AsconHash256 {
+ #[arg(short)]
+ /// Output the digest in hex format.
+ x: bool,
+ },
+
+ /// Perform Ascon-XOF128 of the content provided on stdin. Requires the output length in bytes.
+ /// Supports streaming update for low memory footprint.
+ AsconXOF128 {
+ /// Length of the output in bytes.
+ length: usize,
+
+ #[arg(short)]
+ /// Output in hex format.
+ x: bool,
+ },
+
+ /// Perform Ascon-CXOF128 of the content provided on stdin. Requires the output length in bytes.
+ /// Supports streaming update for low memory footprint.
+ AsconCXOF128 {
+ /// Length of the output in bytes.
+ length: usize,
+
+ /// Customization string in hex (optional).
+ #[arg(long)]
+ customization: Option<String>,
+
+ #[arg(short)]
+ /// Output in hex format.
+ x: bool,
+ },
+
+ /// Ascon-AEAD128 authenticated encryption/decryption of the content provided on stdin.
+ /// Encrypts by default (stdin = plaintext, output = ciphertext||tag); with --decrypt the
+ /// reverse. Decryption fails with a non-zero exit status if the tag does not verify.
+ /// Note: in production uses, secrets should not be passed on the command-line because they get
+ /// logged in shell history. Use the file-based input instead.
+ AsconAEAD128 {
+ /// The 128-bit key in hex.
+ /// The `key_file` option is preferred to avoid leaving key material in command history.
+ #[arg(long)]
+ key: Option<String>,
+
+ /// A file containing the 128-bit key in binary.
+ #[arg(long)]
+ key_file: Option<String>,
+
+ /// The 128-bit nonce in hex. Must be unique per encryption under a given key.
+ #[arg(long)]
+ nonce: Option<String>,
+
+ /// A file containing the 128-bit nonce in binary.
+ #[arg(long)]
+ nonce_file: Option<String>,
+
+ /// Associated data in hex (authenticated but not encrypted).
+ #[arg(long)]
+ ad: Option<String>,
+
+ /// Decrypt instead of encrypt.
+ #[arg(short, long)]
+ decrypt: bool,
+
+ #[arg(short)]
+ /// Output in hex format.
+ x: bool,
+ },
+
  /// Perform HMAC-SHA256 of the content provided on stdin.
  /// Supports streaming update for low memory footprint.
  /// Note: in production uses, secrets should not be passed on the command-line because they get
@@ -531,6 +602,18 @@ fn main() {
  Some(Subcommands::SHAKE256 { length, x }) => {
  sha3_cmd::shake_cmd(256, *length, *x);
  }
+ Some(Subcommands::AsconHash256 { x }) => {
+ ascon_cmd::hash256_cmd(*x);
+ }
+ Some(Subcommands::AsconXOF128 { length, x }) => {
+ ascon_cmd::xof128_cmd(*length, *x);
+ }
+ Some(Subcommands::AsconCXOF128 { length, customization, x }) => {
+ ascon_cmd::cxof128_cmd(customization, *length, *x);
+ }
+ Some(Subcommands::AsconAEAD128 { key, key_file, nonce, nonce_file, ad, decrypt, x }) => {
+ ascon_cmd::aead128_cmd(key, key_file, nonce, nonce_file, ad, *decrypt, *x);
+ }
  Some(Subcommands::HMAC_SHA256 { key, key_file, verify, x }) => {
  mac_cmd::mac_cmd(HMACVariant::SHA256, key, key_file, verify, *x)
  }

crypto/ascon/Cargo.toml

@@ -0,0 +1,27 @@
+[package]
+name = "bouncycastle-ascon"
+version.workspace = true
+edition.workspace = true
+
+[features]
+# `std` gates the ergonomic, allocating (`Vec`-returning) one-shot cipher APIs, mirroring the
+# `std` feature of `bouncycastle-core`. On by default; a future `--no-default-features` build is
+# what will let the crate move toward `#![no_std]`.
+default = ["std"]
+std = ["bouncycastle-core/std"]
+
+[dependencies]
+bouncycastle-core.workspace = true
+bouncycastle-rng.workspace = true
+bouncycastle-utils.workspace = true
+
+[dev-dependencies]
+bouncycastle-core-test-framework.workspace = true
+bouncycastle-hex.workspace = true
+bouncycastle-rng.workspace = true
+criterion.workspace = true
+serde_json = "1.0" # todo -- why?
+
+[[bench]]
+name = "ascon_benches"
+harness = false

crypto/ascon/benches/ascon_benches.rs

@@ -0,0 +1,90 @@
+use bouncycastle_rng as rng;
+use criterion::{Criterion, Throughput, criterion_group, criterion_main};
+use std::hint::black_box;
+
+use bouncycastle_ascon::ascon_aead128::AsconAead128;
+use bouncycastle_ascon::ascon_cxof128::AsconCXof128;
+use bouncycastle_ascon::ascon_hash256::AsconHash256;
+use bouncycastle_ascon::ascon_xof128::AsconXof128;
+use bouncycastle_core::traits::{Hash, RNG, XOF};
+
+const DATA_LEN: usize = 16 * 1024;
+
+fn random_data(len: usize) -> Vec<u8> {
+ let mut data = vec![0u8; len];
+ rng::DefaultRNG::default().next_bytes_out(&mut data).unwrap();
+ data
+}
+
+fn bench_aead128_encrypt(c: &mut Criterion) {
+ let key = [0x42u8; 16];
+ let nonce = [0x24u8; 16];
+ let data = random_data(DATA_LEN);
+ let mut out = vec![0u8; DATA_LEN + 16];
+
+ let mut group = c.benchmark_group("ascon::AsconAead128");
+ group.throughput(Throughput::Bytes(DATA_LEN as u64));
+ group.bench_function(format!("{DATA_LEN} bytes -- ::encrypt()"), |b| {
+ b.iter(|| {
+ AsconAead128::encrypt(&key, &nonce, None, black_box(&data), &mut out);
+ black_box(&out);
+ })
+ });
+ group.finish();
+}
+
+fn bench_hash256(c: &mut Criterion) {
+ let data = random_data(DATA_LEN);
+ let mut digest = [0u8; 32];
+
+ let mut group = c.benchmark_group("ascon::AsconHash256");
+ group.throughput(Throughput::Bytes(DATA_LEN as u64));
+ group.bench_function(format!("{DATA_LEN} bytes -- ::hash_out()"), |b| {
+ b.iter(|| {
+ AsconHash256::new().hash_out(black_box(&data), &mut digest);
+ black_box(&digest);
+ })
+ });
+ group.finish();
+}
+
+fn bench_xof128(c: &mut Criterion) {
+ let data = random_data(DATA_LEN);
+ let mut out = [0u8; 64];
+
+ let mut group = c.benchmark_group("ascon::AsconXof128");
+ group.throughput(Throughput::Bytes((DATA_LEN + out.len()) as u64));
+ group.bench_function(
+ format!("input: {DATA_LEN} bytes, output: 64 bytes -- ::hash_xof_out()"),
+ |b| {
+ b.iter(|| {
+ AsconXof128::new().hash_xof_out(black_box(&data), &mut out);
+ black_box(&out);
+ })
+ },
+ );
+ group.finish();
+}
+
+fn bench_cxof128(c: &mut Criterion) {
+ let data = random_data(DATA_LEN);
+ let customization = b"bench-customization";
+ let mut out = [0u8; 64];
+
+ let mut group = c.benchmark_group("ascon::AsconCXof128");
+ group.throughput(Throughput::Bytes((DATA_LEN + out.len()) as u64));
+ group.bench_function(
+ format!("input: {DATA_LEN} bytes, output: 64 bytes -- ::hash_xof_out()"),
+ |b| {
+ b.iter(|| {
+ AsconCXof128::with_customization(customization)
+ .hash_xof_out(black_box(&data), &mut out);
+ black_box(&out);
+ })
+ },
+ );
+ group.finish();
+}
+
+criterion_group!(benches, bench_aead128_encrypt, bench_hash256, bench_xof128, bench_cxof128);
+criterion_main!(benches);

.gitignore

@@ -5,3 +5,5 @@ mutants.out*/
 
 .idea/
 .vscode/
+
+.claude/*

Cargo.toml

@@ -9,6 +9,7 @@ version = "0.1.3"
 
 # *** Internal Dependencies ***
 bouncycastle = { path = "./" }
+bouncycastle-ascon = { path = "./crypto/ascon" }
 bouncycastle-base64 = { path = "./crypto/base64" }
 bouncycastle-core = { path = "crypto/core" }
 bouncycastle-core-test-framework = { path = "./crypto/core-test-framework" }
@@ -41,6 +42,7 @@ version.workspace = true
 edition.workspace = true
 
 [dependencies]
+bouncycastle-ascon.workspace = true
 bouncycastle-base64.workspace = true
 bouncycastle-core.workspace = true
 bouncycastle-factory.workspace = true

cli/src/ascon_cmd.rs

@@ -0,0 +1,152 @@
+use std::io::{Read, Write};
+use std::process::exit;
+use std::{fs, io};
+
+use bouncycastle::ascon::ascon_aead128::AsconAead128;
+use bouncycastle::ascon::ascon_cxof128::AsconCXof128;
+use bouncycastle::ascon::ascon_hash256::AsconHash256;
+use bouncycastle::ascon::ascon_xof128::AsconXof128;
+use bouncycastle::core::traits::{Hash, XOF};
+use bouncycastle::hex;
+
+/// Write `data` to stdout, either as hex or raw binary, followed by a newline.
+fn emit(data: &[u8], output_hex: bool) {
+ if output_hex {
+ for b in data.iter() {
+ print!("{b:02x}");
+ }
+ } else {
+ io::stdout().write_all(data).unwrap();
+ }
+ println!();
+}
+
+/// Read all of stdin into a Vec.
+fn read_stdin() -> Vec<u8> {
+ let mut data = Vec::new();
+ io::stdin().read_to_end(&mut data).expect("Failed to read from stdin");
+ data
+}
+
+/// Load a hex string or a binary file into bytes; exits with an error if neither is supplied.
+fn load_bytes(value: &Option<String>, value_file: &Option<String>, label: &str) -> Vec<u8> {
+ if let Some(file) = value_file {
+ fs::read(file).unwrap_or_else(|e| {
+ eprintln!("Error: failed to read {label} file: {e}");
+ exit(-1)
+ })
+ } else if let Some(v) = value {
+ hex::decode(v).unwrap_or_else(|_| {
+ eprintln!("Error: {label} is not valid hex.");
+ exit(-1)
+ })
+ } else {
+ eprintln!("Error: {label} must be supplied.");
+ exit(-1)
+ }
+}
+
+fn require_16(bytes: Vec<u8>, label: &str) -> [u8; 16] {
+ bytes.try_into().unwrap_or_else(|_: Vec<u8>| {
+ eprintln!("Error: {label} must be exactly 16 bytes.");
+ exit(-1)
+ })
+}
+
+/// Ascon-Hash256 of stdin. Streaming update; 256-bit digest.
+pub(crate) fn hash256_cmd(output_hex: bool) {
+ let mut h = AsconHash256::new();
+ let mut buf = [0u8; 1024];
+ let mut bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ while bytes_read != 0 {
+ h.do_update(&buf[..bytes_read]);
+ bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ }
+ let out = h.do_final();
+ emit(&out, output_hex);
+}
+
+/// Ascon-XOF128 of stdin, producing `output_len` bytes. Streaming absorb.
+pub(crate) fn xof128_cmd(output_len: usize, output_hex: bool) {
+ let mut x = AsconXof128::new();
+ let mut buf = [0u8; 1024];
+ let mut bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ while bytes_read != 0 {
+ // Absorb cannot fail here: we only absorb before any squeeze.
+ x.absorb(&buf[..bytes_read]).expect("absorb before squeeze is infallible");
+ bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ }
+ let out = x.squeeze(output_len);
+ emit(&out, output_hex);
+}
+
+/// Ascon-CXOF128 of stdin with a hex customization string, producing `output_len` bytes.
+pub(crate) fn cxof128_cmd(customization: &Option<String>, output_len: usize, output_hex: bool) {
+ let z = match customization {
+ Some(v) => hex::decode(v).unwrap_or_else(|_| {
+ eprintln!("Error: customization is not valid hex.");
+ exit(-1)
+ }),
+ None => Vec::new(),
+ };
+ let mut x = AsconCXof128::with_customization(&z);
+ let mut buf = [0u8; 1024];
+ let mut bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ while bytes_read != 0 {
+ // Absorb cannot fail here: we only absorb before any squeeze.
+ x.absorb(&buf[..bytes_read]).expect("absorb before squeeze is infallible");
+ bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ }
+ let out = x.squeeze(output_len);
+ emit(&out, output_hex);
+}
+
+/// Ascon-AEAD128 of stdin. Encrypts (stdin = plaintext, output = ciphertext||tag) or, with
+/// `decrypt`, decrypts (stdin = ciphertext||tag, output = plaintext). Decryption exits with a
+/// non-zero status if the authentication tag does not verify.
+#[allow(clippy::too_many_arguments)]
+pub(crate) fn aead128_cmd(
+ key: &Option<String>,
+ key_file: &Option<String>,
+ nonce: &Option<String>,
+ nonce_file: &Option<String>,
+ ad: &Option<String>,
+ decrypt: bool,
+ output_hex: bool,
+) {
+ let key = require_16(load_bytes(key, key_file, "key"), "key");
+ let nonce = require_16(load_bytes(nonce, nonce_file, "nonce"), "nonce");
+ let ad_bytes = match ad {
+ Some(v) => hex::decode(v).unwrap_or_else(|_| {
+ eprintln!("Error: associated data is not valid hex.");
+ exit(-1)
+ }),
+ None => Vec::new(),
+ };
+ let ad_opt = if ad_bytes.is_empty() { None } else { Some(ad_bytes.as_slice()) };
+
+ let input = read_stdin();
+
+ if decrypt {
+ if input.len() < 16 {
+ eprintln!("Error: ciphertext is shorter than the 16-byte tag.");
+ exit(-1);
+ }
+ let mut out = vec![0u8; input.len() - 16];
+ match AsconAead128::decrypt(&key, &nonce, ad_opt, &input, &mut out) {
+ Ok(n) => {
+ out.truncate(n);
+ emit(&out, output_hex);
+ }
+ Err(_) => {
+ eprintln!("Error: Ascon-AEAD128 authentication failed.");
+ exit(-1);
+ }
+ }
+ } else {
+ let mut out = vec![0u8; input.len() + 16];
+ let n = AsconAead128::encrypt(&key, &nonce, ad_opt, &input, &mut out);
+ out.truncate(n);
+ emit(&out, output_hex);
+ }
+}

cli/src/main.rs

@@ -1,3 +1,4 @@
+mod ascon_cmd;
 mod encoders_cmd;
 mod helpers;
 mod hkdf_cmd;
@@ -124,6 +125,76 @@ enum Subcommands {
  x: bool,
  },
 
+ /// Perform Ascon-Hash256 of the content provided on stdin.
+ /// Supports streaming update for low memory footprint.
+ AsconHash256 {
+ #[arg(short)]
+ /// Output the digest in hex format.
+ x: bool,
+ },
+
+ /// Perform Ascon-XOF128 of the content provided on stdin. Requires the output length in bytes.
+ /// Supports streaming update for low memory footprint.
+ AsconXOF128 {
+ /// Length of the output in bytes.
+ length: usize,
+
+ #[arg(short)]
+ /// Output in hex format.
+ x: bool,
+ },
+
+ /// Perform Ascon-CXOF128 of the content provided on stdin. Requires the output length in bytes.
+ /// Supports streaming update for low memory footprint.
+ AsconCXOF128 {
+ /// Length of the output in bytes.
+ length: usize,
+
+ /// Customization string in hex (optional).
+ #[arg(long)]
+ customization: Option<String>,
+
+ #[arg(short)]
+ /// Output in hex format.
+ x: bool,
+ },
+
+ /// Ascon-AEAD128 authenticated encryption/decryption of the content provided on stdin.
+ /// Encrypts by default (stdin = plaintext, output = ciphertext||tag); with --decrypt the
+ /// reverse. Decryption fails with a non-zero exit status if the tag does not verify.
+ /// Note: in production uses, secrets should not be passed on the command-line because they get
+ /// logged in shell history. Use the file-based input instead.
+ AsconAEAD128 {
+ /// The 128-bit key in hex.
+ /// The `key_file` option is preferred to avoid leaving key material in command history.
+ #[arg(long)]
+ key: Option<String>,
+
+ /// A file containing the 128-bit key in binary.
+ #[arg(long)]
+ key_file: Option<String>,
+
+ /// The 128-bit nonce in hex. Must be unique per encryption under a given key.
+ #[arg(long)]
+ nonce: Option<String>,
+
+ /// A file containing the 128-bit nonce in binary.
+ #[arg(long)]
+ nonce_file: Option<String>,
+
+ /// Associated data in hex (authenticated but not encrypted).
+ #[arg(long)]
+ ad: Option<String>,
+
+ /// Decrypt instead of encrypt.
+ #[arg(short, long)]
+ decrypt: bool,
+
+ #[arg(short)]
+ /// Output in hex format.
+ x: bool,
+ },
+
  /// Perform HMAC-SHA256 of the content provided on stdin.
  /// Supports streaming update for low memory footprint.
  /// Note: in production uses, secrets should not be passed on the command-line because they get
@@ -531,6 +602,18 @@ fn main() {
  Some(Subcommands::SHAKE256 { length, x }) => {
  sha3_cmd::shake_cmd(256, *length, *x);
  }
+ Some(Subcommands::AsconHash256 { x }) => {
+ ascon_cmd::hash256_cmd(*x);
+ }
+ Some(Subcommands::AsconXOF128 { length, x }) => {
+ ascon_cmd::xof128_cmd(*length, *x);
+ }
+ Some(Subcommands::AsconCXOF128 { length, customization, x }) => {
+ ascon_cmd::cxof128_cmd(customization, *length, *x);
+ }
+ Some(Subcommands::AsconAEAD128 { key, key_file, nonce, nonce_file, ad, decrypt, x }) => {
+ ascon_cmd::aead128_cmd(key, key_file, nonce, nonce_file, ad, *decrypt, *x);
+ }
  Some(Subcommands::HMAC_SHA256 { key, key_file, verify, x }) => {
  mac_cmd::mac_cmd(HMACVariant::SHA256, key, key_file, verify, *x)
  }

crypto/ascon/Cargo.toml

@@ -0,0 +1,27 @@
+[package]
+name = "bouncycastle-ascon"
+version.workspace = true
+edition.workspace = true
+
+[features]
+# `std` gates the ergonomic, allocating (`Vec`-returning) one-shot cipher APIs, mirroring the
+# `std` feature of `bouncycastle-core`. On by default; a future `--no-default-features` build is
+# what will let the crate move toward `#![no_std]`.
+default = ["std"]
+std = ["bouncycastle-core/std"]
+
+[dependencies]
+bouncycastle-core.workspace = true
+bouncycastle-rng.workspace = true
+bouncycastle-utils.workspace = true
+
+[dev-dependencies]
+bouncycastle-core-test-framework.workspace = true
+bouncycastle-hex.workspace = true
+bouncycastle-rng.workspace = true
+criterion.workspace = true
+serde_json = "1.0" # todo -- why?
+
+[[bench]]
+name = "ascon_benches"
+harness = false

crypto/ascon/benches/ascon_benches.rs

@@ -0,0 +1,90 @@
+use bouncycastle_rng as rng;
+use criterion::{Criterion, Throughput, criterion_group, criterion_main};
+use std::hint::black_box;
+
+use bouncycastle_ascon::ascon_aead128::AsconAead128;
+use bouncycastle_ascon::ascon_cxof128::AsconCXof128;
+use bouncycastle_ascon::ascon_hash256::AsconHash256;
+use bouncycastle_ascon::ascon_xof128::AsconXof128;
+use bouncycastle_core::traits::{Hash, RNG, XOF};
+
+const DATA_LEN: usize = 16 * 1024;
+
+fn random_data(len: usize) -> Vec<u8> {
+ let mut data = vec![0u8; len];
+ rng::DefaultRNG::default().next_bytes_out(&mut data).unwrap();
+ data
+}
+
+fn bench_aead128_encrypt(c: &mut Criterion) {
+ let key = [0x42u8; 16];
+ let nonce = [0x24u8; 16];
+ let data = random_data(DATA_LEN);
+ let mut out = vec![0u8; DATA_LEN + 16];
+
+ let mut group = c.benchmark_group("ascon::AsconAead128");
+ group.throughput(Throughput::Bytes(DATA_LEN as u64));
+ group.bench_function(format!("{DATA_LEN} bytes -- ::encrypt()"), |b| {
+ b.iter(|| {
+ AsconAead128::encrypt(&key, &nonce, None, black_box(&data), &mut out);
+ black_box(&out);
+ })
+ });
+ group.finish();
+}
+
+fn bench_hash256(c: &mut Criterion) {
+ let data = random_data(DATA_LEN);
+ let mut digest = [0u8; 32];
+
+ let mut group = c.benchmark_group("ascon::AsconHash256");
+ group.throughput(Throughput::Bytes(DATA_LEN as u64));
+ group.bench_function(format!("{DATA_LEN} bytes -- ::hash_out()"), |b| {
+ b.iter(|| {
+ AsconHash256::new().hash_out(black_box(&data), &mut digest);
+ black_box(&digest);
+ })
+ });
+ group.finish();
+}
+
+fn bench_xof128(c: &mut Criterion) {
+ let data = random_data(DATA_LEN);
+ let mut out = [0u8; 64];
+
+ let mut group = c.benchmark_group("ascon::AsconXof128");
+ group.throughput(Throughput::Bytes((DATA_LEN + out.len()) as u64));
+ group.bench_function(
+ format!("input: {DATA_LEN} bytes, output: 64 bytes -- ::hash_xof_out()"),
+ |b| {
+ b.iter(|| {
+ AsconXof128::new().hash_xof_out(black_box(&data), &mut out);
+ black_box(&out);
+ })
+ },
+ );
+ group.finish();
+}
+
+fn bench_cxof128(c: &mut Criterion) {
+ let data = random_data(DATA_LEN);
+ let customization = b"bench-customization";
+ let mut out = [0u8; 64];
+
+ let mut group = c.benchmark_group("ascon::AsconCXof128");
+ group.throughput(Throughput::Bytes((DATA_LEN + out.len()) as u64));
+ group.bench_function(
+ format!("input: {DATA_LEN} bytes, output: 64 bytes -- ::hash_xof_out()"),
+ |b| {
+ b.iter(|| {
+ AsconCXof128::with_customization(customization)
+ .hash_xof_out(black_box(&data), &mut out);
+ black_box(&out);
+ })
+ },
+ );
+ group.finish();
+}
+
+criterion_group!(benches, bench_aead128_encrypt, bench_hash256, bench_xof128, bench_cxof128);
+criterion_main!(benches);

.gitignore

@@ -5,3 +5,5 @@ mutants.out*/
 
 .idea/
 .vscode/
+
+.claude/*

Cargo.toml

@@ -9,6 +9,7 @@ version = "0.1.3"
 
 # *** Internal Dependencies ***
 bouncycastle = { path = "./" }
+bouncycastle-ascon = { path = "./crypto/ascon" }
 bouncycastle-base64 = { path = "./crypto/base64" }
 bouncycastle-core = { path = "crypto/core" }
 bouncycastle-core-test-framework = { path = "./crypto/core-test-framework" }
@@ -41,6 +42,7 @@ version.workspace = true
 edition.workspace = true
 
 [dependencies]
+bouncycastle-ascon.workspace = true
 bouncycastle-base64.workspace = true
 bouncycastle-core.workspace = true
 bouncycastle-factory.workspace = true

cli/src/ascon_cmd.rs

@@ -0,0 +1,152 @@
+use std::io::{Read, Write};
+use std::process::exit;
+use std::{fs, io};
+
+use bouncycastle::ascon::ascon_aead128::AsconAead128;
+use bouncycastle::ascon::ascon_cxof128::AsconCXof128;
+use bouncycastle::ascon::ascon_hash256::AsconHash256;
+use bouncycastle::ascon::ascon_xof128::AsconXof128;
+use bouncycastle::core::traits::{Hash, XOF};
+use bouncycastle::hex;
+
+/// Write `data` to stdout, either as hex or raw binary, followed by a newline.
+fn emit(data: &[u8], output_hex: bool) {
+ if output_hex {
+ for b in data.iter() {
+ print!("{b:02x}");
+ }
+ } else {
+ io::stdout().write_all(data).unwrap();
+ }
+ println!();
+}
+
+/// Read all of stdin into a Vec.
+fn read_stdin() -> Vec<u8> {
+ let mut data = Vec::new();
+ io::stdin().read_to_end(&mut data).expect("Failed to read from stdin");
+ data
+}
+
+/// Load a hex string or a binary file into bytes; exits with an error if neither is supplied.
+fn load_bytes(value: &Option<String>, value_file: &Option<String>, label: &str) -> Vec<u8> {
+ if let Some(file) = value_file {
+ fs::read(file).unwrap_or_else(|e| {
+ eprintln!("Error: failed to read {label} file: {e}");
+ exit(-1)
+ })
+ } else if let Some(v) = value {
+ hex::decode(v).unwrap_or_else(|_| {
+ eprintln!("Error: {label} is not valid hex.");
+ exit(-1)
+ })
+ } else {
+ eprintln!("Error: {label} must be supplied.");
+ exit(-1)
+ }
+}
+
+fn require_16(bytes: Vec<u8>, label: &str) -> [u8; 16] {
+ bytes.try_into().unwrap_or_else(|_: Vec<u8>| {
+ eprintln!("Error: {label} must be exactly 16 bytes.");
+ exit(-1)
+ })
+}
+
+/// Ascon-Hash256 of stdin. Streaming update; 256-bit digest.
+pub(crate) fn hash256_cmd(output_hex: bool) {
+ let mut h = AsconHash256::new();
+ let mut buf = [0u8; 1024];
+ let mut bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ while bytes_read != 0 {
+ h.do_update(&buf[..bytes_read]);
+ bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ }
+ let out = h.do_final();
+ emit(&out, output_hex);
+}
+
+/// Ascon-XOF128 of stdin, producing `output_len` bytes. Streaming absorb.
+pub(crate) fn xof128_cmd(output_len: usize, output_hex: bool) {
+ let mut x = AsconXof128::new();
+ let mut buf = [0u8; 1024];
+ let mut bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ while bytes_read != 0 {
+ // Absorb cannot fail here: we only absorb before any squeeze.
+ x.absorb(&buf[..bytes_read]).expect("absorb before squeeze is infallible");
+ bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ }
+ let out = x.squeeze(output_len);
+ emit(&out, output_hex);
+}
+
+/// Ascon-CXOF128 of stdin with a hex customization string, producing `output_len` bytes.
+pub(crate) fn cxof128_cmd(customization: &Option<String>, output_len: usize, output_hex: bool) {
+ let z = match customization {
+ Some(v) => hex::decode(v).unwrap_or_else(|_| {
+ eprintln!("Error: customization is not valid hex.");
+ exit(-1)
+ }),
+ None => Vec::new(),
+ };
+ let mut x = AsconCXof128::with_customization(&z);
+ let mut buf = [0u8; 1024];
+ let mut bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ while bytes_read != 0 {
+ // Absorb cannot fail here: we only absorb before any squeeze.
+ x.absorb(&buf[..bytes_read]).expect("absorb before squeeze is infallible");
+ bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
+ }
+ let out = x.squeeze(output_len);
+ emit(&out, output_hex);
+}
+
+/// Ascon-AEAD128 of stdin. Encrypts (stdin = plaintext, output = ciphertext||tag) or, with
+/// `decrypt`, decrypts (stdin = ciphertext||tag, output = plaintext). Decryption exits with a
+/// non-zero status if the authentication tag does not verify.
+#[allow(clippy::too_many_arguments)]
+pub(crate) fn aead128_cmd(
+ key: &Option<String>,
+ key_file: &Option<String>,
+ nonce: &Option<String>,
+ nonce_file: &Option<String>,
+ ad: &Option<String>,
+ decrypt: bool,
+ output_hex: bool,
+) {
+ let key = require_16(load_bytes(key, key_file, "key"), "key");
+ let nonce = require_16(load_bytes(nonce, nonce_file, "nonce"), "nonce");
+ let ad_bytes = match ad {
+ Some(v) => hex::decode(v).unwrap_or_else(|_| {
+ eprintln!("Error: associated data is not valid hex.");
+ exit(-1)
+ }),
+ None => Vec::new(),
+ };
+ let ad_opt = if ad_bytes.is_empty() { None } else { Some(ad_bytes.as_slice()) };
+
+ let input = read_stdin();
+
+ if decrypt {
+ if input.len() < 16 {
+ eprintln!("Error: ciphertext is shorter than the 16-byte tag.");
+ exit(-1);
+ }
+ let mut out = vec![0u8; input.len() - 16];
+ match AsconAead128::decrypt(&key, &nonce, ad_opt, &input, &mut out) {
+ Ok(n) => {
+ out.truncate(n);
+ emit(&out, output_hex);
+ }
+ Err(_) => {
+ eprintln!("Error: Ascon-AEAD128 authentication failed.");
+ exit(-1);
+ }
+ }
+ } else {
+ let mut out = vec![0u8; input.len() + 16];
+ let n = AsconAead128::encrypt(&key, &nonce, ad_opt, &input, &mut out);
+ out.truncate(n);
+ emit(&out, output_hex);
+ }
+}

cli/src/main.rs

@@ -1,3 +1,4 @@
+mod ascon_cmd;
 mod encoders_cmd;
 mod helpers;
 mod hkdf_cmd;
@@ -124,6 +125,76 @@ enum Subcommands {
  x: bool,
  },
 
+ /// Perform Ascon-Hash256 of the content provided on stdin.
+ /// Supports streaming update for low memory footprint.
+ AsconHash256 {
+ #[arg(short)]
+ /// Output the digest in hex format.
+ x: bool,
+ },
+
+ /// Perform Ascon-XOF128 of the content provided on stdin. Requires the output length in bytes.
+ /// Supports streaming update for low memory footprint.
+ AsconXOF128 {
+ /// Length of the output in bytes.
+ length: usize,
+
+ #[arg(short)]
+ /// Output in hex format.
+ x: bool,
+ },
+
+ /// Perform Ascon-CXOF128 of the content provided on stdin. Requires the output length in bytes.
+ /// Supports streaming update for low memory footprint.
+ AsconCXOF128 {
+ /// Length of the output in bytes.
+ length: usize,
+
+ /// Customization string in hex (optional).
+ #[arg(long)]
+ customization: Option<String>,
+
+ #[arg(short)]
+ /// Output in hex format.
+ x: bool,
+ },
+
+ /// Ascon-AEAD128 authenticated encryption/decryption of the content provided on stdin.
+ /// Encrypts by default (stdin = plaintext, output = ciphertext||tag); with --decrypt the
+ /// reverse. Decryption fails with a non-zero exit status if the tag does not verify.
+ /// Note: in production uses, secrets should not be passed on the command-line because they get
+ /// logged in shell history. Use the file-based input instead.
+ AsconAEAD128 {
+ /// The 128-bit key in hex.
+ /// The `key_file` option is preferred to avoid leaving key material in command history.
+ #[arg(long)]
+ key: Option<String>,
+
+ /// A file containing the 128-bit key in binary.
+ #[arg(long)]
+ key_file: Option<String>,
+
+ /// The 128-bit nonce in hex. Must be unique per encryption under a given key.
+ #[arg(long)]
+ nonce: Option<String>,
+
+ /// A file containing the 128-bit nonce in binary.
+ #[arg(long)]
+ nonce_file: Option<String>,
+
+ /// Associated data in hex (authenticated but not encrypted).
+ #[arg(long)]
+ ad: Option<String>,
+
+ /// Decrypt instead of encrypt.
+ #[arg(short, long)]
+ decrypt: bool,
+
+ #[arg(short)]
+ /// Output in hex format.
+ x: bool,
+ },
+
  /// Perform HMAC-SHA256 of the content provided on stdin.
  /// Supports streaming update for low memory footprint.
  /// Note: in production uses, secrets should not be passed on the command-line because they get
@@ -531,6 +602,18 @@ fn main() {
  Some(Subcommands::SHAKE256 { length, x }) => {
  sha3_cmd::shake_cmd(256, *length, *x);
  }
+ Some(Subcommands::AsconHash256 { x }) => {
+ ascon_cmd::hash256_cmd(*x);
+ }
+ Some(Subcommands::AsconXOF128 { length, x }) => {
+ ascon_cmd::xof128_cmd(*length, *x);
+ }
+ Some(Subcommands::AsconCXOF128 { length, customization, x }) => {
+ ascon_cmd::cxof128_cmd(customization, *length, *x);
+ }
+ Some(Subcommands::AsconAEAD128 { key, key_file, nonce, nonce_file, ad, decrypt, x }) => {
+ ascon_cmd::aead128_cmd(key, key_file, nonce, nonce_file, ad, *decrypt, *x);
+ }
  Some(Subcommands::HMAC_SHA256 { key, key_file, verify, x }) => {
  mac_cmd::mac_cmd(HMACVariant::SHA256, key, key_file, verify, *x)
  }

crypto/ascon/Cargo.toml

@@ -0,0 +1,27 @@
+[package]
+name = "bouncycastle-ascon"
+version.workspace = true
+edition.workspace = true
+
+[features]
+# `std` gates the ergonomic, allocating (`Vec`-returning) one-shot cipher APIs, mirroring the
+# `std` feature of `bouncycastle-core`. On by default; a future `--no-default-features` build is
+# what will let the crate move toward `#![no_std]`.
+default = ["std"]
+std = ["bouncycastle-core/std"]
+
+[dependencies]
+bouncycastle-core.workspace = true
+bouncycastle-rng.workspace = true
+bouncycastle-utils.workspace = true
+
+[dev-dependencies]
+bouncycastle-core-test-framework.workspace = true
+bouncycastle-hex.workspace = true
+bouncycastle-rng.workspace = true
+criterion.workspace = true
+serde_json = "1.0" # todo -- why?
+
+[[bench]]
+name = "ascon_benches"
+harness = false

crypto/ascon/benches/ascon_benches.rs

@@ -0,0 +1,90 @@
+use bouncycastle_rng as rng;
+use criterion::{Criterion, Throughput, criterion_group, criterion_main};
+use std::hint::black_box;
+
+use bouncycastle_ascon::ascon_aead128::AsconAead128;
+use bouncycastle_ascon::ascon_cxof128::AsconCXof128;
+use bouncycastle_ascon::ascon_hash256::AsconHash256;
+use bouncycastle_ascon::ascon_xof128::AsconXof128;
+use bouncycastle_core::traits::{Hash, RNG, XOF};
+
+const DATA_LEN: usize = 16 * 1024;
+
+fn random_data(len: usize) -> Vec<u8> {
+ let mut data = vec![0u8; len];
+ rng::DefaultRNG::default().next_bytes_out(&mut data).unwrap();
+ data
+}
+
+fn bench_aead128_encrypt(c: &mut Criterion) {
+ let key = [0x42u8; 16];
+ let nonce = [0x24u8; 16];
+ let data = random_data(DATA_LEN);
+ let mut out = vec![0u8; DATA_LEN + 16];
+
+ let mut group = c.benchmark_group("ascon::AsconAead128");
+ group.throughput(Throughput::Bytes(DATA_LEN as u64));
+ group.bench_function(format!("{DATA_LEN} bytes -- ::encrypt()"), |b| {
+ b.iter(|| {
+ AsconAead128::encrypt(&key, &nonce, None, black_box(&data), &mut out);
+ black_box(&out);
+ })
+ });
+ group.finish();
+}
+
+fn bench_hash256(c: &mut Criterion) {
+ let data = random_data(DATA_LEN);
+ let mut digest = [0u8; 32];
+
+ let mut group = c.benchmark_group("ascon::AsconHash256");
+ group.throughput(Throughput::Bytes(DATA_LEN as u64));
+ group.bench_function(format!("{DATA_LEN} bytes -- ::hash_out()"), |b| {
+ b.iter(|| {
+ AsconHash256::new().hash_out(black_box(&data), &mut digest);
+ black_box(&digest);
+ })
+ });
+ group.finish();
+}
+
+fn bench_xof128(c: &mut Criterion) {
+ let data = random_data(DATA_LEN);
+ let mut out = [0u8; 64];
+
+ let mut group = c.benchmark_group("ascon::AsconXof128");
+ group.throughput(Throughput::Bytes((DATA_LEN + out.len()) as u64));
+ group.bench_function(
+ format!("input: {DATA_LEN} bytes, output: 64 bytes -- ::hash_xof_out()"),
+ |b| {
+ b.iter(|| {
+ AsconXof128::new().hash_xof_out(black_box(&data), &mut out);
+ black_box(&out);
+ })
+ },
+ );
+ group.finish();
+}
+
+fn bench_cxof128(c: &mut Criterion) {
+ let data = random_data(DATA_LEN);
+ let customization = b"bench-customization";
+ let mut out = [0u8; 64];
+
+ let mut group = c.benchmark_group("ascon::AsconCXof128");
+ group.throughput(Throughput::Bytes((DATA_LEN + out.len()) as u64));
+ group.bench_function(
+ format!("input: {DATA_LEN} bytes, output: 64 bytes -- ::hash_xof_out()"),
+ |b| {
+ b.iter(|| {
+ AsconCXof128::with_customization(customization)
+ .hash_xof_out(black_box(&data), &mut out);
+ black_box(&out);
+ })
+ },
+ );
+ group.finish();
+}
+
+criterion_group!(benches, bench_aead128_encrypt, bench_hash256, bench_xof128, bench_cxof128);
+criterion_main!(benches);