class Ably::Util::Crypto

Contains the properties required to configure the encryption of {Ably::Models::Message} payloads.

Constants

BLOCK_LENGTH
DEFAULTS

Attributes

cipher_params[R]

Configured {Ably::Models::CipherParams} for this Crypto object, see {#initialize} for a list of configureable options

@return [Ably::Models::CipherParams]

fixed_iv[R]

Used solely for tests to fix the IV instead of randomly generate one

Public Class Methods

cipher_type(options) click to toggle source

The Cipher algorithm string such as AES-128-CBC @api private

# File lib/submodules/ably-ruby/lib/ably/util/crypto.rb, line 68
def self.cipher_type(options)
  Ably::Models::CipherParams.cipher_type(options)
end
generate_random_key(key_length = DEFAULTS.fetch(:key_length)) click to toggle source

Generates a random key to be used in the encryption of the channel. If the language cryptographic randomness primitives are blocking or async, a callback is used. The callback returns a generated binary key.

@spec RSE2, RSE2a, RSE2b

@param [Integer] key_length The length of the key, in bits, to be generated. If not specified, this is equal to the default keyLength of the default algorithm: for AES this is 256 bits. @return Binary The key as a binary, for example, a byte array.

# File lib/submodules/ably-ruby/lib/ably/util/crypto.rb, line 61
def self.generate_random_key(key_length = DEFAULTS.fetch(:key_length))
  params = DEFAULTS.merge(key_length: key_length)
  OpenSSL::Cipher.new(cipher_type(params)).random_key
end
get_default_params(params = {}) click to toggle source

Returns a {Ably::Models::CipherParams} object, using the default values for any fields not supplied by the ‘Hash` object.

@spec RSE1, RSE1b, RSE1b

@param [Hash] params a Hash used to configure the Crypto library’s {Ably::Models::CipherParams} @option params (see {Ably::Models::CipherParams#initialize})

@return [Ably::Models::CipherParams] Configured cipher params with :key, :algorithm, :mode, :key_length attributes

# File lib/submodules/ably-ruby/lib/ably/util/crypto.rb, line 49
def self.get_default_params(params = {})
  Ably::Models::CipherParams(params)
end
new(params) click to toggle source

Creates a {Ably::Util::Crypto} object

@param [Hash] params a Hash used to configure the Crypto library’s {Ably::Models::CipherParams} @option params (see Ably::Models::CipherParams#initialize)

@return [Ably::Util::Crypto]

@example

key = Ably::Util::Crypto.generate_random_key
crypto = Ably::Util::Crypto.new(key: key)
encrypted = crypto.encrypt('secret text')
crypto.decrypt(decrypted) # => 'secret text'
# File lib/submodules/ably-ruby/lib/ably/util/crypto.rb, line 35
def initialize(params)
  @fixed_iv = params[:fixed_iv]
  @cipher_params = Ably::Models::CipherParams(params)
end

Public Instance Methods

decrypt(encrypted_payload_with_iv) click to toggle source

Decrypt payload using configured Cipher

@param [String] encrypted_payload_with_iv the encrypted payload to be decrypted

@return [String]

# File lib/submodules/ably-ruby/lib/ably/util/crypto.rb, line 96
def decrypt(encrypted_payload_with_iv)
  raise Ably::Exceptions::CipherError, 'iv is missing or not long enough' unless encrypted_payload_with_iv.length >= BLOCK_LENGTH*2

  iv = encrypted_payload_with_iv.slice(0...BLOCK_LENGTH)
  encrypted_payload = encrypted_payload_with_iv.slice(BLOCK_LENGTH..-1)

  decipher = openssl_cipher
  decipher.decrypt
  decipher.key = key
  decipher.iv = iv

  decipher.update(encrypted_payload) << decipher.final
end
encrypt(payload, encrypt_options = {}) click to toggle source

Encrypt payload using configured Cipher

@param [String] payload the payload to be encrypted @param [Hash] encrypt_options an options Hash to configure the encrypt action @option encrypt_options [String] :iv optionally use the provided Initialization Vector instead of a randomly generated IV

@return [String] binary string with Encoding::ASCII_8BIT encoding

# File lib/submodules/ably-ruby/lib/ably/util/crypto.rb, line 80
def encrypt(payload, encrypt_options = {})
  cipher = openssl_cipher
  cipher.encrypt
  cipher.key = key
  iv = encrypt_options[:iv] || fixed_iv || cipher.random_iv
  cipher.iv = iv

  iv << cipher.update(payload) << cipher.final
end
random_iv() click to toggle source

Generate a random IV @return [String]

# File lib/submodules/ably-ruby/lib/ably/util/crypto.rb, line 112
def random_iv
  openssl_cipher.random_iv
end

Private Instance Methods

key() click to toggle source
# File lib/submodules/ably-ruby/lib/ably/util/crypto.rb, line 126
def key
  cipher_params.key
end
openssl_cipher() click to toggle source
# File lib/submodules/ably-ruby/lib/ably/util/crypto.rb, line 130
def openssl_cipher
  @openssl_cipher ||= OpenSSL::Cipher.new(cipher_params.cipher_type)
end
random_key() click to toggle source

Generate a random key @return [String]

# File lib/submodules/ably-ruby/lib/ably/util/crypto.rb, line 122
def random_key
  openssl_cipher.random_key
end