Class: Ably::Models::CipherParams

Inherits:
Object
  • Object
show all
Includes:
Ably::Modules::ModelCommon
Defined in:
lib/submodules/ably-ruby/lib/ably/models/cipher_params.rb

Overview

CipherParams is used to configure a channel for encryption

Instance Attribute Summary collapse

Attributes included from Ably::Modules::ModelCommon

#hash

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Ably::Modules::ModelCommon

#==, #[], #as_json, included, #to_json, #to_s

Methods included from Ably::Modules::MessagePack

#to_msgpack

Constructor Details

#initialize(params = {}) ⇒ CipherParams

Returns a new instance of CipherParams.

Parameters:

  • params (Hash) (defaults to: {})

Options Hash (params):

  • :key (String, Binary) —

    Required private key must be either a binary (e.g. a ASCII_8BIT encoded string), or a base64-encoded string. If the key is a base64-encoded string, the it will be automatically converted into a binary

  • :algorithm (String) —

    optional (default AES), specify the encryption algorithm supported by OpenSSL::Cipher

  • :mode (String) —

    optional (default CBC), specify the cipher mode supported by OpenSSL::Cipher

  • :key_length (Integer) —

    optional (default 128), specify the key length of the cipher supported by OpenSSL::Cipher

  • :combined (String) —

    optional (default AES-128-CBC), specify in one option the algorithm, key length and cipher of the cipher supported by OpenSSL::Cipher

Raises:



31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
 
# File 'lib/submodules/ably-ruby/lib/ably/models/cipher_params.rb', line 31

def initialize(params = {})
  @attributes = IdiomaticRubyWrapper(params.clone)

  raise Ably::Exceptions::CipherError, ':key param is required' unless attributes[:key]
  raise Ably::Exceptions::CipherError, ':key param must be a base64-encoded string or byte array (ASCII_8BIT enocdede string)' unless key.kind_of?(String)
  attributes[:key] = decode_key(key) if key.kind_of?(String) && key.encoding != Encoding::ASCII_8BIT

  if attributes[:combined]
    match = /(?<algorithm>\w+)-(?<key_length>\d+)-(?<mode>\w+)/.match(attributes[:combined])
    raise Ably::Exceptions::CipherError, "Invalid :combined param, expecting format such as AES-256-CBC" unless match
    attributes[:algorithm] = match[:algorithm]
    attributes[:key_length] = match[:key_length].to_i
    attributes[:mode] = match[:mode]
  end

  if attributes[:key_length] && (key_length != attributes[:key_length])
    raise Ably::Exceptions::CipherError, "Incompatible :key length of #{key_length} and provided :key_length of #{attributes[:key_length]}"
  end

  if algorithm == 'aes' && mode == 'cbc'
    unless [128, 256].include?(key_length)
      raise Ably::Exceptions::CipherError, "Unsupported key length #{key_length} for aes-cbc encryption. Encryption key must be 128 or 256 bits (16 or 32 ASCII characters)"
    end
  end

  attributes.freeze
end

Instance Attribute Details

#algorithm ⇒ String (readonly)

Returns The algorithm to use for encryption, currently only AES is supported.

Returns:

  • (String) —

    The algorithm to use for encryption, currently only AES is supported



69
70
71
72
73
 
# File 'lib/submodules/ably-ruby/lib/ably/models/cipher_params.rb', line 69

def algorithm
  attributes.fetch(:algorithm) do
    Ably::Util::Crypto::DEFAULTS.fetch(:algorithm)
  end.downcase
end

#attributes ⇒ Hash (readonly)

Returns Access the token details Hash object ruby'fied to use symbolized keys.

Returns:

  • (Hash) —

    Access the token details Hash object ruby'fied to use symbolized keys



103
104
105
 
# File 'lib/submodules/ably-ruby/lib/ably/models/cipher_params.rb', line 103

def attributes
  @attributes
end

#cipher_type ⇒ String (readonly)

Returns The complete Cipher algorithm string such as AES-128-CBC.

Returns:

  • (String) —

    The complete Cipher algorithm string such as AES-128-CBC



97
98
99
 
# File 'lib/submodules/ably-ruby/lib/ably/models/cipher_params.rb', line 97

def cipher_type
  self.class.cipher_type(algorithm: algorithm, key_length: key_length, mode: mode)
end

#key ⇒ Binary (readonly)

Returns Private key used to encrypt and decrypt payloads.

Returns:

  • (Binary) —

    Private key used to encrypt and decrypt payloads



77
78
79
 
# File 'lib/submodules/ably-ruby/lib/ably/models/cipher_params.rb', line 77

def key
  attributes[:key]
end

#key_length ⇒ Integer (readonly)

Returns The length in bits of the key.

Returns:

  • (Integer) —

    The length in bits of the key



83
84
85
 
# File 'lib/submodules/ably-ruby/lib/ably/models/cipher_params.rb', line 83

def key_length
  key.unpack('b*').first.length
end

#mode ⇒ String (readonly)

Returns The cipher mode, currently only CBC is supported.

Returns:

  • (String) —

    The cipher mode, currently only CBC is supported



89
90
91
92
93
 
# File 'lib/submodules/ably-ruby/lib/ably/models/cipher_params.rb', line 89

def mode
  attributes.fetch(:mode) do
    Ably::Util::Crypto::DEFAULTS.fetch(:mode)
  end.downcase
end

Class Method Details

.cipher_type(params) ⇒ String

The Cipher algorithm string such as AES-128-CBC

Parameters:

  • params (Hash) —

    Hash containing :algorithm, :key_length and :mode key values

Returns:

  • (String) 


63
64
65
 
# File 'lib/submodules/ably-ruby/lib/ably/models/cipher_params.rb', line 63

def self.cipher_type(params)
  "#{params[:algorithm]}-#{params[:key_length]}-#{params[:mode]}".to_s.upcase
end