xoodyak 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '087e6888550b824a43b269965b1066bd4daad3d1942cc517ced8435ffcfaa21b'
+  data.tar.gz: 0cabd3ab1dfddae09c63de3040479e365e11c10726d9a3a484f7983927080173
+SHA512:
+  metadata.gz: ea9b1f41888eef78c4ca2e960988f7f04cc418386b2883f0cf4653be7a699b7eef0eb5d44c9b072fd0a9dbf2340bf6d5082ceb16c7f5582c7bf502bc0a90c0cb
+  data.tar.gz: 1c0a4f756035ff03478a7031c40fd505d03f7c32fb02e0e5e755ac7ed872c587dafe2b71f161cd308907c4fa183769553ede8bc3bf615fdee91c12303999bab1

data/LICENSE.md

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, Sarun Rattanasiri
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,352 @@
+# Xoodyak Ruby Gem
+
+A blazing fast, secure, and modern Rust-backed Ruby implementation of the Xoodyak cryptographic scheme.
+
+[![Gem Version](https://img.shields.io/gem/v/xoodyak.svg?style=flat-square)](https://badge.fury.io/rb/xoodyak)
+[![License](https://img.shields.io/badge/license-BSD--2--Clause-blue.svg?style=flat-square)](https://github.com/midnight-wonderer/xoodyak-rb/blob/main/LICENSE.md)
+[![RBS Types](https://img.shields.io/badge/types-RBS-informational.svg?style=flat-square)](https://github.com/midnight-wonderer/xoodyak-rb/blob/main/sig/xoodyak.rbs)
+
+---
+
+## 📖 Table of Contents
+
+- [Introduction](#-introduction)
+- [Features](#-features)
+- [Installation](#-installation)
+- [Usage Guide](#-usage-guide)
+  - [1. Hashing (Unkeyed Mode)](#1-hashing-unkeyed-mode)
+  - [2. Ruby Digest API Integration](#2-ruby-digest-api-integration)
+  - [3. Symmetric Encryption (Keyed Mode)](#3-symmetric-encryption-keyed-mode)
+  - [4. Authenticated Encryption (AEAD)](#4-authenticated-encryption-aead)
+    - [Combined Ciphertext & Tag](#combined-ciphertext--tag)
+    - [Detached Ciphertext & Tag](#detached-ciphertext--tag)
+  - [5. Advanced Keyed Customization (Nonces, Key IDs, Counters)](#5-advanced-keyed-customization-nonces-key-ids-counters)
+  - [6. Forward Secrecy (State Ratcheting)](#6-forward-secrecy-state-ratcheting)
+  - [7. Stateful Session-based Encrypt/Decrypt](#7-stateful-session-based-encryptdecrypt)
+  - [8. State Cloning & Checkpointing](#8-state-cloning--checkpointing)
+- [API Reference](#-api-reference)
+- [Type Safety with RBS](#-type-safety-with-rbs)
+- [Development & Testing](#-development--testing)
+- [License](#-license)
+
+---
+
+## 🌟 Introduction
+
+**Xoodyak** is a lightweight cryptographic scheme designed by the Keccak team (creators of SHA-3). It is part of the Keccak family and is optimized for low-resource environments. Xoodyak operates as a stateful "sponge" construction, making it extremely versatile. A single instance can perform:
+- **Hashing** (unkeyed mode)
+- **Symmetric Encryption** (keyed mode)
+- **Message Authentication Codes (MAC)** (keyed mode)
+- **Authenticated Encryption with Associated Data (AEAD)** (keyed mode)
+- **Key Derivation & Ratcheting**
+
+This gem provides a production-ready Ruby interface to Xoodyak, wrapping a highly optimized Rust implementation.
+
+---
+
+## ⚡ Features
+
+- 🏎️ **Blazing Fast**: Native Rust extension using `magnus` and `rb-sys` outpaces pure Ruby cryptography.
+- 🔒 **Sponge-based Design**: Supports stateful session-based protocols.
+- 🛠️ **Seamless Digest Integration**: Inherits from Ruby's standard `Digest::Base` for drop-in compatibility.
+- 📦 **Zero-Configuration AEAD**: Simple combined and detached AEAD interfaces.
+- 🧩 **RBS Typed**: Complete type definitions shipped out of the box.
+- 🛡️ **Memory Safe**: Built-in Rust safety guarantees prevent common memory leaks and buffer overflows.
+
+---
+
+## 📥 Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'xoodyak'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it directly via:
+
+```bash
+$ gem install xoodyak
+```
+
+> [!NOTE]
+> Since this gem includes a Rust extension, you must have the **Rust toolchain** (cargo/rustc) installed on your system to compile it.
+
+---
+
+## 🚀 Usage Guide
+
+### 1. Hashing (Unkeyed Mode)
+
+In unkeyed mode, Xoodyak acts as a standard cryptographic hash function. You can feed data incrementally using `absorb` and extract the hash using `squeeze`.
+
+```ruby
+require 'xoodyak'
+
+# Initialize in unkeyed (hashing) mode
+hash_sponge = Xoodyak.new
+
+# Absorb data
+hash_sponge.absorb("Hello, world!")
+
+# Squeeze out the digest (you can request any length!)
+digest = hash_sponge.squeeze(32)
+# => returns a 32-byte binary string
+```
+
+### 2. Ruby Digest API Integration
+
+For standard hashing tasks, this gem integrates directly with Ruby's `Digest` framework.
+
+```ruby
+require 'xoodyak'
+
+# 1. Instantiate the Digest class
+digest = Xoodyak::Digest.new
+digest.update("Hello, ")
+digest.update("world!")
+puts digest.hexdigest
+# => "c1ae6b98..."
+
+# 2. Or use the shortcut methods
+hex_hash = Digest::Xoodyak.hexdigest("Hello, world!")
+binary_hash = Digest::Xoodyak.digest("Hello, world!")
+
+# 3. Dynamic loading also works
+algo = Digest("Xoodyak").new
+```
+
+### 3. Symmetric Encryption (Keyed Mode)
+
+By passing a key during initialization, Xoodyak enters **keyed mode**. This allows standard symmetric encryption and decryption.
+
+```ruby
+require 'xoodyak'
+
+key = "my-secure-key-16" # Can be any length (Xoodyak handles varying key lengths)
+
+# Encrypting
+encryptor = Xoodyak.new(key)
+ciphertext = encryptor.encrypt("super secret message")
+
+# Decrypting (initialize a new state with the same key)
+decryptor = Xoodyak.new(key)
+plaintext = decryptor.decrypt(ciphertext)
+puts plaintext # => "super secret message"
+```
+
+### 4. Authenticated Encryption (AEAD)
+
+Standard encryption protects confidentiality but not integrity. **AEAD** (Authenticated Encryption with Associated Data) is highly recommended because it also authenticates the message and optional "Associated Data" (like unencrypted routing headers).
+
+#### Combined Ciphertext & Tag
+
+`aead_encrypt` appends a 16-byte authentication tag directly to the ciphertext. `aead_decrypt` verifies the tag and returns the decrypted text, raising an error if the tag is invalid.
+
+```ruby
+require 'xoodyak'
+require 'securerandom'
+
+key = "my-secure-key-16"
+nonce = SecureRandom.bytes(16) # Nonces must be unique for each encryption!
+
+# Encrypt with Associated Data
+alice = Xoodyak.new(key, nonce)
+alice.absorb("Associated Data (unencrypted header)")
+ciphertext_with_tag = alice.aead_encrypt("confidential message")
+
+# Decrypt and Verify
+bob = Xoodyak.new(key, nonce)
+bob.absorb("Associated Data (unencrypted header)") # Must match Alice's AD
+
+begin
+  decrypted = bob.aead_decrypt(ciphertext_with_tag)
+  puts decrypted # => "confidential message"
+rescue Xoodyak::Error => e
+  # Raised if ciphertext or associated data was altered
+  puts "Integrity check failed: #{e.message}"
+end
+```
+
+#### Detached Ciphertext & Tag
+
+If your protocol stores or transmits the ciphertext and tag separately, you can use the detached API:
+
+```ruby
+require 'xoodyak'
+require 'securerandom'
+
+key = "my-secure-key-16"
+nonce = SecureRandom.bytes(16)
+
+# Encrypt
+alice = Xoodyak.new(key, nonce)
+alice.absorb("metadata")
+ciphertext, tag = alice.aead_encrypt_detached("confidential message")
+
+# Decrypt and Verify
+bob = Xoodyak.new(key, nonce)
+bob.absorb("metadata")
+
+begin
+  decrypted = bob.aead_decrypt_detached(ciphertext, tag)
+  puts decrypted # => "confidential message"
+rescue Xoodyak::Error => e
+  puts "Integrity check failed: #{e.message}"
+end
+```
+
+### 5. Advanced Keyed Customization (Nonces, Key IDs, Counters)
+
+Xoodyak supports initializing the keyed state with a variety of optional parameters:
+- `key` (required for keyed mode)
+- `nonce` (optional binary string)
+- `key_id` (optional binary string)
+- `counter` (optional binary string)
+
+```ruby
+# Initialize with key, nonce, key_id, and counter
+xoodyak = Xoodyak.new(key, nonce, key_id, counter)
+```
+
+> [!WARNING]
+> Passing `nonce`, `key_id`, or `counter` without a `key` will raise an `ArgumentError`.
+
+### 6. Forward Secrecy (State Ratcheting)
+
+State ratcheting advances the keyed state in a non-reversible way. Even if an attacker gains access to the current state, they cannot reconstruct past states, providing forward secrecy.
+
+```ruby
+require 'xoodyak'
+
+xoodyak = Xoodyak.new("my-secret-key")
+
+# Perform operations...
+xoodyak.absorb("some context")
+
+# Ratchet the state
+xoodyak.ratchet
+
+# Squeeze out session keys or continue encrypting
+session_key = xoodyak.squeeze(32)
+```
+
+### 7. Stateful Session-based Encrypt/Decrypt
+
+Xoodyak is stateful: every operation transitions the internal sponge state. This allows Bob and Alice to have a stateful session where they encrypt and decrypt a stream of messages in order.
+
+```ruby
+require 'xoodyak'
+require 'securerandom'
+
+key = "session-key-1234"
+nonce = SecureRandom.bytes(16)
+
+alice = Xoodyak.new(key, nonce)
+bob = Xoodyak.new(key, nonce)
+
+# Alice sends first message
+ct1 = alice.encrypt("Message 1")
+# Bob receives and decrypts
+puts bob.decrypt(ct1) # => "Message 1"
+
+# Alice sends second message (depends on state mutated by msg1!)
+ct2 = alice.encrypt("Message 2")
+# Bob decrypts
+puts bob.decrypt(ct2) # => "Message 2"
+```
+
+> [!IMPORTANT]
+> Because the state mutates with each operation, Alice and Bob must remain in perfect sync. If any message is lost, reordered, or duplicated, decryption will fail. This provides built-in replay and out-of-order protection.
+
+### 8. State Cloning & Checkpointing
+
+You can duplicate or clone the state of a Xoodyak instance. This is useful for saving checkpoints or branching a cryptographic session.
+
+```ruby
+require 'xoodyak'
+
+xoodyak = Xoodyak.new
+xoodyak.absorb("initial setup data")
+
+# Duplicate the state
+checkpoint = xoodyak.dup
+
+# Both instances can now diverge independently
+xoodyak.absorb("branch A")
+checkpoint.absorb("branch B")
+
+puts xoodyak.squeeze(16).unpack1("H*")      # Squeezes based on "initial setup data" + "branch A"
+puts checkpoint.squeeze(16).unpack1("H*")   # Squeezes based on "initial setup data" + "branch B"
+```
+
+---
+
+## 🛠️ API Reference
+
+### `Xoodyak` Class
+
+| Method | Signature | Mode | Description |
+| :--- | :--- | :--- | :--- |
+| `initialize` | `(key=nil, nonce=nil, key_id=nil, counter=nil)` | Any | Creates a Xoodyak instance. Enters keyed mode if a key is provided. |
+| `absorb` | `(bin: String) -> void` | Any | Absorbs binary data into the state. |
+| `squeeze` | `(len: Integer) -> String` | Any | Squeezes `len` bytes from the state. |
+| `squeeze_key` | `(len: Integer) -> String` | Any | Squeezes `len` key bytes from the state. |
+| `encrypt` | `(bin: String) -> String` | Keyed | Encrypts a message. |
+| `decrypt` | `(bin: String) -> String` | Keyed | Decrypts a message. |
+| `aead_encrypt` | `(bin: String) -> String` | Keyed | Encrypts a message, appending a 16-byte authentication tag. |
+| `aead_decrypt` | `(bin: String) -> String` | Keyed | Verifies the tag and decrypts a combined AEAD message. |
+| `aead_encrypt_detached` | `(bin: String) -> [String, String]` | Keyed | Encrypts a message, returning `[ciphertext, tag]`. |
+| `aead_decrypt_detached` | `(bin: String, tag: String) -> String` | Keyed | Verifies the detached tag and decrypts the ciphertext. |
+| `ratchet` | `() -> void` | Keyed | Ratchets the state to provide forward secrecy. |
+| `dup` / `clone` | `() -> Xoodyak` | Any | Creates a deep copy of the Xoodyak instance state. |
+
+---
+
+## 🧩 Type Safety with RBS
+
+This gem is packaged with complete RBS type definitions. You can typecheck your application using Steep or other Ruby signature verification tools.
+
+Type signatures are defined in [sig/xoodyak.rbs](file:///storage/projects/xoodyak-rb/sig/xoodyak.rbs).
+
+---
+
+## 🔧 Development & Testing
+
+After checking out the repo, run `bin/setup` to install dependencies.
+
+### Compilation
+
+Since the core cryptographic operations are written in Rust, you must compile the C-extension locally:
+
+```bash
+bundle exec rake compile
+```
+
+### Running Tests
+
+Run the RSpec test suite:
+
+```bash
+bundle exec rake spec
+```
+
+### Linting
+
+Check code formatting and style guidelines:
+
+```bash
+bundle exec rake rubocop
+```
+
+---
+
+## 📄 License
+
+This gem is available as open source under the terms of the [BSD 2-Clause License](LICENSE.md).

data/ext/xoodyak/Cargo.toml

@@ -0,0 +1,24 @@
+[package]
+name = "xoodyak"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+magnus = { version = "0.8.2", features = ["rb-sys"] }
+rb-sys = { version = "0.9", features = ["stable-api-compiled-fallback"] }
+xoodyak = "0.8.4"
+
+[build-dependencies]
+rb-sys-env = "0.2.2"
+
+[dev-dependencies]
+rb-sys-test-helpers = { version = "0.2.2" }
+
+[lints.rust]
+unexpected_cfgs = { level = "warn", check-cfg = [
+  'cfg(digest_use_rb_ext_resolve_symbol)',
+] }

data/ext/xoodyak/build.rs

@@ -0,0 +1,5 @@
+pub fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let _ = rb_sys_env::activate()?;
+
+    Ok(())
+}

data/ext/xoodyak/extconf.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "mkmf"
+require "rb_sys/mkmf"
+
+# Detect when DIGEST_USE_RB_EXT_RESOLVE_SYMBOL is defined truthy,
+# which indicates rb_ext_resolve_symbol("digest.so", "rb_digest_wrap_metadata")
+# will work with the version of Digest we're building against.
+digest_use_rb_ext_resolve_symbol = try_compile(<<~C)
+  #include <ruby/digest.h>
+
+  #if !defined(DIGEST_USE_RB_EXT_RESOLVE_SYMBOL)
+  # error DIGEST_USE_RB_EXT_RESOLVE_SYMBOL not defined
+  #endif
+  #if !DIGEST_USE_RB_EXT_RESOLVE_SYMBOL
+  # error DIGEST_USE_RB_EXT_RESOLVE_SYMBOL is 0
+  #endif
+C
+puts("digest_use_rb_ext_resolve_symbol=#{digest_use_rb_ext_resolve_symbol}")
+
+create_rust_makefile("xoodyak/xoodyak") do |r|
+  r.extra_rustflags = ["--cfg digest_use_rb_ext_resolve_symbol"] if digest_use_rb_ext_resolve_symbol
+end

data/ext/xoodyak/src/lib.rs

@@ -0,0 +1,438 @@
+use std::cell::RefCell;
+use std::ffi::{c_int, c_uchar, c_void};
+use std::mem::MaybeUninit;
+use std::os::raw::c_char;
+use magnus::{
+    prelude::*, scan_args::scan_args, Error, ExceptionClass, RString, Ruby, Value,
+};
+use rb_sys::{VALUE, size_t};
+use xoodyak::{XoodyakHash, XoodyakKeyed, XoodyakCommon, XoodyakError, XOODYAK_AUTH_TAG_BYTES};
+
+// Low-level Digest bindings
+pub const RUBY_DIGEST_API_VERSION: c_int = 3;
+
+pub type RbDigestHashInitFuncT = unsafe extern "C" fn(*mut c_void) -> c_int;
+pub type RbDigestHashUpdateFuncT = unsafe extern "C" fn(*mut c_void, *mut c_uchar, size_t);
+pub type RbDigestHashFinishFuncT = unsafe extern "C" fn(*mut c_void, *mut c_uchar) -> c_int;
+
+#[derive(Debug)]
+#[repr(C)]
+pub struct RbDigestMetadataT {
+    pub api_version: c_int,
+    pub digest_len: size_t,
+    pub block_len: size_t,
+    pub ctx_size: size_t,
+    pub init_func: RbDigestHashInitFuncT,
+    pub update_func: RbDigestHashUpdateFuncT,
+    pub finish_func: RbDigestHashFinishFuncT,
+}
+
+#[allow(dead_code)]
+type WrapperType = unsafe extern "C" fn(&'static RbDigestMetadataT) -> VALUE;
+
+#[cfg(any(digest_use_rb_ext_resolve_symbol, ruby_gte_3_4))]
+pub unsafe fn rb_digest_make_metadata(meta: &'static RbDigestMetadataT) -> VALUE {
+    static mut WRAPPER: Option<WrapperType> = None;
+
+    unsafe fn load_wrapper() {
+        use rb_sys::rb_ext_resolve_symbol;
+        use std::ffi::c_char;
+        use std::sync::Once;
+
+        static INIT: Once = Once::new();
+
+        INIT.call_once(|| {
+            let lib_name = "digest.so\0".as_ptr() as *const c_char;
+            let symbol_name = "rb_digest_wrap_metadata\0".as_ptr() as *const c_char;
+            let symbol_ptr = unsafe { rb_ext_resolve_symbol(lib_name, symbol_name) };
+
+            if !symbol_ptr.is_null() {
+                unsafe {
+                    WRAPPER = Some(std::mem::transmute::<*mut c_void, WrapperType>(symbol_ptr));
+                }
+            } else {
+                panic!("Failed to resolve rb_digest_wrap_metadata");
+            }
+        });
+    }
+
+    unsafe {
+        load_wrapper();
+        if let Some(wrapper) = WRAPPER {
+            return wrapper(meta);
+        }
+    }
+    panic!("Failed to resolve rb_digest_wrap_metadata");
+}
+
+#[cfg(not(any(digest_use_rb_ext_resolve_symbol, ruby_gte_3_4)))]
+pub unsafe fn rb_digest_make_metadata(meta: &'static RbDigestMetadataT) -> VALUE {
+    use rb_sys::{rb_data_object_wrap, rb_obj_freeze};
+    unsafe {
+        let data = rb_data_object_wrap(
+            0 as VALUE,
+            meta as *const RbDigestMetadataT as *mut c_void,
+            None,
+            None,
+        );
+        rb_obj_freeze(data)
+    }
+}
+
+struct RbXoodyakDigestCtx {
+    hash: XoodyakHash,
+    buffer: [u8; 16],
+    buf_len: usize,
+    first_block_absorbed: bool,
+}
+
+// Struct to configure dynamic digest metadata
+struct XoodyakDigest;
+
+impl XoodyakDigest {
+    const BLOCK_LEN: usize = 16;
+    const DIGEST_LEN: usize = 32;
+
+    fn digest_metadata() -> &'static RbDigestMetadataT {
+        static DIGEST_METADATA: RbDigestMetadataT = RbDigestMetadataT {
+            api_version: RUBY_DIGEST_API_VERSION,
+            digest_len: XoodyakDigest::DIGEST_LEN as _,
+            block_len: XoodyakDigest::BLOCK_LEN as _,
+            ctx_size: std::mem::size_of::<RbXoodyakDigestCtx>() as _,
+            init_func: XoodyakDigest::init_in_place,
+            update_func: XoodyakDigest::update,
+            finish_func: XoodyakDigest::finish,
+        };
+        &DIGEST_METADATA
+    }
+
+    extern "C" fn init_in_place(ctx: *mut c_void) -> c_int {
+        let ctx = ctx as *mut MaybeUninit<RbXoodyakDigestCtx>;
+        let ctx = unsafe { &mut *ctx };
+        ctx.write(RbXoodyakDigestCtx {
+            hash: XoodyakHash::new(),
+            buffer: [0u8; 16],
+            buf_len: 0,
+            first_block_absorbed: false,
+        });
+        true as _
+    }
+
+    extern "C" fn update(ctx: *mut c_void, data: *mut c_uchar, len: size_t) {
+        let ctx = ctx as *mut MaybeUninit<RbXoodyakDigestCtx>;
+        let ctx = unsafe { &mut *ctx };
+        let ctx = unsafe { ctx.assume_init_mut() };
+        let mut slice = unsafe { std::slice::from_raw_parts(data, len as _) };
+
+        while !slice.is_empty() {
+            let space = 16 - ctx.buf_len;
+            if slice.len() >= space {
+                ctx.buffer[ctx.buf_len..16].copy_from_slice(&slice[..space]);
+                slice = &slice[space..];
+
+                if !ctx.first_block_absorbed {
+                    ctx.hash.absorb(&ctx.buffer);
+                    ctx.first_block_absorbed = true;
+                } else {
+                    ctx.hash.absorb_more(&ctx.buffer, 16);
+                }
+                ctx.buf_len = 0;
+            } else {
+                ctx.buffer[ctx.buf_len..ctx.buf_len + slice.len()].copy_from_slice(slice);
+                ctx.buf_len += slice.len();
+                break;
+            }
+        }
+    }
+
+    extern "C" fn finish(ctx: *mut c_void, digest: *mut c_uchar) -> c_int {
+        let ctx = ctx as *mut MaybeUninit<RbXoodyakDigestCtx>;
+        let ctx = unsafe { &mut *ctx };
+        let ctx = unsafe { ctx.assume_init_mut() };
+
+        if ctx.buf_len > 0 {
+            if !ctx.first_block_absorbed {
+                ctx.hash.absorb(&ctx.buffer[..ctx.buf_len]);
+                ctx.first_block_absorbed = true;
+            } else {
+                ctx.hash.absorb_more(&ctx.buffer[..ctx.buf_len], 16);
+            }
+            ctx.buf_len = 0;
+        }
+
+        let outbuf = unsafe { std::slice::from_raw_parts_mut(digest, Self::DIGEST_LEN) };
+        ctx.hash.squeeze(outbuf);
+        true as _
+    }
+}
+
+fn get_error_class(name: &str) -> Option<ExceptionClass> {
+    let ruby = Ruby::get().unwrap();
+    ruby.class_object()
+        .const_get::<_, magnus::RClass>("Xoodyak")
+        .ok()
+        .and_then(|xoodyak| xoodyak.const_get::<_, ExceptionClass>(name).ok())
+}
+
+fn keyed_mode_error(msg: &'static str) -> Error {
+    let ruby = Ruby::get().unwrap();
+    if let Some(error_class) = get_error_class("KeyedModeError") {
+        Error::new(error_class, msg)
+    } else {
+        Error::new(ruby.exception_runtime_error(), msg)
+    }
+}
+
+fn argument_error(msg: &'static str) -> Error {
+    let ruby = Ruby::get().unwrap();
+    if let Some(error_class) = get_error_class("ArgumentError") {
+        Error::new(error_class, msg)
+    } else {
+        Error::new(ruby.exception_arg_error(), msg)
+    }
+}
+
+fn verification_error(msg: &'static str) -> Error {
+    let ruby = Ruby::get().unwrap();
+    if let Some(error_class) = get_error_class("VerificationError") {
+        Error::new(error_class, msg)
+    } else {
+        Error::new(ruby.exception_runtime_error(), msg)
+    }
+}
+
+// Custom error mapping
+fn map_xoodyak_err(err: XoodyakError) -> Error {
+    match err {
+        XoodyakError::InvalidBufferLength => argument_error("invalid buffer length"),
+        XoodyakError::InvalidParameterLength => argument_error("invalid parameter length"),
+        XoodyakError::KeyRequired => argument_error("key required"),
+        XoodyakError::TagMismatch => verification_error("tag mismatch"),
+    }
+}
+
+// Unified Xoodyak class
+#[derive(Clone)]
+enum XoodyakState {
+    Unkeyed(XoodyakHash),
+    Keyed(XoodyakKeyed),
+}
+
+#[derive(magnus::TypedData, Clone)]
+#[magnus(class = "Xoodyak", free_immediately)]
+pub struct Xoodyak {
+    state: RefCell<XoodyakState>,
+}
+
+impl Default for XoodyakState {
+    fn default() -> Self {
+        XoodyakState::Unkeyed(XoodyakHash::new())
+    }
+}
+
+impl Default for Xoodyak {
+    fn default() -> Self {
+        Xoodyak {
+            state: RefCell::new(XoodyakState::default()),
+        }
+    }
+}
+
+impl magnus::DataTypeFunctions for Xoodyak {}
+
+impl Xoodyak {
+    fn initialize(rb_self: magnus::typed_data::Obj<Self>, args: &[Value]) -> Result<(), Error> {
+        let args = scan_args::<(), (Option<Option<RString>>, Option<Option<RString>>, Option<Option<RString>>, Option<Option<RString>>), (), (), (), ()>(args)?;
+        let (key, nonce, key_id, counter) = args.optional;
+        let key = key.flatten();
+        let nonce = nonce.flatten();
+        let key_id = key_id.flatten();
+        let counter = counter.flatten();
+        if let Some(k) = key {
+            let key_bytes = unsafe { k.as_slice() };
+            let nonce_bytes = nonce.as_ref().map(|n| unsafe { n.as_slice() });
+            let key_id_bytes = key_id.as_ref().map(|ki| unsafe { ki.as_slice() });
+            let counter_bytes = counter.as_ref().map(|c| unsafe { c.as_slice() });
+            let keyed = XoodyakKeyed::new(key_bytes, nonce_bytes, key_id_bytes, counter_bytes)
+                .map_err(map_xoodyak_err)?;
+            *rb_self.state.borrow_mut() = XoodyakState::Keyed(keyed);
+        } else {
+            if nonce.is_some() || key_id.is_some() || counter.is_some() {
+                return Err(argument_error(
+                    "nonce, key_id, and counter can only be used in keyed mode (when key is provided)",
+                ));
+            }
+            *rb_self.state.borrow_mut() = XoodyakState::Unkeyed(XoodyakHash::new());
+        }
+        Ok(())
+    }
+
+    fn initialize_copy(&self, other: &Xoodyak) -> Result<(), Error> {
+        let other_state = other.state.borrow().clone();
+        *self.state.borrow_mut() = other_state;
+        Ok(())
+    }
+
+    fn absorb(&self, bin: RString) {
+        let bin_bytes = unsafe { bin.as_slice() };
+        match &mut *self.state.borrow_mut() {
+            XoodyakState::Unkeyed(ref mut h) => h.absorb(bin_bytes),
+            XoodyakState::Keyed(ref mut k) => k.absorb(bin_bytes),
+        }
+    }
+
+    fn squeeze(&self, len: usize) -> RString {
+        let mut buf = vec![0u8; len];
+        match &mut *self.state.borrow_mut() {
+            XoodyakState::Unkeyed(ref mut h) => h.squeeze(&mut buf),
+            XoodyakState::Keyed(ref mut k) => k.squeeze(&mut buf),
+        }
+        Ruby::get().unwrap().str_from_slice(&buf)
+    }
+
+    fn squeeze_key(&self, len: usize) -> RString {
+        let mut buf = vec![0u8; len];
+        match &mut *self.state.borrow_mut() {
+            XoodyakState::Unkeyed(ref mut h) => h.squeeze_key(&mut buf),
+            XoodyakState::Keyed(ref mut k) => k.squeeze_key(&mut buf),
+        }
+        Ruby::get().unwrap().str_from_slice(&buf)
+    }
+
+    fn encrypt(&self, bin: RString) -> Result<RString, Error> {
+        let bin_bytes = unsafe { bin.as_slice() };
+        match &mut *self.state.borrow_mut() {
+            XoodyakState::Unkeyed(_) => Err(keyed_mode_error("encrypt is only supported in keyed mode")),
+            XoodyakState::Keyed(ref mut k) => {
+                let mut out = vec![0u8; bin_bytes.len()];
+                k.encrypt(&mut out, bin_bytes).map_err(map_xoodyak_err)?;
+                Ok(Ruby::get().unwrap().str_from_slice(&out))
+            }
+        }
+    }
+
+    fn decrypt(&self, bin: RString) -> Result<RString, Error> {
+        let bin_bytes = unsafe { bin.as_slice() };
+        match &mut *self.state.borrow_mut() {
+            XoodyakState::Unkeyed(_) => Err(keyed_mode_error("decrypt is only supported in keyed mode")),
+            XoodyakState::Keyed(ref mut k) => {
+                let mut out = vec![0u8; bin_bytes.len()];
+                k.decrypt(&mut out, bin_bytes).map_err(map_xoodyak_err)?;
+                Ok(Ruby::get().unwrap().str_from_slice(&out))
+            }
+        }
+    }
+
+    fn aead_encrypt(&self, bin: RString) -> Result<RString, Error> {
+        let bin_bytes = unsafe { bin.as_slice() };
+        match &mut *self.state.borrow_mut() {
+            XoodyakState::Unkeyed(_) => Err(keyed_mode_error("aead_encrypt is only supported in keyed mode")),
+            XoodyakState::Keyed(ref mut k) => {
+                let mut out = vec![0u8; bin_bytes.len() + XOODYAK_AUTH_TAG_BYTES];
+                k.aead_encrypt(&mut out, Some(bin_bytes)).map_err(map_xoodyak_err)?;
+                Ok(Ruby::get().unwrap().str_from_slice(&out))
+            }
+        }
+    }
+
+    fn aead_decrypt(&self, bin: RString) -> Result<RString, Error> {
+        let bin_bytes = unsafe { bin.as_slice() };
+        match &mut *self.state.borrow_mut() {
+            XoodyakState::Unkeyed(_) => Err(keyed_mode_error("aead_decrypt is only supported in keyed mode")),
+            XoodyakState::Keyed(ref mut k) => {
+                if bin_bytes.len() < XOODYAK_AUTH_TAG_BYTES {
+                    return Err(argument_error("ciphertext is too short to contain a tag"));
+                }
+                let mut out = vec![0u8; bin_bytes.len() - XOODYAK_AUTH_TAG_BYTES];
+                k.aead_decrypt(&mut out, bin_bytes).map_err(map_xoodyak_err)?;
+                Ok(Ruby::get().unwrap().str_from_slice(&out))
+            }
+        }
+    }
+
+    fn aead_encrypt_detached(&self, bin: RString) -> Result<magnus::RArray, Error> {
+        let bin_bytes = unsafe { bin.as_slice() };
+        match &mut *self.state.borrow_mut() {
+            XoodyakState::Unkeyed(_) => Err(keyed_mode_error("aead_encrypt_detached is only supported in keyed mode")),
+            XoodyakState::Keyed(ref mut k) => {
+                let mut out = vec![0u8; bin_bytes.len()];
+                let tag = k.aead_encrypt_detached(&mut out, Some(bin_bytes)).map_err(map_xoodyak_err)?;
+                let ruby = Ruby::get().unwrap();
+                let ct_str = ruby.str_from_slice(&out);
+                let tag_str = ruby.str_from_slice(tag.as_ref());
+                Ok(ruby.ary_new_from_values(&[ct_str.as_value(), tag_str.as_value()]))
+            }
+        }
+    }
+
+    fn aead_decrypt_detached(&self, bin: RString, tag: RString) -> Result<RString, Error> {
+        let bin_bytes = unsafe { bin.as_slice() };
+        let tag_bytes = unsafe { tag.as_slice() };
+        match &mut *self.state.borrow_mut() {
+            XoodyakState::Unkeyed(_) => Err(keyed_mode_error("aead_decrypt_detached is only supported in keyed mode")),
+            XoodyakState::Keyed(ref mut k) => {
+                let t_array: [u8; XOODYAK_AUTH_TAG_BYTES] = tag_bytes.try_into().map_err(|_| {
+                    argument_error("tag must be 16 bytes")
+                })?;
+                let mut out = vec![0u8; bin_bytes.len()];
+                k.aead_decrypt_detached(&mut out, &t_array.into(), Some(bin_bytes))
+                    .map_err(map_xoodyak_err)?;
+                Ok(Ruby::get().unwrap().str_from_slice(&out))
+            }
+        }
+    }
+
+    fn ratchet(&self) -> Result<(), Error> {
+        match &mut *self.state.borrow_mut() {
+            XoodyakState::Unkeyed(_) => Err(keyed_mode_error("ratchet is only supported in keyed mode")),
+            XoodyakState::Keyed(ref mut k) => {
+                k.ratchet();
+                Ok(())
+            }
+        }
+    }
+}
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    // Define the Xoodyak class at the top level
+    let class = ruby.define_class("Xoodyak", ruby.class_object())?;
+    class.define_alloc_func::<Xoodyak>();
+    class.define_method("initialize", magnus::method!(Xoodyak::initialize, -1))?;
+    class.define_method("initialize_copy", magnus::method!(Xoodyak::initialize_copy, 1))?;
+    class.define_method("absorb", magnus::method!(Xoodyak::absorb, 1))?;
+    class.define_method("squeeze", magnus::method!(Xoodyak::squeeze, 1))?;
+    class.define_method("squeeze_key", magnus::method!(Xoodyak::squeeze_key, 1))?;
+    class.define_method("encrypt", magnus::method!(Xoodyak::encrypt, 1))?;
+    class.define_method("decrypt", magnus::method!(Xoodyak::decrypt, 1))?;
+    class.define_method("aead_encrypt", magnus::method!(Xoodyak::aead_encrypt, 1))?;
+    class.define_method("aead_decrypt", magnus::method!(Xoodyak::aead_decrypt, 1))?;
+    class.define_method("aead_encrypt_detached", magnus::method!(Xoodyak::aead_encrypt_detached, 1))?;
+    class.define_method("aead_decrypt_detached", magnus::method!(Xoodyak::aead_decrypt_detached, 2))?;
+    class.define_method("ratchet", magnus::method!(Xoodyak::ratchet, 0))?;
+
+    // Define the custom Error classes/modules under Xoodyak class
+    let error_module = class.define_module("Error")?;
+
+    let keyed_mode_error = class.define_error("KeyedModeError", ruby.exception_standard_error())?;
+    keyed_mode_error.include_module(error_module)?;
+
+    let verification_error = class.define_error("VerificationError", ruby.exception_standard_error())?;
+    verification_error.include_module(error_module)?;
+
+    let argument_error = class.define_error("ArgumentError", ruby.exception_arg_error())?;
+    argument_error.include_module(error_module)?;
+
+    // Define Digest subclassing Digest::Base nested under Xoodyak class
+    ruby.require("digest")?;
+    let digest_module = ruby.define_module("Digest")?;
+    let digest_base = digest_module.const_get::<_, magnus::RClass>("Base")?;
+    let digest_klass = class.define_class("Digest", digest_base)?;
+
+    use magnus::rb_sys::AsRawValue;
+    let meta = unsafe { rb_digest_make_metadata(XoodyakDigest::digest_metadata()) };
+    let metadata_id = unsafe { rb_sys::rb_intern("metadata\0".as_ptr() as *const c_char) };
+    unsafe { rb_sys::rb_ivar_set(digest_klass.as_raw(), metadata_id, meta) };
+
+    Ok(())
+}

data/lib/digest/xoodyak.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "xoodyak"

data/lib/xoodyak/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class Xoodyak
+  VERSION = "0.1.0"
+end

data/lib/xoodyak.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "digest"
+
+# Define the Digest class in the Xoodyak namespace inheriting from Digest::Base,
+# so the C extension can successfully find it and attach the digest metadata.
+class Xoodyak
+  class Digest < ::Digest::Base
+  end
+end
+
+require_relative "xoodyak/version"
+
+begin
+  RUBY_VERSION =~ /(\d+\.\d+)/
+  require "xoodyak/#{Regexp.last_match(1)}/xoodyak"
+rescue LoadError
+  begin
+    require_relative "xoodyak/xoodyak"
+  rescue LoadError
+    require "xoodyak/xoodyak"
+  end
+end
+
+module Digest
+  Xoodyak = ::Xoodyak::Digest
+end

data/sig/xoodyak.rbs

@@ -0,0 +1,34 @@
+class Xoodyak
+  VERSION: String
+
+  module Error
+  end
+
+  class KeyedModeError < ::StandardError
+    include Error
+  end
+
+  class VerificationError < ::StandardError
+    include Error
+  end
+
+  class ArgumentError < ::ArgumentError
+    include Error
+  end
+
+  class Digest < ::Digest::Base
+  end
+
+  def initialize: (?String? key, ?String? nonce, ?String? key_id, ?String? counter) -> void
+  def initialize_copy: (Xoodyak other) -> void
+  def absorb: (String bin) -> void
+  def squeeze: (Integer len) -> String
+  def squeeze_key: (Integer len) -> String
+  def encrypt: (String bin) -> String
+  def decrypt: (String bin) -> String
+  def aead_encrypt: (String bin) -> String
+  def aead_decrypt: (String bin) -> String
+  def aead_encrypt_detached: (String bin) -> [String, String]
+  def aead_decrypt_detached: (String bin, String tag) -> String
+  def ratchet: () -> void
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: xoodyak
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sarun Rattanasiri
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.91
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.91
+description: A Ruby wrapper for the Xoodyak cryptographic scheme, built in Rust using
+  magnus and rb-sys. It supports hashing (unkeyed mode), symmetric encryption and
+  AEAD (keyed mode), forward secrecy (state ratcheting), and integrates with the standard
+  Ruby Digest API.
+email: midnight_w@gmx.tw
+executables: []
+extensions:
+- ext/xoodyak/extconf.rb
+extra_rdoc_files: []
+files:
+- LICENSE.md
+- README.md
+- ext/xoodyak/Cargo.toml
+- ext/xoodyak/build.rs
+- ext/xoodyak/extconf.rb
+- ext/xoodyak/src/lib.rs
+- lib/digest/xoodyak.rb
+- lib/xoodyak.rb
+- lib/xoodyak/version.rb
+- sig/xoodyak.rbs
+homepage: https://github.com/midnight-wonderer/xoodyak-rb
+licenses:
+- BSD-2-Clause
+metadata:
+  source_code_uri: https://github.com/midnight-wonderer/xoodyak-rb
+  bug_tracker_uri: https://github.com/midnight-wonderer/xoodyak-rb/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: A fast, memory-safe Rust-backed Ruby implementation of the Xoodyak cryptographic
+  scheme
+test_files: []