aesx 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1e8c7c99e1f1da63ccfe84212082b558d0b265a4ce48deba8d47793bb43559ce
+  data.tar.gz: 312f5a067623b83db638bfa13b2dee0c8b8632d2cd1f2ba991db814249f39ebb
+SHA512:
+  metadata.gz: 14b31c2cef73d6fadf793edf21d1b142edc0df8aa1db7f5d7d4d82704e5e1c162f2db71d9841f9b36366a6e720f8315dcd4c801e08e3eba13737817bb2527d3e
+  data.tar.gz: 30174c3791681e8d36c2bf5617d817e1d86f55d4e193f9ba9e01f0a4376ceb6beaa574cfa17b71c3642b50921250478243a68e43a2b297ea6a5aee80d5f6f2b2

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tom Lahti
+
+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/README.md

@@ -0,0 +1,156 @@
+# AESX
+
+A lightweight encryption library that provides an extended version of the popular AES gem interface with modern ciphers. The default cipher is AES-256-GCM. Other than the output formats being slightly extended to accommodate GCM authentication tags and compression indicators, this is a drop-in replacement for the AES gem. The API of that gem is fully implemented.  AESX adds a binary format which is more efficiently stored than base64, and compression.
+
+Security-wise, GCM ciphers provide tampering prevention and data integrity automatically. When using AESX, a regular password-style key of any length can be provided and a cryptographically secure encryption key will be generated using a key derivation function.
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'aesx'
+```
+
+And then execute:
+
+```
+$ bundle install
+```
+
+Or install it yourself:
+
+```
+$ gem install aesx
+```
+
+## Usage
+
+### Basic Encryption and Decryption
+
+```ruby
+require 'aesx'
+
+# Encrypt with a key
+key = AESX.key
+encrypted = AESX.encrypt("Secret message", key)
+
+# Decrypt
+decrypted = AESX.decrypt(encrypted, key)
+```
+
+### Using Different Ciphers
+
+```ruby
+# List available ciphers
+puts AESX.cipher_list
+
+# Use a specific cipher
+key = AESX.key(cipher: 'CHACHA20-POLY1305')
+encrypted = AESX.encrypt("Secret message", key, cipher: 'CHACHA20-POLY1305')
+decrypted = AESX.decrypt(encrypted, key, cipher: 'CHACHA20-POLY1305')
+```
+
+### Compression
+
+```ruby
+# Compression is enabled by default
+encrypted = AESX.encrypt("Large content to encrypt", key)
+
+# Disable compression
+encrypted = AESX.encrypt("Data to encrypt", key, compression: false)
+
+# Specify a compression algorithm
+encrypted = AESX.encrypt("Large content to encrypt", key, compression: :zstd)
+encrypted = AESX.encrypt("Large content to encrypt", key, compression: :snappy)
+encrypted = AESX.encrypt("Large content to encrypt", key, compression: :lz4)
+```
+
+#### Compression Information
+
+```ruby
+# Check what compression algorithms are available (what gems loaded)
+AESX.available_compression  # => [:zstd, :snappy, :lz4]
+
+# Check the default compression algorithm
+AESX.default_compression    # => :zstd
+```
+
+Available compression algorithms:
+- `:zstd` - High compression ratio with good speed (default if available)
+- `:snappy` - Fast compression with moderate ratio
+- `:lz4` - Very fast compression with lower ratio
+
+AESX attempts to load zstd, then snappy, then lz4.  The first one that loads successfully is the default.  If none of them load, compression is disabled.  Install gems to have compression available:
+
+| **Compression** | **Ruby** gem | **JRuby** gem  |
+|:---------------:|:------------:|:--------------:|
+| :zstd           | zstd-ruby    | zstandard-ruby |
+| :snappy         | snappy       | jruby-snappy   |
+| :lz4            | lz4-ruby     | jruby-lz4      |
+### Output Formats
+
+AESX supports multiple output formats:
+
+```ruby
+# Base64 encoded string (default)
+encrypted = AESX.encrypt("Secret message", key, format: :base_64)
+
+# Raw binary output
+encrypted = AESX.encrypt("Secret message", key, format: :binary)
+
+# Array of components [iv, ciphertext, auth_tag, compression_algorithm]
+encrypted = AESX.encrypt("Secret message", key, format: :plain)
+```
+
+### Advanced Usage
+
+You don’t have to supply the cipher with every operation. You can instead create an object configured for a particular cipher, and then reuse that object for multiple operations.
+
+```ruby
+# Create an AESX object for multiple operations
+cipher = AESX::AESX.new(key, {
+  cipher: 'AES-192-GCM',
+  padding: true,
+  compression: :snappy,
+  auth_data: "additional authentication data" # for GCM mode
+})
+
+encrypted1 = cipher.encrypt("Message 1")
+encrypted2 = cipher.encrypt("Message 2")
+```
+
+## Supported Ciphers
+
+- AES-128/192/256-GCM
+- AES-128/192/256-CTR
+- ARIA-128/192/256-CTR[^1]
+- SM4-CTR[^2]
+- SM4-GCM[^2]
+- CHACHA20-POLY1305
+
+The actual list depends on your OpenSSL version. Use `AESX.cipher_list` to see available ciphers.
+
+[^1]: ARIA is a block cipher developed by South Korean cryptographers and is widely used in South Korea, particularly in government and financial systems.
+
+[^2]: SM4 is the Chinese national standard block cipher algorithm and is commonly used within China in government and regulated industries.
+
+## Cross-Platform Compatibility
+
+The compression information is stored as part of the encrypted data, so files encrypted on one system can be decrypted on another, even if different compression libraries are available. If the required compression algorithm is not available during decryption, a clear error message will be displayed. Compression can also be completely disabled.
+
+## Notes on Security
+
+- GCM and CHACHA20-POLY1305 provide authenticated encryption, meaning they detect tampering with the encrypted data
+- When using CTR mode, no authentication is provided
+- You can use AESX to provide a secure random key (generated with `AESX.key`)
+- **CRITICAL SECURITY WARNING**: Never store the encryption key with the encrypted data
+  - Storing key and encrypted data together compromises all encryption
+  - Manage keys separately using secure key management practices
+- When providing your own key via a password, key derivation uses PBKDF2 with a deterministic salt derived from the input
+  - Ensures consistent key stretching across systems
+  - Requires OpenSSL >= 1.0.0
+  - The same input/password will always produce the same derived key
+
+## License
+
+This library is available as open source under the terms of the MIT License.

data/lib/aesx.rb

@@ -0,0 +1,391 @@
+# Copyright (c) 2025 Tom Lahti
+# MIT License
+
+require 'openssl'
+require 'base64'
+require 'digest'
+require_relative 'compression'
+
+# AESX - AES eXtended encryption library
+#
+# A lightweight encryption library that provides an extended version of 
+# the popular AES gem interface with modern ciphers. The default cipher 
+# is AES-256-GCM.
+#
+# @example Basic usage
+#   key = AESX.key
+#   encrypted = AESX.encrypt("Secret message", key)
+#   decrypted = AESX.decrypt(encrypted, key)
+#
+# @example Using different ciphers
+#   key = AESX.key(cipher: 'CHACHA20-POLY1305')
+#   encrypted = AESX.encrypt("Secret message", key, cipher: 'CHACHA20-POLY1305')
+#
+# @example With compression
+#   encrypted = AESX.encrypt("Large message", key, compression: :zstd)
+#
+module AESX
+
+  # Mapping of cipher names to [key_length, iv_length]
+  CIPHER_SPECS = {
+    'AES-128-CTR'    => [16, 16],
+    'AES-192-CTR'    => [24, 16],
+    'AES-256-CTR'    => [32, 16],
+    'AES-128-GCM'    => [16, 12],
+    'AES-192-GCM'    => [24, 12],
+    'AES-256-GCM'    => [32, 12],
+    'ARIA-128-CTR'   => [16, 16],
+    'ARIA-192-CTR'   => [24, 16],
+    'ARIA-256-CTR'   => [32, 16],
+    'SM4-CTR'        => [16, 16],
+    'SM4-GCM'        => [16, 12],
+    'CHACHA20-POLY1305' => [32, 12]
+  }.freeze
+
+  class << self
+
+    # Returns a list of supported ciphers available in the current OpenSSL installation
+    #
+    # @return [Array<String>] List of available cipher names
+    def cipher_list
+      openssl_ciphers = OpenSSL::Cipher.ciphers.map(&:upcase)
+      CIPHER_SPECS.keys & openssl_ciphers    
+    end
+
+    # Encrypts plaintext using the specified key and options
+    #
+    # @param plaintext [String] The data to encrypt
+    # @param key [String] The encryption key
+    # @param opts [Hash] Options for encryption
+    # @option opts [Symbol] :format (:base_64) Output format - :base_64, :binary, or :plain
+    # @option opts [String] :cipher ('AES-256-GCM') Cipher to use
+    # @option opts [String] :iv (random) Initialization vector
+    # @option opts [Boolean, Integer] :padding (true) Enable padding
+    # @option opts [String] :auth_data ('') Additional authentication data for GCM mode
+    # @option opts [Boolean, Symbol] :compression (default algorithm) Compression option
+    #
+    # @return [String, Array] Encrypted data in the specified format
+    def encrypt(plaintext, key, opts={})
+      cipher = AESX.new(key, opts)
+      cipher.encrypt(plaintext)
+    end
+
+    # Decrypts ciphertext using the specified key and options
+    #
+    # @param ciphertext [String, Array] The encrypted data to decrypt
+    # @param key [String] The encryption key
+    # @param opts [Hash] Options for decryption (most are auto-detected)
+    # @option opts [Symbol] :format (auto-detected) Input format
+    # @option opts [String] :cipher ('AES-256-GCM') Cipher to use
+    # @option opts [Boolean, Integer] :padding (true) Enable padding
+    # @option opts [String] :auth_data ('') Additional authentication data for GCM mode
+    #
+    # @return [String] The decrypted plaintext
+    # @raise [OpenSSL::Cipher::CipherError] If decryption fails (wrong key, tampered data)
+    def decrypt(ciphertext, key, opts={})
+      cipher = AESX.new(key, opts)
+      cipher.decrypt(ciphertext)
+    end
+
+    # Generates a random key of appropriate length for the specified cipher
+    #
+    # @param length [Integer, nil] Key length in bits, or nil to use cipher default
+    # @param format [Symbol] Output format - :plain or :base_64
+    # @param cipher [String] Cipher to determine key length
+    #
+    # @return [String] A random key in the specified format
+    def key(length = nil, format = :plain, cipher: 'AES-256-GCM')
+      key_length = length ? length / 8 : CIPHER_SPECS[cipher.upcase][0]
+      key = OpenSSL::Random.random_bytes(key_length)
+      format == :base_64 ? Base64.encode64(key).chomp : key
+    end
+
+    # Generates a random initialization vector of appropriate length for the specified cipher
+    #
+    # @param format [Symbol] Output format - :plain or :base_64
+    # @param cipher [String] Cipher to determine IV length
+    #
+    # @return [String] A random IV in the specified format
+    def iv(format = :plain, cipher: 'AES-256-GCM')
+      iv_length = CIPHER_SPECS[cipher.upcase][1]
+      iv = OpenSSL::Random.random_bytes(iv_length)
+      format == :base_64 ? Base64.encode64(iv).chomp : iv
+    end
+    
+    # Returns the default compression algorithm
+    #
+    # @return [Symbol, nil] The symbol representing the default algorithm, or nil if none available
+    def default_compression
+      AESCompression.default_algorithm
+    end
+    
+    # Returns an array of available compression algorithms
+    #
+    # @return [Array<Symbol>] Symbols representing available compression algorithms
+    def available_compression
+      AESCompression.available_algorithms
+    end
+
+  end
+
+  # Main AESX class for encryption and decryption operations
+  class AESX
+    attr :key, :iv, :cipher, :auth_tag, :options
+
+    # Creates a new AESX cipher instance
+    #
+    # @param key [String] The encryption key
+    # @param opts [Hash] Options for the cipher
+    # @option opts [Symbol] :format (:base_64) Default output format
+    # @option opts [String] :cipher ('AES-256-GCM') Cipher to use
+    # @option opts [String] :iv (random) Initialization vector
+    # @option opts [Boolean, Integer] :padding (true) Enable padding
+    # @option opts [String] :auth_data ('') Additional authentication data for GCM mode
+    # @option opts [Boolean, Symbol] :compression (default algorithm) Compression option
+    #
+    # @raise [ArgumentError] If an unsupported cipher is specified
+    def initialize(key, opts={})
+      # allow laziness
+      if opts.key?(:compress)
+        opts[:compression] = opts.delete(:compress)
+      end      
+      @options = {
+        format: :base_64,        # Default output format for encryption
+        cipher: "AES-256-GCM",   # GCM mode
+        iv: nil,                 # IV will be generated if not passed
+        padding: true,           # OpenSSL padding support
+        auth_data: "",           # additional authenication data (AAD)
+        compression: AESCompression.default_algorithm # Default to the default algorithm
+      }.merge!(opts)
+
+      unless ::AESX.cipher_list.include?(@options[:cipher].upcase)
+        raise ArgumentError, "Unsupported cipher #{@options[:cipher]}. Supported ciphers: #{::AESX.cipher_list.join(', ')}"
+      end
+
+      @key = normalize_key(key, @options[:cipher])
+      @iv = @options[:iv] || ::AESX.iv(cipher: @options[:cipher])
+
+      case @options[:padding]
+      when true
+        @options[:padding] = 1
+      when false
+        @options[:padding] = 0
+      end
+
+      @cipher = OpenSSL::Cipher.new(@options[:cipher])
+    end
+
+    # Encrypts plaintext using the configured cipher and options
+    #
+    # @param plaintext [String] The data to encrypt
+    # @param opts [Hash] Options to override instance defaults
+    # @option opts [Symbol] :format Output format override
+    # @option opts [String] :iv Override the instance IV
+    # @option opts [Boolean, Symbol] :compression Compression override
+    #
+    # @return [String, Array] Encrypted data in the specified format
+    def encrypt(plaintext, opts = {})
+      @cipher.encrypt
+      @cipher.key = @key
+      iv = opts[:iv] || @iv
+      @cipher.iv = iv
+      @cipher.padding = @options[:padding]
+      @cipher.auth_data = @options[:auth_data] unless @options[:cipher] =~ /CTR/i
+
+      # Apply compression if enabled
+      compressed_data = plaintext
+      compression_algorithm = nil
+
+      # Get compression option from opts or fallback to options
+      compression = opts.key?(:compression) ? opts[:compression] : @options[:compression]
+      
+      # If compression is a symbol or truthy value (but not true), use it as the algorithm
+      if compression.is_a?(Symbol) || (compression && compression != true)
+        # Check if specified algorithm is available
+        if compression.is_a?(Symbol) && !AESCompression.algorithm_available?(compression)
+          raise ArgumentError, "Compression algorithm '#{compression}' is not available. Installed algorithms: #{AESCompression.available_algorithms.join(', ')}"
+        end
+        compressed_data, compression_algorithm = AESCompression.compress(plaintext, compression)
+      # If compression is true or nil, use default algorithm
+      elsif compression.nil? || compression == true
+        compressed_data, compression_algorithm = AESCompression.compress(plaintext, AESCompression.default_algorithm)
+      # Otherwise, no compression (compression == false)
+      end
+
+      ciphertext = @cipher.update(compressed_data) + @cipher.final
+      auth_tag = @cipher.auth_tag unless @options[:cipher] =~ /CTR/i
+
+      fmt = opts[:format] || @options[:format]
+      case fmt
+      when :base_64
+        iv_b64 = Base64.encode64(iv).chomp
+        ciphertext_b64 = Base64.encode64(ciphertext).chomp
+        auth_tag_b64 = auth_tag ? Base64.encode64(auth_tag).chomp : nil
+        
+        # Add compression flag
+        comp_flag = compression_algorithm ? AESCompression::ALGORITHM_IDS[compression_algorithm].to_s : "0"
+        
+        if auth_tag_b64
+          result = "#{iv_b64}$#{ciphertext_b64}$#{auth_tag_b64}$#{comp_flag}"
+        else
+          result = "#{iv_b64}$#{ciphertext_b64}$$#{comp_flag}"  # Empty auth_tag field for CTR mode
+        end
+        result.force_encoding(Encoding::US_ASCII)
+      when :binary
+        # IV length has a range of 7-16, which we can get into 3 bits
+        # auth_tag length is 0-16, variable in CCM
+        auth_tag_size = auth_tag ? auth_tag.bytesize : 0
+        packed_lengths = ((iv.bytesize - 7) << 5) | (auth_tag_size & 0x1F)
+        
+        # Add a second byte for compression algorithm
+        compression_byte = AESCompression::ALGORITHM_IDS[compression_algorithm] || 0
+        
+        if auth_tag
+          pack_format = "CC a#{iv.bytesize} a* a#{auth_tag.bytesize}"
+          [packed_lengths, compression_byte, iv, ciphertext, auth_tag].pack(pack_format)
+        else
+          pack_format = "CC a#{iv.bytesize} a*"
+          [packed_lengths, compression_byte, iv, ciphertext].pack(pack_format)
+        end
+      else
+        [iv, ciphertext, auth_tag, compression_algorithm]
+      end
+    end
+
+    # Decrypts ciphertext using the configured cipher and options
+    #
+    # @param encrypted_data [String, Array] The encrypted data to decrypt
+    # @param opts [Hash] Options to override instance defaults
+    # @option opts [Symbol] :format Format override (auto-detected if not specified)
+    # @option opts [Boolean, Integer] :padding Padding override
+    # @option opts [String] :auth_data Authentication data override for GCM mode
+    #
+    # @return [String] The decrypted plaintext
+    # @raise [OpenSSL::Cipher::CipherError] If decryption fails
+    # @raise [RuntimeError] If decompression fails or algorithm is unavailable
+    def decrypt(encrypted_data, opts = {})
+      # ignore provided opts[:format] and auto-detect
+      compression_algorithm = nil
+
+      case encrypted_data
+      when Array
+        opts[:format] = :plain
+        iv, ciphertext, auth_tag, compression_algorithm = encrypted_data
+      else
+        opts[:format] = :binary
+
+        # unless it's Base64 encoded?
+        parts = encrypted_data.split('$')
+        if parts.size.between?(3, 4)
+          all_base64 = parts.all? { |str| str.nil? || str.empty? || str =~ /^[A-Za-z0-9+\/=]*$/ }
+          if all_base64
+            opts[:format] = :base_64
+          end
+        end
+      end
+
+      case opts[:format]
+      when :base_64
+        parts = encrypted_data.split('$')
+        iv_b64 = parts[0]
+        ciphertext_b64 = parts[1]
+        auth_tag_b64 = parts[2] if parts.size >= 3 && !parts[2].nil? && !parts[2].empty?
+        compression_code = parts[3] if parts.size >= 4
+        
+        iv = Base64.decode64(iv_b64)
+        ciphertext = Base64.decode64(ciphertext_b64)
+        auth_tag = auth_tag_b64 ? Base64.decode64(auth_tag_b64) : nil
+        
+        # Determine compression algorithm from the code
+        if compression_code && compression_code != "0"
+          algorithm_id = compression_code.to_i
+          compression_algorithm = AESCompression::ID_TO_ALGORITHM[algorithm_id]
+        end
+      when :binary
+        # Extract the first byte which contains IV and auth tag lengths
+        lengths = encrypted_data.unpack1('C')
+        
+        # Extract the second byte which contains compression info
+        compression_byte = encrypted_data.unpack('CC')[1]
+        
+        # Calculate IV length and auth tag length
+        iv_len = ((lengths >> 5) & 0x07) + 7
+        tag_len = lengths & 0x1F
+        
+        # Extract IV, ciphertext, and auth tag
+        iv = encrypted_data[2, iv_len] # 2 bytes of header now
+        
+        if tag_len > 0
+          auth_tag = encrypted_data[-tag_len, tag_len]
+          # Ciphertext starts after header and IV, ends before auth tag
+          ciphertext = encrypted_data[(2 + iv_len)...-tag_len]
+        else
+          auth_tag = nil
+          ciphertext = encrypted_data[(2 + iv_len)..]
+        end
+        
+        # Get compression algorithm
+        compression_algorithm = AESCompression::ID_TO_ALGORITHM[compression_byte] if compression_byte != 0
+      else
+        iv, ciphertext, auth_tag, compression_algorithm = encrypted_data
+      end
+
+      @cipher.decrypt
+      @cipher.key = @key
+      @cipher.iv = iv
+      unless @options[:cipher] =~ /CTR/i
+        @cipher.auth_tag = auth_tag if auth_tag
+        @cipher.auth_data = opts[:auth_data] || @options[:auth_data]
+      end
+      @cipher.padding = opts[:padding] || @options[:padding]
+
+      decrypted_data = @cipher.update(ciphertext) + @cipher.final
+      
+      # Apply decompression if data was compressed
+      if compression_algorithm
+        begin
+          decrypted_data = AESCompression.decompress(decrypted_data, compression_algorithm)
+        rescue => e
+          raise "Error decompressing data: #{e.message}. Algorithm #{compression_algorithm} may not be installed."
+        end
+      end
+
+      decrypted_data
+    end
+
+    alias_method :random_iv, :iv
+    alias_method :random_key, :key
+
+    # Normalizes an encryption key to the correct length and format
+    #
+    # Requires OpenSSL >= 1.0.0 for PBKDF2 key derivation support.
+    #
+    # If the key is already the correct length, it's returned as-is.
+    # If it's a hex string, it's converted to binary.
+    # For other keys, PBKDF2 is used for deterministic key derivation
+    #
+    # @param key [String] The encryption key to normalize
+    # @param cipher [String] Cipher to determine required key length (default: 'AES-256-GCM')
+    # @param iterations [Integer] Number of iterations for PBKDF2 key derivation (default: 10000)
+    #
+    # @return [String] Normalized key of the correct length for the cipher
+    # @raise [RuntimeError] If OpenSSL version is less than 1.0.0
+    # @api private
+    def normalize_key(key, cipher = 'AES-256-GCM', iterations: 10000)
+      key_length = CIPHER_SPECS[cipher.upcase][0]
+      return key if key.bytesize == key_length
+            
+      if key.match?(/\A[0-9a-fA-F]+\z/) # is it a hex string?
+        key = key.unpack('a2' * key_length).map { |x| x.hex }.pack('c' * key_length)
+      else
+        # Derive salt deterministically from the key
+        salt = Digest::SHA256.digest(key)[0,16]
+        # Use PBKDF2 for key derivation
+        key = OpenSSL::PKCS5.pbkdf2_hmac(key,salt,iterations,key_length,OpenSSL::Digest::SHA256.new)
+      end
+      
+      key
+    end
+
+  end
+end

data/lib/compression.rb

@@ -0,0 +1,129 @@
+# Copyright (c) 2025 Tom Lahti
+# MIT License
+
+module AESCompression
+  @algorithms = {}
+  @default_algorithm = nil
+
+  # Compression algorithm identifiers for serialization
+  ALGORITHM_IDS = {
+    nil => 0,      # No compression
+    :zstd => 1,
+    :snappy => 2,
+    :lz4 => 3
+  }.freeze
+
+  ID_TO_ALGORITHM = ALGORITHM_IDS.invert.freeze
+
+  # Try to load zstd with platform-specific support
+  begin
+    if defined?(JRUBY_VERSION)
+      require 'zstandard-ruby'
+      @algorithms[:zstd] = {
+        compress: ->(data) { Zstandard.compress(data) },
+        decompress: ->(data) { Zstandard.decompress(data) }
+      }
+      @default_algorithm = :zstd
+    else
+      require 'zstd-ruby'
+      @algorithms[:zstd] = {
+        compress: ->(data) { Zstd.compress(data) },
+        decompress: ->(data) { Zstd.decompress(data) }
+      }
+      @default_algorithm = :zstd
+    end
+  rescue LoadError
+    # zstd not available
+  end
+
+  # Try to load snappy with platform-specific support
+  begin
+    if defined?(JRUBY_VERSION)
+      require 'jruby-snappy'
+      @algorithms[:snappy] = {
+        compress: ->(data) { Snappy.deflate(data) },
+        decompress: ->(data) { Snappy.inflate(data) }
+      }
+    else
+      require 'snappy'
+      @algorithms[:snappy] = {
+        compress: ->(data) { Snappy.deflate(data) },
+        decompress: ->(data) { Snappy.inflate(data) }
+      }
+    end
+    @default_algorithm ||= :snappy
+  rescue LoadError
+    # snappy not available
+  end
+
+  # Try to load lz4 with platform-specific support
+  begin
+    if defined?(JRUBY_VERSION)
+      require 'jruby-lz4'
+      @algorithms[:lz4] = {
+        compress: ->(data) { LZ4::compress(data) },
+        decompress: ->(data) { LZ4::uncompress(data, data.bytesize * 3) } # Estimate output size
+      }
+    else
+      require 'lz4-ruby'
+      @algorithms[:lz4] = {
+        compress: ->(data) { LZ4.compress(data) },
+        decompress: ->(data) { LZ4.decompress(data) }
+      }
+    end
+    @default_algorithm ||= :lz4
+  rescue LoadError
+    # lz4 not available
+  end
+
+  def self.available_algorithms
+    @algorithms.keys
+  end
+
+  def self.algorithm_available?(algorithm)
+    @algorithms.key?(algorithm)
+  end
+
+  def self.default_algorithm
+    @default_algorithm
+  end
+
+  def self.compress(data, algorithm = nil)
+    return [data, nil] unless data && !data.empty?
+
+    algorithm ||= @default_algorithm
+    return [data, nil] unless algorithm && @algorithms[algorithm]
+
+    begin
+      compressed = @algorithms[algorithm][:compress].call(data)
+      [compressed, algorithm]
+    rescue => e
+      # Fallback to uncompressed data on error
+      [data, nil]
+    end
+  end
+
+  def self.decompress(data, algorithm)
+    return data unless data && !data.empty? && algorithm
+    
+    # Check if algorithm is a valid symbol we recognize
+    unless ID_TO_ALGORITHM.values.include?(algorithm)
+      raise "Unknown compression algorithm identifier: #{algorithm}"
+    end
+    
+    # Check if the algorithm is available
+    unless @algorithms[algorithm]
+      raise "Compression algorithm #{algorithm} required but not available. Please install the required gem."
+    end
+
+    begin
+      @algorithms[algorithm][:decompress].call(data)
+    rescue => e
+      raise "Error decompressing data: #{e.message}. The #{algorithm} library may not be installed correctly."
+    end
+  end
+
+  def self.enabled?
+    !@algorithms.empty?
+  end
+end

data/test_aesx.rb

@@ -0,0 +1,429 @@
+#!/usr/local/bin/ruby
+
+# Copyright (c) 2025 Tom Lahti
+# MIT License
+
+require 'minitest/autorun'
+require 'aesx'
+require 'digest'
+require 'fileutils'
+require 'securerandom'
+
+class TestAESX < Minitest::Test
+  def setup
+    @key = SecureRandom.hex(32)
+    @plaintext = "This is a test message!"
+  end
+
+  def test_key_normalization_with_hex_key
+    hex_key = "a3dcb4b56faed1b20f43aee7e20b40513bf6c5f764c831b95372e142ebff4236"
+    cipher = AESX::AESX.new(hex_key)
+    normalized_key = cipher.instance_variable_get(:@key)
+    assert_equal 32, normalized_key.bytesize, "The normalized key should be 32 bytes."
+  end
+
+  def test_key_normalization_with_short_hex_key
+    short_hex_key = "a3dcb4b56faed1b20f43aee7e20b40"
+    cipher = AESX::AESX.new(short_hex_key)
+    normalized_key = cipher.instance_variable_get(:@key)
+    assert_equal 32, normalized_key.bytesize, "The normalized key should be padded to 32 bytes."
+  end
+
+  def test_key_normalization_with_long_hex_key
+    long_hex_key = "a3dcb4b56faed1b20f43aee7e20b40513bf6c5f764c831b95372e142ebff4236a3dcb4b56faed1b20f43aee7e20b4051"
+    cipher = AESX::AESX.new(long_hex_key)
+    normalized_key = cipher.instance_variable_get(:@key)
+    assert_equal 32, normalized_key.bytesize, "The normalized key should be truncated to 32 bytes."
+  end
+
+  def test_key_normalization_with_non_hex_key
+    password_key = "my password"
+    cipher = AESX::AESX.new(password_key)
+    normalized_key = cipher.instance_variable_get(:@key)
+    assert_equal 32, normalized_key.bytesize, "The SHA-256 hashed key should be 32 bytes."
+  end
+
+  def test_encrypt_decrypt_with_base64_format
+    encrypted = AESX.encrypt(@plaintext, @key, format: :base_64)
+    decrypted = AESX.decrypt(encrypted, @key, format: :base_64)
+
+    assert_equal @plaintext, decrypted, "Decrypted text should match the original plaintext."
+  end
+
+  def test_encrypt_decrypt_with_binary_format
+    encrypted = AESX.encrypt(@plaintext, @key, format: :binary)
+    decrypted = AESX.decrypt(encrypted, @key, format: :binary)
+
+    assert_equal @plaintext, decrypted, "Decrypted text should match the original plaintext."
+  end
+
+  def test_encrypt_decrypt_with_plain_format
+    encrypted = AESX.encrypt(@plaintext, @key, format: :plain)
+    decrypted = AESX.decrypt(encrypted, @key, format: :plain)
+
+    assert_equal @plaintext, decrypted, "Decrypted text should match the original plaintext."
+  end
+
+  def test_encrypt_decrypt_with_random_iv
+    encrypted = AESX.encrypt(@plaintext, @key, format: :base_64)
+    decrypted = AESX.decrypt(encrypted, @key, format: :base_64)
+
+    assert_equal @plaintext, decrypted, "Decrypted text should match the original plaintext when using a random IV."
+  end
+
+  def test_encrypt_decrypt_with_32_byte_key
+    key_32_bytes = "a" * 32  # exactly 32 bytes
+    encrypted = AESX.encrypt(@plaintext, key_32_bytes, format: :base_64)
+    decrypted = AESX.decrypt(encrypted, key_32_bytes, format: :base_64)
+
+    assert_equal @plaintext, decrypted, "Decrypted text should match the original plaintext when using a 32-byte key."
+  end
+
+  def test_invalid_cipher_text
+    # Generate a valid encrypted string first
+    valid_encrypted = AESX.encrypt("test", @key, format: :base_64)
+    # Corrupt the ciphertext portion
+    parts = valid_encrypted.split('$')
+    parts[1] = "invalidciphertext"
+    invalid_encrypted = parts.join('$')
+
+    assert_raises(OpenSSL::Cipher::CipherError) do
+      AESX.decrypt(invalid_encrypted, @key, format: :base_64)
+    end
+  end
+
+  def test_invalid_decryption_format
+    invalid_encrypted = "invalidcipherdata"
+    assert_raises(ArgumentError) do
+      AESX.decrypt(invalid_encrypted, @key, format: :base_64)
+    end
+  end  
+
+  def test_decrypt_with_invalid_key
+    invalid_key = "invalidkey123456"  # Invalid key that won't match
+    encrypted = AESX.encrypt(@plaintext, @key, format: :base_64)
+
+    # Try to decrypt with an invalid key
+    decrypted = nil
+    assert_raises(OpenSSL::Cipher::CipherError) do
+      decrypted = AESX.decrypt(encrypted, invalid_key, format: :base_64)
+    end
+
+    refute_equal @plaintext, decrypted, "Decryption with an invalid key should not yield the original plaintext."
+  end
+
+  def test_key_generation_default
+    key = AESX.key
+    assert_equal 32, key.bytesize, "Default key should be 32 bytes."
+  end
+
+  def test_key_generation_with_length
+    key = AESX.key(128)
+    assert_equal 16, key.bytesize, "128-bit key should be 16 bytes."
+  end
+
+  def test_key_generation_with_base64
+    key = AESX.key(256, :base_64)
+    decoded = Base64.decode64(key)
+    assert_equal 32, decoded.bytesize, "Base64 key should decode to 32 bytes."
+  end
+
+  def test_iv_generation_default
+    iv = AESX.iv
+    assert_equal 12, iv.bytesize, "Default IV should be 12 bytes."
+  end
+
+  def test_iv_generation_with_base64
+    iv = AESX.iv(:base_64)
+    decoded = Base64.decode64(iv)
+    assert_equal 12, decoded.bytesize, "Base64 IV should decode to 12 bytes."
+  end
+
+  def test_random_iv_and_key_methods
+    aes = AESX::AESX.new("testkey" * 4)  # 32-byte key
+    iv = aes.random_iv
+    key = aes.random_key
+    assert_equal 12, iv.bytesize, "Random IV should be 12 bytes."
+    assert_equal 32, key.bytesize, "Random key should be 32 bytes."
+  end
+
+  def test_encrypt_decrypt_with_short_aes
+    plaintext = "Secret message"
+    cipher = 'AES-128-GCM'
+    key = AESX.key(cipher: cipher)
+
+    encrypted = AESX.encrypt(plaintext, key, cipher: cipher)
+    decrypted = AESX.decrypt(encrypted, key, cipher: cipher)
+
+    assert_equal plaintext, decrypted, "Decrypted text should match original with custom cipher."
+  end
+
+  def test_encrypt_decrypt_with_ctr
+    plaintext = "Secret message"
+    cipher = 'AES-256-CTR'
+    key = AESX.key(cipher: cipher)
+
+    encrypted = AESX.encrypt(plaintext, key, cipher: cipher)
+    decrypted = AESX.decrypt(encrypted, key, cipher: cipher)
+
+    assert_equal plaintext, decrypted, "Decrypted text should match original with custom cipher."
+  end
+
+  def test_encrypt_decrypt_with_aria
+    plaintext = "Secret message"
+    cipher = 'ARIA-256-CTR'
+    key = AESX.key(cipher: cipher)
+
+    encrypted = AESX.encrypt(plaintext, key, cipher: cipher)
+    decrypted = AESX.decrypt(encrypted, key, cipher: cipher)
+
+    assert_equal plaintext, decrypted, "Decrypted text should match original with custom cipher."
+  end
+
+  def test_encrypt_decrypt_with_sm4
+    plaintext = "Secret message"
+    cipher = 'SM4-CTR'
+    key = AESX.key(cipher: cipher)
+
+    encrypted = AESX.encrypt(plaintext, key, cipher: cipher)
+    decrypted = AESX.decrypt(encrypted, key, cipher: cipher)
+
+    assert_equal plaintext, decrypted, "Decrypted text should match original with custom cipher."
+  end
+
+  def test_encrypt_decrypt_with_chacha
+    plaintext = "Secret message"
+    cipher = 'chacha20-poly1305'
+    key = AESX.key(cipher: cipher)
+
+    encrypted = AESX.encrypt(plaintext, key, cipher: cipher)
+    decrypted = AESX.decrypt(encrypted, key, cipher: cipher)
+
+    assert_equal plaintext, decrypted, "Decrypted text should match original with custom cipher."
+  end
+
+  def test_disable_compression_with_all_formats
+    # Create a larger string to better demonstrate compression
+    large_plaintext = "This is a test message with repetitive content. " * 100
+    
+    # Test with each format
+    [:base_64, :binary, :plain].each do |format|
+      encrypted = AESX.encrypt(large_plaintext, @key, format: format, compression: false)
+      decrypted = AESX.decrypt(encrypted, @key)
+      
+      assert_equal large_plaintext, decrypted, "Decryption should match original plaintext with format #{format} and compression disabled"
+    end
+  end
+
+  def test_zstd_compression_with_all_formats
+    # Skip if zstd is not available
+    skip "Zstd compression not available" unless AESCompression.algorithm_available?(:zstd)
+    
+    large_plaintext = "This is a test message with repetitive content. " * 100
+    
+    # Test with each format
+    [:base_64, :binary, :plain].each do |format|
+      encrypted = AESX.encrypt(large_plaintext, @key, format: format, compression: :zstd)
+      decrypted = AESX.decrypt(encrypted, @key)
+      
+      assert_equal large_plaintext, decrypted, "Decryption should match original plaintext with format #{format} and zstd compression"
+    end
+  end
+
+  def test_snappy_compression_with_all_formats
+    # Skip if snappy is not available
+    skip "Snappy compression not available" unless AESCompression.algorithm_available?(:snappy)
+    
+    large_plaintext = "This is a test message with repetitive content. " * 100
+    
+    # Test with each format
+    [:base_64, :binary, :plain].each do |format|
+      encrypted = AESX.encrypt(large_plaintext, @key, format: format, compression: :snappy)
+      decrypted = AESX.decrypt(encrypted, @key)
+      
+      assert_equal large_plaintext, decrypted, "Decryption should match original plaintext with format #{format} and snappy compression"
+    end
+  end
+
+  def test_lz4_compression_with_all_formats
+    # Skip if lz4 is not available
+    skip "LZ4 compression not available" unless AESCompression.algorithm_available?(:lz4)
+    
+    large_plaintext = "This is a test message with repetitive content. " * 100
+    
+    # Test with each format
+    [:base_64, :binary, :plain].each do |format|
+      encrypted = AESX.encrypt(large_plaintext, @key, format: format, compression: :lz4)
+      decrypted = AESX.decrypt(encrypted, @key)
+      
+      assert_equal large_plaintext, decrypted, "Decryption should match original plaintext with format #{format} and lz4 compression"
+    end
+  end
+
+  def test_default_compression_with_all_formats
+    # Skip if no compression algorithms are available
+    skip "No compression algorithms available" unless AESCompression.default_algorithm
+    
+    large_plaintext = "This is a test message with repetitive content. " * 100
+    
+    # Test with each format
+    [:base_64, :binary, :plain].each do |format|
+      # Using default compression (nil or not specified)
+      encrypted = AESX.encrypt(large_plaintext, @key, format: format)
+      decrypted = AESX.decrypt(encrypted, @key)
+      
+      assert_equal large_plaintext, decrypted, "Decryption should match original plaintext with format #{format} and default compression"
+    end
+  end
+
+  def test_invalid_compression_algorithm
+    assert_raises(ArgumentError) do
+      AESX.encrypt("test", @key, compression: :invalid_algorithm)
+    end
+  end
+
+  def test_cross_format_compatibility
+    # Skip if no compression algorithms are available
+    skip "No compression algorithms available" unless AESCompression.default_algorithm
+    
+    large_plaintext = "This is a test message with repetitive content. " * 50
+    
+    # Test encrypting with one format and decrypting with auto-detection
+    encrypted_base64 = AESX.encrypt(large_plaintext, @key, format: :base_64)
+    encrypted_binary = AESX.encrypt(large_plaintext, @key, format: :binary)
+    encrypted_plain = AESX.encrypt(large_plaintext, @key, format: :plain)
+    
+    # Decrypt all without specifying format (should auto-detect)
+    decrypted_from_base64 = AESX.decrypt(encrypted_base64, @key)
+    decrypted_from_binary = AESX.decrypt(encrypted_binary, @key)
+    decrypted_from_plain = AESX.decrypt(encrypted_plain, @key)
+    
+    assert_equal large_plaintext, decrypted_from_base64, "Should correctly decrypt base64 format with auto-detection"
+    assert_equal large_plaintext, decrypted_from_binary, "Should correctly decrypt binary format with auto-detection"
+    assert_equal large_plaintext, decrypted_from_plain, "Should correctly decrypt plain format with auto-detection"
+  end
+
+  def test_compression_algorithm_persistence
+    # Skip if zstd is not available
+    skip "Zstd compression not available" unless AESCompression.algorithm_available?(:zstd)
+    
+    large_plaintext = "This is a test message with repetitive content. " * 100
+    
+    # Encrypt with a specific algorithm
+    encrypted = AESX.encrypt(large_plaintext, @key, compression: :zstd)
+    
+    # Create a new instance with different default settings
+    different_default = AESX::AESX.new(@key, compression: false)
+    
+    # It should still decrypt correctly by reading the embedded algorithm info
+    decrypted = different_default.decrypt(encrypted)
+    
+    assert_equal large_plaintext, decrypted, "Should decrypt correctly even when instance defaults differ from encryption settings"
+  end
+
+  def test_cross_platform_compatibility
+    # This test simulates what happens when data is encrypted on one system
+    # and decrypted on another with different compression libraries available
+    
+    # Skip if no compression algorithms are available
+    skip "No compression algorithms available" unless AESCompression.default_algorithm
+    
+    large_plaintext = "This is a test message with repetitive content. " * 100
+    
+    # Save the original state
+    orig_algorithms = AESCompression.instance_variable_get(:@algorithms).dup
+    orig_default = AESCompression.instance_variable_get(:@default_algorithm)
+    
+    begin
+      # First, encrypt with zstd
+      if AESCompression.algorithm_available?(:zstd)
+        encrypted = AESX.encrypt(large_plaintext, @key, compression: :zstd)
+        
+        # Now simulate a system that only has snappy
+        AESCompression.instance_variable_set(:@algorithms, 
+          orig_algorithms.select { |k, _| k == :snappy })
+        AESCompression.instance_variable_set(:@default_algorithm, :snappy)
+        
+        # It should still decrypt correctly by reading the embedded algorithm info
+        # and using the correct decompression method or raising a clear error
+        if AESCompression.algorithm_available?(:zstd)
+          decrypted = AESX.decrypt(encrypted, @key)
+          assert_equal large_plaintext, decrypted, "Should decompress with the correct algorithm"
+        else
+          assert_raises(RuntimeError) do
+            AESX.decrypt(encrypted, @key)
+          end
+        end
+      end
+    ensure
+      # Restore original state
+      AESCompression.instance_variable_set(:@algorithms, orig_algorithms)
+      AESCompression.instance_variable_set(:@default_algorithm, orig_default)
+    end
+  end
+
+  def test_decrypt_with_unavailable_algorithm
+    # Create encrypted data with a default algorithm
+    large_plaintext = "This is a test message with repetitive content. " * 50
+    encrypted = AESX.encrypt(large_plaintext, @key)
+    
+    # Save original state
+    orig_algorithms = AESCompression.instance_variable_get(:@algorithms).dup
+    
+    begin
+      # For base64 format, modify the compression flag
+      parts = encrypted.split('$')
+      
+      # Determine an algorithm that isn't currently loaded
+      # We'll use ID 3 for lz4 if it's not available, otherwise 2 for snappy
+      algorithm_id = AESCompression.algorithm_available?(:lz4) ? 2 : 3
+      
+      # Ensure the algorithm we're testing isn't available
+      AESCompression.instance_variable_set(:@algorithms, 
+        orig_algorithms.reject { |k, _| k == AESCompression::ID_TO_ALGORITHM[algorithm_id] })
+      
+      # Set the compression flag to our chosen algorithm
+      parts[3] = algorithm_id.to_s
+      modified_encrypted = parts.join('$')
+      
+      # Try to decrypt with the modified compression flag
+      assert_raises(RuntimeError) do
+        AESX.decrypt(modified_encrypted, @key)
+      end
+    ensure
+      # Restore original algorithms
+      AESCompression.instance_variable_set(:@algorithms, orig_algorithms)
+    end
+  end
+  
+  def test_advanced_usage_non_default_cipher
+    key = AESX.key(cipher: 'CHACHA20-POLY1305')
+    
+    # Create an AESX object with non-default cipher
+    cipher = AESX::AESX.new(key, {
+      cipher: 'CHACHA20-POLY1305',
+      padding: true,
+      compression: :zstd,
+      auth_data: "additional authentication data"
+    })
+
+    # Test encryption
+    message1 = "Message 1"
+    message2 = "Message 2"
+    
+    encrypted1 = cipher.encrypt(message1)
+    encrypted2 = cipher.encrypt(message2)
+    
+    # Verify successful encryption
+    refute_nil encrypted1
+    refute_nil encrypted2
+    
+    # Verify decryption
+    decrypted1 = cipher.decrypt(encrypted1)
+    decrypted2 = cipher.decrypt(encrypted2)
+    
+    assert_equal message1, decrypted1
+    assert_equal message2, decrypted2
+  end
+
+end

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification
+name: aesx
+version: !ruby/object:Gem::Version
+  version: 0.1.2
+platform: ruby
+authors:
+- Tom lahti
+bindir: bin
+cert_chain: []
+date: 2025-02-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: openssl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: zstd-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: snappy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: lz4-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Provides almost the same interface as the AES gem, but with modern ciphers
+  and compression. The default cipher is AES-256-GCM. See the README for details.
+email:
+- uidzip@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/aesx.rb
+- lib/compression.rb
+- test_aesx.rb
+homepage: https://github.com/uidzip/aesx
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/uidzip/aesx
+  bug_tracker_uri: https://github.com/uidzip/aesx/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.5
+specification_version: 4
+summary: A lightweight encryption library, in the style of the AES gem
+test_files: []