Class: Familia::Encryption::Providers::XChaCha20Poly1305Provider

Inherits:
Familia::Encryption::Provider show all
Defined in:
lib/familia/encryption/providers/xchacha20_poly1305_provider.rb

Constant Summary collapse

ALGORITHM = 
'xchacha20poly1305'.freeze
NONCE_SIZE = 
24
AUTH_TAG_SIZE = 
16

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

This class inherits a constructor from Familia::Encryption::Provider

Class Method Details

.auth_tag_size ⇒ Object 



114
115
116
 
# File 'lib/familia/encryption/providers/xchacha20_poly1305_provider.rb', line 114

def self.auth_tag_size
  AUTH_TAG_SIZE
end

.available? ⇒ Boolean

Returns:

  • (Boolean) 


40
41
42
 
# File 'lib/familia/encryption/providers/xchacha20_poly1305_provider.rb', line 40

def self.available?
  !!defined?(RbNaCl)
end

.nonce_size ⇒ Object 



110
111
112
 
# File 'lib/familia/encryption/providers/xchacha20_poly1305_provider.rb', line 110

def self.nonce_size
  NONCE_SIZE
end

.priority ⇒ Object 



44
45
46
 
# File 'lib/familia/encryption/providers/xchacha20_poly1305_provider.rb', line 44

def self.priority
  100 # Highest priority - best in class
end

Instance Method Details

#algorithm ⇒ Object 



126
127
128
 
# File 'lib/familia/encryption/providers/xchacha20_poly1305_provider.rb', line 126

def algorithm
  ALGORITHM
end

#auth_tag_size ⇒ Object 



122
123
124
 
# File 'lib/familia/encryption/providers/xchacha20_poly1305_provider.rb', line 122

def auth_tag_size
  AUTH_TAG_SIZE
end

#decrypt(ciphertext, key, nonce, auth_tag, additional_data = nil) ⇒ Object 



63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/familia/encryption/providers/xchacha20_poly1305_provider.rb', line 63

def decrypt(ciphertext, key, nonce, auth_tag, additional_data = nil)
  validate_key_length!(key)
  box = RbNaCl::AEAD::XChaCha20Poly1305IETF.new(key)

  ciphertext_with_tag = ciphertext + auth_tag
  aad = additional_data.to_s

  box.decrypt(nonce, ciphertext_with_tag, aad)
rescue RbNaCl::CryptoError
  raise EncryptionError, 'Decryption failed - invalid key or corrupted data'
end

#derive_key(master_key, context, personal: nil) ⇒ String

Derives a context-specific encryption key using BLAKE2b.

The personalization parameter provides cryptographic domain separation, ensuring that derived keys are unique per application even when using identical master keys and contexts. This prevents key reuse across different applications or library versions.

Parameters:

  • master_key (String) —

    The master key (must be >= 32 bytes)

  • context (String) —

    Context string for key derivation

  • personal (String, nil) (defaults to: nil) —

    Optional personalization override

Returns:

  • (String) —

    32-byte derived key

Raises:



90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/familia/encryption/providers/xchacha20_poly1305_provider.rb', line 90

def derive_key(master_key, context, personal: nil)
  validate_key_length!(master_key)
  raw_personal = personal || Familia.config.encryption_personalization
  raise EncryptionError, 'Personalization string must not contain null bytes' if raw_personal.include?("\0")

  personal_string = raw_personal.ljust(16, "\0")

  RbNaCl::Hash.blake2b(
    context.force_encoding('BINARY'),
    key: master_key,
    digest_size: 32,
    personal: personal_string
  )
end

#encrypt(plaintext, key, additional_data = nil) ⇒ Object 



48
49
50
51
52
53
54
55
56
57
58
59
60
61
 
# File 'lib/familia/encryption/providers/xchacha20_poly1305_provider.rb', line 48

def encrypt(plaintext, key, additional_data = nil)
  validate_key_length!(key)
  nonce = generate_nonce
  box = RbNaCl::AEAD::XChaCha20Poly1305IETF.new(key)

  aad = additional_data.to_s
  ciphertext_with_tag = box.encrypt(nonce, plaintext.to_s, aad)

  {
    ciphertext: ciphertext_with_tag[0...-16],
    auth_tag: ciphertext_with_tag[-16..],
    nonce: nonce,
  }
end

#generate_nonce ⇒ Object 



75
76
77
 
# File 'lib/familia/encryption/providers/xchacha20_poly1305_provider.rb', line 75

def generate_nonce
  RbNaCl::Random.random_bytes(NONCE_SIZE)
end

#nonce_size ⇒ Object 



118
119
120
 
# File 'lib/familia/encryption/providers/xchacha20_poly1305_provider.rb', line 118

def nonce_size
  NONCE_SIZE
end

#secure_wipe(key) ⇒ Object

Clear key from memory (no security guarantees in Ruby)



106
107
108
 
# File 'lib/familia/encryption/providers/xchacha20_poly1305_provider.rb', line 106

def secure_wipe(key)
  key&.clear
end