Class: Cybertrain::Encryptor

Inherits:
Object
  • Object
show all
Defined in:
cybertrain/encryptor.rb

Overview

AES-256-GCM with one current key (encrypts and decrypts) and any number of previous ones (decrypt only, tried in order after the current one). Keys are raw bytes, 32 each: Encryptor.from_hex reads the 64-hex configuration value.

Examples:

enc = Cybertrain::Encryptor.new(Cybertrain::Encryptor.from_hex(ENV["CYBERTRAIN_ENCRYPTION_KEY"].to_s))
payload = enc.encrypt("sk_live_...")   # => "1:3q2+7w..."
enc.decrypt(payload)                   # => "sk_live_..."

Defined Under Namespace

Classes: Error

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.from_hex(hex) ⇒ String

The 32 raw bytes of a 64-hex-character key (either case).

Parameters:

  • hex (String)

Returns:

  • (String)

Raises:



83
84
85
86
87
88
# File 'cybertrain/encryptor.rb', line 83

def self.from_hex(hex)
  s = hex.to_s
  raise Error, "encryption key must be 64 hex characters" unless Config.encryption_key_text?(s)

  [s].pack("H*")
end

Instance Method Details

#decrypt(payload) ⇒ String

The text of a payload #encrypt made, under the current key or a previous one, as UTF-8. An empty String (an empty stored cell, which no payload is) is “”.

Parameters:

  • payload (String)

Returns:

  • (String)

Raises:

  • (Encryptor::Error) —

    on an unknown version, bad Base64, a payload too short, or one no key authenticates (a wrong key or a changed byte)



166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
# File 'cybertrain/encryptor.rb', line 166

def decrypt(payload)
  s = payload.to_s
  return "" if s.empty?
  unless s.start_with?(PAYLOAD_PREFIX)
    raise Error, "encrypted payload has an unknown version (expected \"#{PAYLOAD_PREFIX}\")"
  end

  raw = Encryptor.decode_payload(s[2, s.size - 2].to_s)
  raise Error, "encrypted payload is too short" if raw.bytesize < NONCE_BYTES + TAG_BYTES

  opened = open_bytes(raw, "")
  return opened unless opened.nil?

  raise Error, "encrypted payload does not decrypt with the configured keys (wrong key or changed data)"
end

#encrypt(text) ⇒ String

The payload of text under the current key, with a fresh nonce.

Parameters:

  • text (String)

Returns:

  • (String) —

    "1:" and Base64



100
101
102
103
# File 'cybertrain/encryptor.rb', line 100

def encrypt(text)
  raw = seal_bytes(text, "")
  PAYLOAD_PREFIX + Base64.strict_encode64(raw)
end

#open_bytes(raw, aad) ⇒ String?

The text #seal_bytes sealed with the same aad, under the current key or a previous one, as UTF-8; nil when no key authenticates it (a wrong key, other additional data, a changed or missing byte, or fewer bytes than a nonce and a tag). Never raises for the bytes it is given.

Parameters:

  • raw (String) —

    binary, nonce ‖ ciphertext ‖ tag

  • aad (String)

Returns:

  • (String, nil)


139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
# File 'cybertrain/encryptor.rb', line 139

def open_bytes(raw, aad)
  bytes = raw.to_s
  data = aad.to_s
  n = bytes.bytesize
  return nil if n < NONCE_BYTES + TAG_BYTES

  nonce = bytes.byteslice(0, NONCE_BYTES).to_s
  sealed = bytes.byteslice(NONCE_BYTES, n - NONCE_BYTES - TAG_BYTES).to_s
  tag = bytes.byteslice(n - TAG_BYTES, TAG_BYTES).to_s
  i = 0
  while i < @keys.size
    opened = Encryptor.open_with(@keys[i], nonce, sealed, tag, data)
    return opened.force_encoding("UTF-8") unless opened.nil?

    i += 1
  end
  nil
end

#seal_bytes(text, aad) ⇒ String

text sealed under the current key with a fresh random nonce and aad as the GCM additional data (authenticated, not encrypted): the raw bytes nonce(12) ‖ ciphertext ‖ tag(16), which only #open_bytes with the same aad opens.

Examples:

raw = enc.seal_bytes("{\"user_id\":\"5\"}", "session")
enc.open_bytes(raw, "session")   # => "{\"user_id\":\"5\"}"
enc.open_bytes(raw, "cookie:x")  # => nil

Parameters:

  • text (String)
  • aad (String) —

    the purpose the value is sealed for

Returns:

  • (String) —

    binary



117
118
119
120
121
122
123
124
125
126
127
128
129
# File 'cybertrain/encryptor.rb', line 117

def seal_bytes(text, aad)
  s = text.to_s
  data = aad.to_s
  nonce = SecureRandom.random_bytes(NONCE_BYTES)
  cipher = OpenSSL::Cipher.new(CIPHER)
  cipher.encrypt
  cipher.key = @keys[0]
  cipher.iv = nonce
  cipher.auth_data = data
  sealed = cipher.update(s) + cipher.final
  tag = cipher.auth_tag
  nonce + sealed + tag
end