Module: AESX

Defined in:
lib/aesx.rb

Overview

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.

Examples:

Basic usage

key = AESX.key
encrypted = AESX.encrypt("Secret message", key)
decrypted = AESX.decrypt(encrypted, key)

Using different ciphers

key = AESX.key(cipher: 'CHACHA20-POLY1305')
encrypted = AESX.encrypt("Secret message", key, cipher: 'CHACHA20-POLY1305')

With compression

encrypted = AESX.encrypt("Large message", key, compression: :zstd)

Defined Under Namespace

Classes: AESX

Constant Summary collapse

CIPHER_SPECS =

Mapping of cipher names to [key_length, iv_length]

{
  '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 Method Summary collapse

Class Method Details

.available_compression ⇒ Array<Symbol>

Returns an array of available compression algorithms

Returns:

  • (Array<Symbol>) —

    Symbols representing available compression algorithms



125
126
127
 
# File 'lib/aesx.rb', line 125

def available_compression
  AESCompression.available_algorithms
end

.cipher_list ⇒ Array<String>

Returns a list of supported ciphers available in the current OpenSSL installation

Returns:

  • (Array<String>) —

    List of available cipher names



50
51
52
53
 
# File 'lib/aesx.rb', line 50

def cipher_list
  openssl_ciphers = OpenSSL::Cipher.ciphers.map(&:upcase)
  CIPHER_SPECS.keys & openssl_ciphers    
end

.decrypt(ciphertext, key, opts = {}) ⇒ String

Decrypts ciphertext using the specified key and options

Parameters:

  • ciphertext (String, Array) —

    The encrypted data to decrypt

  • key (String) —

    The encryption key

  • opts (Hash) (defaults to: {}) —

    Options for decryption (most are auto-detected)

Options Hash (opts):

  • :format (Symbol) — default: auto-detected —

    Input format

  • :cipher (String) — default: 'AES-256-GCM' —

    Cipher to use

  • :padding (Boolean, Integer) — default: true —

    Enable padding

  • :auth_data (String) — default: '' —

    Additional authentication data for GCM mode

Returns:

  • (String) —

    The decrypted plaintext

Raises:

  • (OpenSSL::Cipher::CipherError) —

    If decryption fails (wrong key, tampered data)



85
86
87
88
 
# File 'lib/aesx.rb', line 85

def decrypt(ciphertext, key, opts={})
  cipher = AESX.new(key, opts)
  cipher.decrypt(ciphertext)
end

.default_compression ⇒ Symbol?

Returns the default compression algorithm

Returns:

  • (Symbol, nil) —

    The symbol representing the default algorithm, or nil if none available



118
119
120
 
# File 'lib/aesx.rb', line 118

def default_compression
  AESCompression.default_algorithm
end

.encrypt(plaintext, key, opts = {}) ⇒ String, Array

Encrypts plaintext using the specified key and options

Parameters:

  • plaintext (String) —

    The data to encrypt

  • key (String) —

    The encryption key

  • opts (Hash) (defaults to: {}) —

    Options for encryption

Options Hash (opts):

  • :format (Symbol) — default: :base_64 —

    Output format - :base_64, :binary, or :plain

  • :cipher (String) — default: 'AES-256-GCM' —

    Cipher to use

  • :iv (String) — default: random —

    Initialization vector

  • :padding (Boolean, Integer) — default: true —

    Enable padding

  • :auth_data (String) — default: '' —

    Additional authentication data for GCM mode

  • :compression (Boolean, Symbol) — default: default algorithm —

    Compression option

Returns:

  • (String, Array) —

    Encrypted data in the specified format



68
69
70
71
 
# File 'lib/aesx.rb', line 68

def encrypt(plaintext, key, opts={})
  cipher = AESX.new(key, opts)
  cipher.encrypt(plaintext)
end

.iv(format = :plain, cipher: 'AES-256-GCM') ⇒ String

Generates a random initialization vector of appropriate length for the specified cipher

Parameters:

  • format (Symbol) (defaults to: :plain) —

    Output format - :plain or :base_64

  • cipher (String) (defaults to: 'AES-256-GCM') —

    Cipher to determine IV length

Returns:

  • (String) —

    A random IV in the specified format



109
110
111
112
113
 
# File 'lib/aesx.rb', line 109

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

.key(length = nil, format = :plain, cipher: 'AES-256-GCM') ⇒ String

Generates a random key of appropriate length for the specified cipher

Parameters:

  • length (Integer, nil) (defaults to: nil) —

    Key length in bits, or nil to use cipher default

  • format (Symbol) (defaults to: :plain) —

    Output format - :plain or :base_64

  • cipher (String) (defaults to: 'AES-256-GCM') —

    Cipher to determine key length

Returns:

  • (String) —

    A random key in the specified format



97
98
99
100
101
 
# File 'lib/aesx.rb', line 97

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