Class: Ably::Models::CipherParams

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

Overview

Sets the properties to configure encryption for a Rest::Channel or Realtime::Channel object.

Instance Attribute Summary

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:



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
58
 
# File 'lib/ably/models/cipher_params.rb', line 32

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

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) 


66
67
68
 
# File 'lib/ably/models/cipher_params.rb', line 66

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

Instance Method Details

#algorithm ⇒ String

The algorithm to use for encryption. Only AES is supported and is the default value.

Returns:

  • (String) 


76
77
78
79
80
 
# File 'lib/ably/models/cipher_params.rb', line 76

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

#attributes ⇒ Hash

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

Returns:

  • (Hash) 


126
127
128
 
# File 'lib/ably/models/cipher_params.rb', line 126

def attributes
  @attributes
end

#cipher_type ⇒ String

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

Returns:

  • (String) 


118
119
120
 
# File 'lib/ably/models/cipher_params.rb', line 118

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

#key ⇒ Binary

The private key used to encrypt and decrypt payloads.

Returns:

  • (Binary) 


88
89
90
 
# File 'lib/ably/models/cipher_params.rb', line 88

def key
  attributes[:key]
end

#key_length ⇒ Integer

The length of the key in bits; for example 128 or 256.

Returns:

  • (Integer) 


98
99
100
 
# File 'lib/ably/models/cipher_params.rb', line 98

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

#mode ⇒ String

The cipher mode. Only CBC is supported and is the default value.

Returns:

  • (String) 


108
109
110
111
112
 
# File 'lib/ably/models/cipher_params.rb', line 108

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