Module: Cybertrain::Crypto

Defined in:
cybertrain/crypto.rb,
cybertrain/encryptor.rb

Class Method Summary collapse

Class Method Details

.decrypt(payload) ⇒ String

The text of a payload encrypt made, with the configured key or a previous one.

Parameters:

  • payload (String)

Returns:

  • (String)

Raises:



258
259
260
# File 'cybertrain/encryptor.rb', line 258

def self.decrypt(payload)
  Cybertrain.config.encryptor.decrypt(payload)
end

.derive_key(secret, label) ⇒ String

A 32-byte key for one purpose, derived from a secret (normally secret_key_base): the HMAC-SHA256 of "cybertrain key\0" + label under secret (the prefix keeps it apart from the framework’s other HMACs under the raw secret). Each use takes its own label (“cybertrain session”, “cybertrain signed cookie”, “cybertrain encrypted cookie”), so a value made under one key never verifies or decrypts under another, and rotating the secret changes them all.

Examples:

Cybertrain::Crypto.derive_key(config.secret_key_base, "cybertrain session").bytesize   # => 32

Parameters:

  • secret (String)
  • label (String) —

    the purpose

Returns:

  • (String) —

    32 raw bytes



130
131
132
# File 'cybertrain/crypto.rb', line 130

def self.derive_key(secret, label)
  Crypto.hmac_digest(secret, KEY_PREFIX + label)
end

.encrypt(text) ⇒ String

text encrypted with the configured key (Cybertrain::Config#encryptor).

Examples:

Cybertrain::Crypto.encrypt("sk_live_...")   # => "1:3q2+7w..."

Parameters:

  • text (String)

Returns:

  • (String)

Raises:



248
249
250
# File 'cybertrain/encryptor.rb', line 248

def self.encrypt(text)
  Cybertrain.config.encryptor.encrypt(text)
end

.encryption_key_hex ⇒ String

A fresh key for CYBERTRAIN_ENCRYPTION_KEY: 32 random bytes as 64 lowercase hex digits (what cybertrain secret --hex prints). The encryption itself is cybertrain/encryptor.rb’s (AES-256-GCM through openssl); making a key needs only SecureRandom.

Examples:

Cybertrain::Crypto.encryption_key_hex   # => "9b1f..." (64 hex digits)

Returns:

  • (String)


112
113
114
# File 'cybertrain/crypto.rb', line 112

def self.encryption_key_hex
  Crypto.random_token(32)
end

.random_token(bytes = 32) ⇒ String

SecureRandom.hex, through Crypto.hex (SecureRandom.hex appends a one-character String per digit).

Examples:

Cybertrain::Crypto.random_token(16)   # => "3f9c..." (32 hex digits)

Parameters:

  • bytes (Integer) (defaults to: 32) —

    how many random bytes

Returns:

  • (String) —

    twice as many lowercase hex digits



79
80
81
# File 'cybertrain/crypto.rb', line 79

def self.random_token(bytes = 32)
  Crypto.hex(SecureRandom.random_bytes(bytes))
end

.secure_compare(a, b) ⇒ Boolean

Constant-time byte comparison: every byte pair is examined regardless of an early mismatch, so the running time does not leak how much of a signature or token was guessed correctly. (Strings of different lengths return false at once: the length is not the secret.)

Examples:

Cybertrain::Crypto.secure_compare(params[:token].to_s, SetupController.setup_token)

Parameters:

  • a (String)
  • b (String)

Returns:

  • (Boolean) —

    whether the two hold the same bytes



58
59
60
61
62
63
64
65
66
67
68
69
70
# File 'cybertrain/crypto.rb', line 58

def self.secure_compare(a, b)
  return false if a.bytesize != b.bytesize

  a_bytes = a.bytes
  b_bytes = b.bytes
  diff = 0
  i = 0
  while i < a_bytes.length
    diff |= (a_bytes[i] ^ b_bytes[i])
    i += 1
  end
  diff == 0
end

.uuid ⇒ String

A random (version 4) UUID in lower-case hex, 8-4-4-4-12: 16 bytes from SecureRandom with the version (byte 6’s high nibble, 4) and the variant (byte 8’s two high bits, 10) set, as RFC 9562 says. A request’s id (RequestId). Built here rather than by SecureRandom.uuid, which nothing in the framework has compiled.

Examples:

Cybertrain::Crypto.uuid   # => "3f2a9c1e-6c1d-4f0b-9a52-0d1e2f3a4b5c"

Returns:

  • (String) —

    36 characters



92
93
94
95
96
97
98
99
100
101
102
# File 'cybertrain/crypto.rb', line 92

def self.uuid
  raw = SecureRandom.random_bytes(16)
  hex = Crypto.hex(raw)
  version = (raw.getbyte(6).to_i & 0x0f) | 0x40
  variant = (raw.getbyte(8).to_i & 0x3f) | 0x80
  # Only the high nibbles change: the hex digits 12 and 16.
  hex.setbyte(12, HEX_DIGITS.getbyte(version >> 4))
  hex.setbyte(16, HEX_DIGITS.getbyte(variant >> 4))
  "#{hex.byteslice(0, 8)}-#{hex.byteslice(8, 4)}-#{hex.byteslice(12, 4)}-" \
    "#{hex.byteslice(16, 4)}-#{hex.byteslice(20, 12)}"
end