xaes_gcm 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8c94c5ea1a1fb9d1ee9045139a86f53f5c8b7ebf89edc7521136a4065e4e32b5
+  data.tar.gz: 4fd2f8e6b2eccb6de066608818177084ad4f5a9c289b9448842224eaa39ad9d7
+SHA512:
+  metadata.gz: c8a2dc2bc6fb43f227b9fb606cc05ff8caa0f90a160b5e704a19e65bcd959bc2496fa49ff1959b5903fe22087087cc816710ad914a53b498e9c57346e48ac109
+  data.tar.gz: c881c39b0475962a1ee080dfb23c3db5fbb64713ac6fb74225c816fdcac89623789c97ff6d5fa2f8bc0064f468fc6b9a1d2975355cbe9fc9d600069e604b5c38

data/LICENSE.txt

@@ -0,0 +1,21 @@
+Copyright (c) 2020
+The C2SP Authors.  All rights reserved.
+Copyright (c) 2026 Sorah Fukumori.
+
+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.
+
+THIS SOFTWARE IS PROVIDED BY The C2SP Authors ``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 C2SP Authors 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,66 @@
+# xaes_gcm
+
+Ruby implementation of [XAES-256-GCM](https://c2sp.org/XAES-256-GCM), an extended-nonce AEAD built on AES-256-GCM.
+
+XAES-256-GCM uses 192-bit (24-byte) nonces instead of AES-256-GCM's 96-bit nonces. The longer nonce makes it safe to generate nonces randomly for a practically unlimited number of messages, without risking nonce reuse.
+
+This gem implements the key and nonce derivation step of XAES-256-GCM. It derives a standard AES-256-GCM key and nonce from the extended inputs, which you then use with Ruby's built-in `OpenSSL::Cipher` for encryption and decryption.
+
+## Security Warning
+
+> [!CAUTION]
+> No security audits of this gem have ever been performed. USE AT YOUR OWN RISK!
+
+## Installation
+
+```bash
+bundle add xaes_gcm
+```
+
+Or install directly:
+
+```bash
+gem install xaes_gcm
+```
+
+## Usage
+
+```ruby
+require "xaes_gcm"
+
+# Create a reusable key (precomputes the AES key schedule and subkey)
+key = OpenSSL::Random.random_bytes(XaesGcm::KEY_SIZE) # 32 bytes
+xkey = XaesGcm::Key.new(key)
+
+# Encrypt (generates a random 192-bit nonce by default)
+cipher = OpenSSL::Cipher.new("aes-256-gcm")
+cipher.encrypt
+nonce = xkey.apply(cipher)
+cipher.auth_data = "optional authenticated data"
+ciphertext = cipher.update(plaintext) + cipher.final
+tag = cipher.auth_tag
+
+# Decrypt (pass the same nonce used for encryption)
+decipher = OpenSSL::Cipher.new("aes-256-gcm")
+decipher.decrypt
+xkey.apply(decipher, nonce:)
+decipher.auth_tag = tag
+decipher.auth_data = "optional authenticated data"
+plaintext = decipher.update(ciphertext) + decipher.final
+```
+
+`Key#apply` generates a random nonce, derives the AES-256-GCM key and nonce, sets them on the cipher, and returns the 24-byte nonce. Pass the same nonce back for decryption. `Key` precomputes the AES key schedule and subkey, so reuse the same instance when encrypting multiple messages under the same key.
+
+## Alternative gems
+
+There's alternative gem `xaes_256_gcm`: https://github.com/vcsjones/xaes-256-gcm-ruby
+
+Key differences:
+
+- Smaller code footprint
+  - Leaving OpenSSL::Cipher setup to the user
+- Accumulated randomized test vectors are included in the test suite
+
+## License
+
+The gem is available as open source under the terms of the [BSD 1-Clause License](https://opensource.org/licenses/BSD-1-Clause).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/xaes_gcm/key.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module XaesGcm
+  class Key
+    def initialize(key)
+      raise ArgumentError, "key must be #{KEY_SIZE} bytes" unless key.bytesize == KEY_SIZE
+
+      @cipher = OpenSSL::Cipher.new('aes-256-ecb')
+      @cipher.encrypt
+      @cipher.padding = 0
+      @cipher.key = key
+
+      # L = AES-256-ECB_K(0^128)
+      l = @cipher.update("\x00" * 16) + @cipher.final
+
+      # K1: shift L left by 1 bit, XOR last byte with 0x87 if MSB was set
+      msb = l.getbyte(0) >> 7
+      k1_bytes = Array.new(16) do |i|
+        next_bit = (i < 15) ? (l.getbyte(i + 1) >> 7) : 0
+        ((l.getbyte(i) << 1) | next_bit) & 0b11111111
+      end
+      k1_bytes[-1] ^= 0b10000111 & -(msb & 1)
+      @k1 = k1_bytes.pack('C*')
+      @cipher.freeze
+    end
+
+    if HAVE_INSTANCE_VARIABLES_TO_INSPECT
+      def instance_variables_to_inspect = []
+    else
+      def inspect
+        "#<#{self.class}>"
+      end
+      alias to_s inspect
+    end
+
+    def enable_hazmat!
+      @enable_hazmat = true
+      self
+    end
+
+    def apply(cipher, nonce: OpenSSL::Random.random_bytes(NONCE_SIZE))
+      raise ArgumentError, "cipher must be AES-256-GCM" unless cipher.name == "AES-256-GCM"
+
+      dk = derive_key_raw(nonce:)
+      cipher.key = dk.key
+      cipher.iv = dk.nonce
+      nonce
+    end
+
+    def derive_key(nonce:)
+      raise RuntimeError, "derive_key is a hazmat API that exposes raw key material; call enable_hazmat! on the Key instance to use it directly" unless @enable_hazmat
+      derive_key_raw(nonce:)
+    end
+
+    private
+
+    def derive_key_raw(nonce:)
+      raise ArgumentError, "nonce must be #{NONCE_SIZE} bytes" unless nonce.bytesize == NONCE_SIZE
+
+      n12 = nonce.byteslice(0, 12)
+
+      m1 = "\x00\x01X\x00".b + n12
+      m2 = "\x00\x02X\x00".b + n12
+
+      m1_xored = xor_blocks(m1, @k1)
+      m2_xored = xor_blocks(m2, @k1)
+
+      cipher = @cipher.dup
+      derived = cipher.update(m1_xored + m2_xored)
+
+      DerivedKey.new(key: derived, nonce: nonce.byteslice(12, 12))
+    end
+
+    def xor_blocks(a, b)
+      a_bytes = a.unpack('C*')
+      b_bytes = b.unpack('C*')
+      a_bytes.length.times { |i| a_bytes[i] ^= b_bytes[i] }
+      a_bytes.pack('C*')
+    end
+  end
+end

data/lib/xaes_gcm/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module XaesGcm
+  VERSION = "0.1.1"
+end

data/lib/xaes_gcm.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "openssl"
+require_relative "xaes_gcm/version"
+
+module XaesGcm
+  class Error < StandardError; end
+
+  KEY_SIZE = 32
+  NONCE_SIZE = 24
+
+  # Detect instance_variables_to_inspect support (Ruby feature #13555)
+  HAVE_INSTANCE_VARIABLES_TO_INSPECT = begin
+    klass = Class.new do
+      def initialize = @secret = true
+      def instance_variables_to_inspect = []
+    end
+    !klass.new.inspect.include?("@secret")
+  end
+
+  DerivedKey = Data.define(:key, :nonce) do
+    # Data.define#inspect doesn't use instance_variables_to_inspect
+    def inspect
+      "#<#{self.class}>"
+    end
+    alias to_s inspect
+  end
+end
+
+require_relative "xaes_gcm/key"

data/sig/xaes_gcm.rbs

@@ -0,0 +1,28 @@
+module XaesGcm
+  VERSION: String
+  KEY_SIZE: Integer
+  NONCE_SIZE: Integer
+
+  class Error < StandardError
+  end
+
+  class DerivedKey
+    attr_reader key: String
+    attr_reader nonce: String
+
+    def self.new: (key: String, nonce: String) -> DerivedKey
+    def self.[]: (key: String, nonce: String) -> DerivedKey
+  end
+
+  class Key
+    def initialize: (String key) -> void
+    def enable_hazmat!: () -> self
+    def apply: (OpenSSL::Cipher cipher, ?nonce: String) -> String
+    def derive_key: (nonce: String) -> DerivedKey
+
+    private
+
+    def derive_key_raw: (nonce: String) -> DerivedKey
+    def xor_blocks: (String a, String b) -> String
+  end
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: xaes_gcm
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Sorah Fukumori
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Ruby implementation of XAES-256-GCM (c2sp.org/XAES-256-GCM), an extended-nonce
+  AEAD built on AES-256-GCM. Derives standard AES-256-GCM keys and nonces from 256-bit
+  keys and 192-bit nonces.
+email:
+- sorah@ivry.jp
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/xaes_gcm.rb
+- lib/xaes_gcm/key.rb
+- lib/xaes_gcm/version.rb
+- sig/xaes_gcm.rbs
+homepage: https://github.com/sorah/xaes_gcm
+licenses:
+- BSD-1-Clause
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/sorah/xaes_gcm
+  source_code_uri: https://github.com/sorah/xaes_gcm
+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: 3.6.9
+specification_version: 4
+summary: XAES-256-GCM extended-nonce AEAD key derivation
+test_files: []