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 



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

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 



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

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 



129
130
131
 
# File 'lib/familia/encryption/providers/xchacha20_poly1305_provider.rb', line 129

def algorithm
  ALGORITHM
end

#auth_tag_size ⇒ Object 



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

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
104
105
106
 
# 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(
    # to_s before .b: tolerate non-String contexts (Symbol, nil) and
    # always operate on a fresh BINARY copy (never mutate a frozen
    # caller string -- see issue #250 / FrozenError in benchmark).
    context.to_s.b,
    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 



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

def nonce_size
  NONCE_SIZE
end

#secure_wipe(key) ⇒ Object

Clear key from memory (no security guarantees in Ruby)



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

def secure_wipe(key)
  key&.clear
end