xaes_256_gcm 0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3ef71e358ba4956fd8741d2f0a2b40c1fb43af910c83ed100f93e2f4b8115af5
+  data.tar.gz: 8121bbb3b12266bd94e4a516226a880d41d22719af8c273b1969fe3ac096503f
+SHA512:
+  metadata.gz: 2cdbd2478078a837754587ad5afb56d74904d55429a9764975eed58ec783c1060f96f52237247599bcfb7f7fed7bedcf0f9a8d170511906be12b42c8d1716e9d
+  data.tar.gz: f9e10e5a46c21b7c082c410a833119b6bc1220d578e20242fa250296b8e040870d7b7c81d82b363c364cee763841b29ff056db21ec0cd3f768879a902e36895f

data/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Kevin Jones
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/lib/xaes_256_gcm/errors.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+# typed: true
+
+module Xaes256Gcm
+  # A base error that all Xaes256Gcm errors derive from.
+  Error = Class.new(StandardError)
+
+  # Indicates that the provided key is invalid because it is nil or the incorrect length.
+  InvalidKeyError = Class.new(Error)
+
+  # Indicates that the provided nonce is invalid because it is nil or the incorrect length.
+  InvalidNonceError = Class.new(Error)
+
+  # Indicates that the provided ciphertext is invalid because the authentication tag failed to verify.
+  #
+  # This may indicate that one of the inputs to open was invalid, or the ciphertext has been modified.
+  InvalidCiphertextError = Class.new(Error)
+end

data/lib/xaes_256_gcm/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Xaes256Gcm
+  # The current version of the gem.
+  VERSION = "0.3"
+end

data/lib/xaes_256_gcm/xaes_256_gcm_cipher.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+##
+# The module containing XAES-256-GCM.
+module Xaes256Gcm
+
+  # Represents an instance of the XAES-256-GCM algorithm.
+  class Xaes256GcmCipher
+
+    # The nonce size of the algorithm, in bytes.
+    NONCE_SIZE = 24.freeze
+
+    # The key size of the algorithm, in bytes.
+    KEY_SIZE = 32.freeze
+
+    # The overhead of a ciphertext.
+    #
+    # When a plaintext is encrypted, the resulting ciphertext will be larger because of the authentication tag.
+    # This value indicates how much larger a ciphertext will be than a plaintext.
+    OVERHEAD = 16.freeze
+
+    BLOCK_SIZE = 16.freeze
+    private_constant :BLOCK_SIZE
+
+    # Creates a new instance of the XAES-256-GCM algorithm.
+    def initialize(key)
+      raise InvalidKeyError.new if key.nil? || !key.is_a?(String) || key.bytesize != KEY_SIZE
+
+      @aes = OpenSSL::Cipher::AES256.new(:ECB)
+      @aes.encrypt
+      @aes.padding = 0
+      @aes.key = key
+
+      k1init = "\0".b * BLOCK_SIZE
+      k1init = @aes.update(k1init)
+
+      msb = 0
+      k1 = k1init.bytes
+
+      for i in (k1.length - 1).downto(0)
+        msbC = msb
+        msb = k1[i] >> 7
+        k1[i] = ((k1[i] << 1) & 0b11111111) | msbC;
+      end
+
+      k1[-1] = k1[-1] ^ ((msb * 0b10000111) & 0b11111111)
+      @k1 = NoInspectBox.new(k1)
+    end
+
+    # Seals, or encrypts, a plaintext with a nonce.  Optional additional authenticated data can be provided.
+    def seal(plaintext, nonce, additionalData = nil)
+      raise InvalidNonceError if nonce.bytesize != NONCE_SIZE
+
+      key = derive_key(nonce.byteslice(0, 12))
+      gcm = OpenSSL::Cipher::AES256.new(:GCM)
+      gcm.encrypt
+      gcm.iv = nonce.byteslice(12, 12)
+      gcm.key = key
+      gcm.auth_data = additionalData unless additionalData.nil?
+
+      ciphertext = ""
+      ciphertext = gcm.update(plaintext) if plaintext.bytesize > 0
+      ciphertext += gcm.final
+      ciphertext + gcm.auth_tag
+    end
+
+    # Opens, or decrypts, a ciphertext with a nonce. Optional additional authenticated data can be provided.
+    def open(ciphertext, nonce, additionalData = nil)
+      ct_bytes = ciphertext.bytesize
+      raise InvalidNonceError if nonce.bytesize != NONCE_SIZE
+      raise InvalidCiphertextError if ciphertext.bytesize < OVERHEAD
+
+      tagless_ciphertext = ciphertext.byteslice(0, ct_bytes - OVERHEAD)
+      tag = ciphertext.byteslice(ct_bytes - OVERHEAD, OVERHEAD)
+
+      key = derive_key(nonce.byteslice(0, 12))
+      gcm = OpenSSL::Cipher::AES256.new(:GCM)
+      gcm.decrypt
+      gcm.iv = nonce.byteslice(12, 12)
+      gcm.key = key
+      gcm.auth_data = additionalData unless additionalData.nil?
+      gcm.auth_tag = tag
+
+      plaintext = ""
+      plaintext = gcm.update(tagless_ciphertext) if tagless_ciphertext.bytesize > 0
+
+      begin
+        plaintext += gcm.final
+      rescue OpenSSL::Cipher::CipherError => ex
+        raise InvalidCiphertextError.new
+      end
+
+      return plaintext
+    end
+
+    private
+
+    def derive_key(nonce)
+      nonce_bytes = nonce.bytes
+
+      # 0x58 is the ASCII value for "X"
+      m1 = [0, 1, 0x58, 0] + nonce_bytes
+      m2 = [0, 2, 0x58, 0] + nonce_bytes
+      xor(m1, @k1.value)
+      xor(m2, @k1.value)
+
+      m12 = (m1 + m2).pack("C*")
+      @aes.update(m12)
+    end
+
+    def xor(destination, other)
+      destination.each_with_index do |value, index|
+        destination[index] = destination[index] ^ other[index]
+      end
+    end
+
+    # This is just a smaller helper class that returns a redacted value for to_s and inspect.
+    # It exists to simply make sure any state on the instance is not accidentally logged or printed.
+    class NoInspectBox
+      def initialize(value)
+        @value = value
+      end
+
+      def value
+        @value
+      end
+
+      def inspect
+        return "hidden"
+      end
+
+      def to_s
+        return "hidden"
+      end
+    end
+
+    private_constant :NoInspectBox
+  end
+end

data/lib/xaes_256_gcm.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "xaes_256_gcm/errors.rb"
+require "xaes_256_gcm/version.rb"
+require "xaes_256_gcm/xaes_256_gcm_cipher.rb"

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: xaes_256_gcm
+version: !ruby/object:Gem::Version
+  version: '0.3'
+platform: ruby
+authors:
+- vcsjones
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.3'
+email: kevin@vcsjones.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- "./LICENSE.md"
+- "./lib/xaes_256_gcm.rb"
+- "./lib/xaes_256_gcm/errors.rb"
+- "./lib/xaes_256_gcm/version.rb"
+- "./lib/xaes_256_gcm/xaes_256_gcm_cipher.rb"
+homepage: https://github.com/vcsjones/xaes_256_gcm
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Implements the XAES-256-GCM algorithm.
+test_files: []