aria: add bouncycastle-aria, a constant-time ARIA block cipher

CLAUDE.md

@@ -204,4 +204,31 @@ external vector suites — is specified in QUALITY_AND_STYLE.md and CONTRIBUTING
 
 ## CI
 
-The only workflow is `.github/workflows/publish_doc_benches_to_ghpages.yaml`: on every PR it builds rustdoc and runs `quality_stats.sh`; on `main` it additionally runs `cargo bench --all` and publishes docs, code stats, and benchmark results to GitHub Pages (`https://bcgit.github.io/bc-rust/`). There is no separate CI test/lint job — local `cargo test --workspace` is the gate, and nothing but a developer running it stands between a broken test and `main`.
+Five workflows in `.github/workflows/`, every one of them triggered by `pull_request` — so they run
+when the branch you push has a PR open, and a bare branch push with no PR runs nothing.
+
+| Workflow | File | What it runs |
+|---|---|---|
+| Rust Build | `rust-build.yml` | `cargo build --workspace --all-targets --all-features` |
+| Rust Tests | `rust-test.yml` | `cargo test --all` |
+| Rust Docs | `rust-docs.yml` | `cargo doc --all` |
+| Rust Style | `rust-style.yml` | `cargo fmt --all --check`, under nightly rustfmt |
+| Build and Publish Docs | `publish_doc_benches_to_ghpages.yaml` | `cargo doc`, and `quality_stats.sh ./crypto` |
+
+Run those first four locally before pushing — together they are the gate, and `Rust Tests` is the
+one that actually fails PRs. (`cargo test --all` is the same thing as `cargo test --workspace`;
+`--all` is the old spelling. Either way the point in [Common commands](#common-commands) stands:
+without it you run zero tests.)
+
+Things worth knowing about the fifth:
+
+- It only **publishes** to GitHub Pages (`https://bcgit.github.io/bc-rust/`) on a push to `main`;
+  its `collect_ghpages` and `publish_to_gh_pages` jobs are gated on
+  `github.ref == 'refs/heads/main'`. On a PR it just builds the doc and code-stats artifacts.
+- It does **not** run benchmarks, despite the file name: the `run_benches` job is commented out
+  ("the benches run crazy slow on the github agent"), so no benchmark results reach the site.
+- It uses `concurrency: group: "pages"` with `cancel-in-progress: true`, which is global rather than
+  per branch. Push several branches at once and all but the last report **cancelled** — that is the
+  concurrency group, not a failure.
+
+`Rust Style` is skipped on forks (`if: github.repository == 'bcgit/bc-rust'`).

Cargo.toml

@@ -12,6 +12,7 @@ version = "0.1.3"
 # *** Internal Dependencies ***
 bouncycastle = { path = "./" }
 bouncycastle-aes = { path = "./crypto/aes" }
+bouncycastle-aria = { path = "./crypto/aria" }
 bouncycastle-ascon = { path = "./crypto/ascon" }
 bouncycastle-base64 = { path = "./crypto/base64" }
 bouncycastle-cipher = { path = "./crypto/cipher" }
@@ -48,6 +49,7 @@ edition.workspace = true
 
 [dependencies]
 bouncycastle-aes.workspace = true
+bouncycastle-aria.workspace = true
 bouncycastle-ascon.workspace = true
 bouncycastle-base64.workspace = true
 bouncycastle-cipher.workspace = true

alpha_0.1.3_release_notes.md

@@ -5,6 +5,8 @@
 * New algorithms added to crypto/ :
     * SM3 -- the SM3 hash (GB/T 32905-2016 / ISO/IEC 10118-3:2018), ported from bc-java.
     * AES -- AES-128/192/256, along with its modes AES_ECB, AES_CBC, AES_CCM, AES_CFB, AES_CFB8, AES_CTR, and AES_GCM.
+    * ARIA -- the ARIA block cipher (RFC 5794 / KS X 1213-1), ported from bc-java, along with its ARIA_CBC,
+      ARIA_CFB, ARIA_CFB8 and ARIA_CTR modes.
     * ASCON -- Ascon-AEAD128, Ascon-Hash256, Ascon-XOF128 and Ascon-CXOF128 (NIST SP 800-232).
 * Further memory usage improvements on ML-DSA / ML-KEM. New figures for the largest size are:
     * ML-DSA-87/Sign 118 kb, ML-DSA-87/Verify 212 kb

cli/src/aria_cbc_cmd.rs

@@ -0,0 +1,73 @@
+//! ARIA-CBC encryption and decryption, streaming stdin to stdout.
+//!
+//! Only the cipher wiring lives here: the IV convention, key loading, stdin framing and
+//! block-alignment enforcement are all in [`crate::helpers::block_mode_helpers`], shared with the `aes*-cbc`,
+//! `aes*-cfb` and `aes*-ecb` commands. See that module for the
+//! command-line contract.
+//!
+//! `aria128-cbc` / `aria192-cbc` / `aria256-cbc` are the same command as `aes*-cbc` over the ARIA
+//! permutation (RFC 5794; 16-, 24- or 32-byte key, 16-byte block -- the `id-aria*-cbc` algorithms of
+//! RFC 5794 Appendix B), so every remark there applies unchanged. CBC (NIST SP 800-38A Sec 6.2)
+//! provides confidentiality only: neither the ciphertext nor the IV is authenticated. Do not decrypt
+//! data you have not authenticated separately.
+
+use crate::helpers::block_mode_helpers::{
+    BLOCK_LEN, CipherDirection, decrypt_stream, encrypt_stream, load_key,
+};
+use bouncycastle::aria::hazmat::{ARIA_128, ARIA_192, ARIA_256};
+use bouncycastle::cipher::modes::Cbc;
+use bouncycastle::cipher::{Decrypting, Encrypting};
+use bouncycastle::core::hazmat::ElectronicCodeBook;
+use bouncycastle::core::key_material::KeyMaterial;
+
+/// Names the mode in error messages.
+const MODE: &str = "CBC";
+
+pub(crate) fn aria128_cbc_cmd(
+    action: &CipherDirection,
+    key: &Option<String>,
+    key_file: &Option<String>,
+    output_hex: bool,
+) {
+    run::<ARIA_128, 16>(action, &load_key::<16>(key, key_file, "ARIA-128"), output_hex);
+}
+
+pub(crate) fn aria192_cbc_cmd(
+    action: &CipherDirection,
+    key: &Option<String>,
+    key_file: &Option<String>,
+    output_hex: bool,
+) {
+    run::<ARIA_192, 24>(action, &load_key::<24>(key, key_file, "ARIA-192"), output_hex);
+}
+
+pub(crate) fn aria256_cbc_cmd(
+    action: &CipherDirection,
+    key: &Option<String>,
+    key_file: &Option<String>,
+    output_hex: bool,
+) {
+    run::<ARIA_256, 32>(action, &load_key::<32>(key, key_file, "ARIA-256"), output_hex);
+}
+
+/// Dispatches to the shared streaming loops with `Cbc` filled in as the mode.
+fn run<P, const KEY_LEN: usize>(
+    action: &CipherDirection,
+    key: &KeyMaterial<KEY_LEN>,
+    output_hex: bool,
+) where
+    P: ElectronicCodeBook<KEY_LEN, BLOCK_LEN>,
+{
+    match action {
+        CipherDirection::Encrypt => {
+            encrypt_stream::<Cbc<P, Encrypting, KEY_LEN, BLOCK_LEN>, KEY_LEN, BLOCK_LEN>(
+                key, output_hex, MODE,
+            )
+        }
+        CipherDirection::Decrypt => {
+            decrypt_stream::<Cbc<P, Decrypting, KEY_LEN, BLOCK_LEN>, KEY_LEN, BLOCK_LEN>(
+                key, output_hex, MODE,
+            )
+        }
+    }
+}

cli/src/aria_cfb8_cmd.rs

@@ -0,0 +1,68 @@
+//! ARIA-CFB8 encryption and decryption, streaming stdin to stdout.
+//!
+//! Only the cipher wiring lives here: the IV convention, key loading and stdin framing are in
+//! [`crate::helpers::stream_mode_helpers`] (and [`crate::helpers::block_mode_helpers`] for the key loader), shared with the
+//! `aes*-cfb8` commands. See those modules for the command-line contract.
+//!
+//! `aria128-cfb8` / `aria192-cfb8` / `aria256-cfb8` are the same command as `aes*-cfb8`
+//! over the ARIA permutation (RFC 5794; 16-, 24- or 32-byte key, 16-byte block), so every
+//! remark there applies unchanged. The segment size is one byte (NIST SP 800-38A Sec 6.3 with
+//! `s = 8`): a DIFFERENT, NON-INTEROPERABLE mode from the CFB128 of `aria*-cfb`, costing a full
+//! ARIA call per byte, sixteen times the work. Prefer `aria*-cfb` unless a byte-granular
+//! self-synchronising stream is required or the format demands CFB8.
+//!
+//! # Warning
+//!
+//! CFB8 provides confidentiality only. It does not detect tampering, and neither the ciphertext nor
+//! the IV is authenticated. Do not decrypt data you have not authenticated separately.
+
+use crate::helpers::block_mode_helpers::{BLOCK_LEN, CipherDirection, load_key};
+use crate::helpers::stream_mode_helpers::run_stream_mode;
+use bouncycastle::aria::hazmat::{ARIA_128, ARIA_192, ARIA_256};
+use bouncycastle::cipher::modes::Cfb8;
+use bouncycastle::cipher::{Decrypting, Encrypting};
+use bouncycastle::core::hazmat::ElectronicCodeBook;
+use bouncycastle::core::key_material::KeyMaterial;
+
+pub(crate) fn aria128_cfb8_cmd(
+    action: &CipherDirection,
+    key: &Option<String>,
+    key_file: &Option<String>,
+    output_hex: bool,
+) {
+    run::<ARIA_128, 16>(action, &load_key::<16>(key, key_file, "ARIA-128"), output_hex);
+}
+
+pub(crate) fn aria192_cfb8_cmd(
+    action: &CipherDirection,
+    key: &Option<String>,
+    key_file: &Option<String>,
+    output_hex: bool,
+) {
+    run::<ARIA_192, 24>(action, &load_key::<24>(key, key_file, "ARIA-192"), output_hex);
+}
+
+pub(crate) fn aria256_cfb8_cmd(
+    action: &CipherDirection,
+    key: &Option<String>,
+    key_file: &Option<String>,
+    output_hex: bool,
+) {
+    run::<ARIA_256, 32>(action, &load_key::<32>(key, key_file, "ARIA-256"), output_hex);
+}
+
+/// Dispatches to the shared streaming loops with `Cfb8` filled in as the mode.
+fn run<P, const KEY_LEN: usize>(
+    action: &CipherDirection,
+    key: &KeyMaterial<KEY_LEN>,
+    output_hex: bool,
+) where
+    P: ElectronicCodeBook<KEY_LEN, BLOCK_LEN>,
+{
+    run_stream_mode::<
+        Cfb8<P, Encrypting, KEY_LEN, BLOCK_LEN>,
+        Cfb8<P, Decrypting, KEY_LEN, BLOCK_LEN>,
+        KEY_LEN,
+        BLOCK_LEN,
+    >(action, key, output_hex)
+}

cli/src/aria_cfb_cmd.rs

@@ -0,0 +1,73 @@
+//! ARIA-CFB128 encryption and decryption, streaming stdin to stdout.
+//!
+//! Only the cipher wiring lives here: the IV convention, key loading and stdin framing are in
+//! [`crate::helpers::stream_mode_helpers`] (and [`crate::helpers::block_mode_helpers`] for the key loader), shared with the
+//! `aes*-cfb` commands. See those modules for the command-line contract.
+//!
+//! `aria128-cfb` / `aria192-cfb` / `aria256-cfb` are the same command as `aes*-cfb`
+//! over the ARIA permutation (RFC 5794; 16-, 24- or 32-byte key, 16-byte block), so every
+//! remark there applies unchanged. The segment size is the full block, i.e. **CFB128**
+//! (NIST SP 800-38A Sec 6.3 with `s = b`); the `s = 8` variant is a different, non-interoperable
+//! mode and has its own commands, `aria*-cfb8`.
+//!
+//! CFB is a stream cipher, so unlike `aria*-cbc` these commands accept input of any length and
+//! pad nothing; the ciphertext is exactly as long as the plaintext.
+//!
+//! # Warning
+//!
+//! CFB provides confidentiality only. It does not detect tampering, and neither the ciphertext nor
+//! the IV is authenticated. Flipping a ciphertext bit flips the *same* bit of the plaintext in the
+//! *same* block (SP 800-38A Appendix D, Table D.2), at the cost of randomising the next one, so an
+//! attacker edits the block they aimed at. Do not decrypt data you have not authenticated
+//! separately.
+
+use crate::helpers::block_mode_helpers::{BLOCK_LEN, CipherDirection, load_key};
+use crate::helpers::stream_mode_helpers::run_stream_mode;
+use bouncycastle::aria::hazmat::{ARIA_128, ARIA_192, ARIA_256};
+use bouncycastle::cipher::modes::Cfb;
+use bouncycastle::cipher::{Decrypting, Encrypting};
+use bouncycastle::core::hazmat::ElectronicCodeBook;
+use bouncycastle::core::key_material::KeyMaterial;
+
+pub(crate) fn aria128_cfb_cmd(
+    action: &CipherDirection,
+    key: &Option<String>,
+    key_file: &Option<String>,
+    output_hex: bool,
+) {
+    run::<ARIA_128, 16>(action, &load_key::<16>(key, key_file, "ARIA-128"), output_hex);
+}
+
+pub(crate) fn aria192_cfb_cmd(
+    action: &CipherDirection,
+    key: &Option<String>,
+    key_file: &Option<String>,
+    output_hex: bool,
+) {
+    run::<ARIA_192, 24>(action, &load_key::<24>(key, key_file, "ARIA-192"), output_hex);
+}
+
+pub(crate) fn aria256_cfb_cmd(
+    action: &CipherDirection,
+    key: &Option<String>,
+    key_file: &Option<String>,
+    output_hex: bool,
+) {
+    run::<ARIA_256, 32>(action, &load_key::<32>(key, key_file, "ARIA-256"), output_hex);
+}
+
+/// Dispatches to the shared streaming loops with `Cfb` filled in as the mode.
+fn run<P, const KEY_LEN: usize>(
+    action: &CipherDirection,
+    key: &KeyMaterial<KEY_LEN>,
+    output_hex: bool,
+) where
+    P: ElectronicCodeBook<KEY_LEN, BLOCK_LEN>,
+{
+    run_stream_mode::<
+        Cfb<P, Encrypting, KEY_LEN, BLOCK_LEN>,
+        Cfb<P, Decrypting, KEY_LEN, BLOCK_LEN>,
+        KEY_LEN,
+        BLOCK_LEN,
+    >(action, key, output_hex)
+}

cli/src/aria_ctr_cmd.rs

@@ -0,0 +1,78 @@
+//! ARIA-CTR encryption and decryption, streaming stdin to stdout.
+//!
+//! Only the cipher wiring lives here: the nonce convention, key loading and stdin framing are in
+//! [`crate::helpers::stream_mode_helpers`] (and [`crate::helpers::block_mode_helpers`] for the key loader), shared with the
+//! `aes*-ctr` commands. See those modules for the command-line contract.
+//!
+//! `aria128-ctr` / `aria192-ctr` / `aria256-ctr` are the same command as `aes*-ctr` over
+//! the ARIA permutation (RFC 5794; 16-, 24- or 32-byte key, 16-byte block), so every remark
+//! there applies unchanged, including the split of the counter block: the nonce is **12 bytes** and
+//! the counter the remaining 4, giving 2^32 blocks -- 64 GiB -- in a single message. That is
+//! NIST SP 800-38A Appendix B.2's construction, and it is the one KISA's published ARIA-CTR
+//! vectors use: their counter block is all zeros and increments from there, which is what a
+//! twelve-byte zero nonce and a counter starting at zero produce.
+//!
+//! `encrypt` writes that 12-byte nonce as the first bytes of its output and `decrypt` reads it back,
+//! exactly as the other modes do with their IVs; note that it is 12 bytes here, not 16.
+//!
+//! # Warning
+//!
+//! CTR provides confidentiality only and is the most malleable mode here: flipping any ciphertext
+//! bit flips exactly the corresponding plaintext bit and affects nothing else (SP 800-38A
+//! Appendix D, Table D.2), so an attacker can edit the plaintext at will with no garbling to give
+//! it away. A repeated nonce under one key is fatal rather than merely unwise -- the same keystream
+//! twice leaks the XOR of the two messages -- which is why the nonce is drawn from the OS-backed
+//! DRBG and there is no way to supply one. Do not decrypt data you have not authenticated
+//! separately.
+
+use crate::helpers::block_mode_helpers::{BLOCK_LEN, CipherDirection, load_key};
+use crate::helpers::stream_mode_helpers::run_stream_mode;
+use bouncycastle::aria::CTR_NONCE_LEN;
+use bouncycastle::aria::hazmat::{ARIA_128, ARIA_192, ARIA_256};
+use bouncycastle::cipher::modes::Ctr;
+use bouncycastle::cipher::{Decrypting, Encrypting};
+use bouncycastle::core::hazmat::ElectronicCodeBook;
+use bouncycastle::core::key_material::KeyMaterial;
+
+pub(crate) fn aria128_ctr_cmd(
+    action: &CipherDirection,
+    key: &Option<String>,
+    key_file: &Option<String>,
+    output_hex: bool,
+) {
+    run::<ARIA_128, 16>(action, &load_key::<16>(key, key_file, "ARIA-128"), output_hex);
+}
+
+pub(crate) fn aria192_ctr_cmd(
+    action: &CipherDirection,
+    key: &Option<String>,
+    key_file: &Option<String>,
+    output_hex: bool,
+) {
+    run::<ARIA_192, 24>(action, &load_key::<24>(key, key_file, "ARIA-192"), output_hex);
+}
+
+pub(crate) fn aria256_ctr_cmd(
+    action: &CipherDirection,
+    key: &Option<String>,
+    key_file: &Option<String>,
+    output_hex: bool,
+) {
+    run::<ARIA_256, 32>(action, &load_key::<32>(key, key_file, "ARIA-256"), output_hex);
+}
+
+/// Dispatches to the shared streaming loops with `Ctr` filled in as the mode.
+fn run<P, const KEY_LEN: usize>(
+    action: &CipherDirection,
+    key: &KeyMaterial<KEY_LEN>,
+    output_hex: bool,
+) where
+    P: ElectronicCodeBook<KEY_LEN, BLOCK_LEN>,
+{
+    run_stream_mode::<
+        Ctr<P, Encrypting, KEY_LEN, BLOCK_LEN, CTR_NONCE_LEN>,
+        Ctr<P, Decrypting, KEY_LEN, BLOCK_LEN, CTR_NONCE_LEN>,
+        KEY_LEN,
+        CTR_NONCE_LEN,
+    >(action, key, output_hex)
+}