pubnub 5.2.2 → 5.3.0

data/lib/pubnub/events/set_memberships.rb

@@ -45,7 +45,7 @@ module Pubnub
         membership_object
       end
 
-      body = Formatter.format_message({ set: memberships }, "", @random_iv, false)
+      body = Formatter.format_message({ set: memberships }, nil, false)
       response = send_request(body)
 
       envelopes = fire_callbacks(handle(response, uri))
@@ -86,11 +86,11 @@ module Pubnub
     def valid_envelope(parsed_response, req_res_objects)
       memberships = parsed_response['data'].map { |uuid_membership|
         membership = Hash.new
-        uuid_membership.each{ |k,v| membership[k.to_sym] = v }
+        uuid_membership.each { |k, v| membership[k.to_sym] = v }
 
         unless membership[:channel].nil?
           channel_metadata = Hash.new
-          membership[:channel].each{ |k,v| channel_metadata[k.to_sym] = v }
+          membership[:channel].each { |k, v| channel_metadata[k.to_sym] = v }
           channel_metadata[:updated] = Date._parse(channel_metadata[:updated]) unless channel_metadata[:updated].nil?
           membership[:channel] = channel_metadata
         end

data/lib/pubnub/events/set_uuid_metadata.rb

@@ -28,7 +28,7 @@ module Pubnub
     def fire
       Pubnub.logger.debug('Pubnub::SetUuidMetadata') { "Fired event #{self.class}" }
 
-      body = Formatter.format_message(@metadata, "", @random_iv, false)
+      body = Formatter.format_message(@metadata, nil, false)
       response = send_request(body)
 
       envelopes = fire_callbacks(handle(response, uri))
@@ -61,7 +61,7 @@ module Pubnub
     def valid_envelope(parsed_response, req_res_objects)
       data = parsed_response['data']
       metadata = Hash.new
-      data.each{ |k,v| metadata[k.to_sym] = v }
+      data.each { |k, v| metadata[k.to_sym] = v }
       metadata[:updated] = Date._parse(metadata[:updated]) unless metadata[:updated].nil?
 
       Pubnub::Envelope.new(

data/lib/pubnub/events/signal.rb

@@ -39,7 +39,7 @@ module Pubnub
         '0',
         Formatter.format_channel(@channel, true),
         '0',
-        Formatter.format_message(@message, @cipher_key, @random_iv)
+        Formatter.format_message(@message, @crypto_module)
       ].join('/')
     end
 

data/lib/pubnub/events/subscribe.rb

@@ -8,6 +8,11 @@ module Pubnub
 
     def initialize(options, app)
       @event = :subscribe
+
+      # Override crypto module if custom cipher key has been used.
+      random_iv = options.key?(:random_iv) ? options[:random_iv] : true
+      options[:crypto_module] = Crypto::CryptoModule.new_legacy(options[:cipher_key], random_iv) if options[:cipher_key]
+
       super
       app.apply_state(self)
     end

data/lib/pubnub/formatter.rb

@@ -41,17 +41,28 @@ module Pubnub
         end
       end
 
-      # Transforms message to json and encode it
-      def format_message(message, cipher_key = "", use_random_iv = false, uri_escape = true)
-        if cipher_key && !cipher_key.empty?
-          pc = Pubnub::Crypto.new(cipher_key, use_random_iv)
-          message = pc.encrypt(message).to_json
-          message = Addressable::URI.escape(message) if uri_escape
-        else
-          message = message.to_json
-          message = Formatter.encode(message) if uri_escape
+      # TODO: Uncomment code below when cryptor implementations will be added.
+      # Transforms message to json and encode it.
+      #
+      # @param message [Hash, String, Integer, Boolean] Message data which
+      #   should be formatted.
+      # @param crypto [Crypto::CryptoProvider, nil] Crypto which should be used to
+      #   encrypt message data.
+      # @param uri_escape [Boolean, nil] Whether formatted message should escape
+      #   to be used as part of URI or not.
+      # @return [String, nil] Formatted message data.
+      def format_message(message, crypto = nil, uri_escape = true)
+        json_message = message.to_json
+        if crypto
+          encrypted_data = crypto&.encrypt(json_message)
+          json_message = Base64.strict_encode64(encrypted_data).to_json unless encrypted_data.nil?
+        end
+
+        if uri_escape
+          json_message = Formatter.encode(json_message) if crypto.nil?
+          json_message = Addressable::URI.escape(json_message).to_s unless crypto.nil?
         end
-        message
+        json_message
       end
 
       # Quite lazy way, but good enough for current usage
@@ -100,7 +111,7 @@ module Pubnub
       # Parses string to JSON
       def parse_json(string)
         [JSON.parse(string), nil]
-      rescue JSON::ParserError => _error
+      rescue JSON::ParserError => _e
         [nil, JSON::ParserError]
       end
 

data/lib/pubnub/modules/crypto/crypto_module.rb

@@ -0,0 +1,159 @@
+module Pubnub
+  module Crypto
+    # Crypto module for data processing.
+    #
+    # The PubNub client uses a module to encrypt and decrypt sent data in a way
+    # that's compatible with previous versions (if additional cryptors have been
+    # registered).
+    class CryptoModule < CryptoProvider
+      # AES-CBC cryptor based module.
+      #
+      # Data <i>encryption</i> and <i>decryption</i> will be done by default
+      # using the <i>AesCbcCryptor</i>. In addition to the <i>AesCbcCryptor</i>
+      # for data <i>decryption</i>, the <i>LegacyCryptor</i> will be registered
+      # for backward-compatibility.
+      #
+      # @param cipher_key [String] Key for data encryption and decryption.
+      # @param use_random_iv [Boolean] Whether random IV should be used for data
+      #   decryption.
+      #
+      # @raise [ArgumentError] If the <i>cipher_key</i> is missing or empty.
+      def self.new_aes_cbc(cipher_key, use_random_iv)
+        if cipher_key.nil? || cipher_key.empty?
+          raise ArgumentError, {
+            message: '\'cipher_key\' is missing or empty.'
+          }
+        end
+
+        CryptoModule.new AesCbcCryptor.new(cipher_key), [LegacyCryptor.new(cipher_key, use_random_iv)]
+      end
+
+      # Legacy AES-CBC cryptor based module.
+      #
+      # Data <i>encryption</i> and <i>decryption</i> will be done by default
+      # using the <i>LegacyCrypto</i>. In addition to the <i>LegacyCrypto</i>
+      # for data <i>decryption</i>, the <i>AesCbcCryptor</i> will be registered
+      # for future-compatibility (which will help with gradual application
+      # updates).
+      #
+      # @param cipher_key [String] Key for data encryption and decryption.
+      # @param use_random_iv [Boolean] Whether random IV should be used for data
+      #   decryption.
+      #
+      # @raise [ArgumentError] If the <i>cipher_key</i> is missing or empty.
+      def self.new_legacy(cipher_key, use_random_iv)
+        if cipher_key.nil? || cipher_key.empty?
+          raise ArgumentError, {
+            message: '\'cipher_key\' is missing or empty.'
+          }
+        end
+
+        CryptoModule.new LegacyCryptor.new(cipher_key, use_random_iv), [AesCbcCryptor.new(cipher_key)]
+      end
+
+      # Create crypto module.
+      #
+      # @param default [Cryptor] Default cryptor used to encrypt and decrypt
+      #   data.
+      # @param cryptors [Array<Cryptor>, nil] Additional cryptors which will be
+      #   used to decrypt data encrypted by previously used cryptors.
+      def initialize(default, cryptors)
+        if default.nil?
+          raise ArgumentError, {
+            message: '\'default\' cryptor required for data encryption.'
+          }
+        end
+
+        @default = default
+        @cryptors = cryptors&.each_with_object({}) do |value, hash|
+          hash[value.identifier] = value
+        end || {}
+        super()
+      end
+
+      def encrypt(data)
+        # Encrypting provided data.
+        encrypted_data = default_cryptor.encrypt(data)
+        return nil if encrypted_data.nil?
+
+        payload = Crypto::CryptorHeader.new(default_cryptor.identifier, encrypted_data.metadata).to_s
+        payload << encrypted_data.metadata unless encrypted_data.metadata.nil?
+        payload << encrypted_data.data
+      end
+
+      def decrypt(data)
+        if data.nil? || data.empty?
+          puts 'Pubnub :: DECRYPTION ERROR: Empty data for decryption'
+          return nil
+        end
+
+        header = Crypto::CryptorHeader.parse(data)
+        return nil if header.nil?
+
+        cryptor_identifier = header.identifier || '\x00\x00\x00\x00'
+        cryptor = cryptor cryptor_identifier
+
+        # Check whether there is a cryptor to decrypt data or not.
+        if cryptor.nil?
+          identifier = header.identifier || 'UNKN'
+          raise UnknownCryptorError, {
+            message: "Decrypting data created by unknown cryptor. Please make sure to register
+#{identifier} or update SDK."
+          }
+        end
+
+        encrypted_data = data[header.length..-1]
+        metadata = metadata encrypted_data, header.data_size
+
+        # Check whether there is still some data for processing or not.
+        return nil if encrypted_data.nil? || encrypted_data.empty?
+
+        cryptor.decrypt(EncryptedData.new(encrypted_data, metadata))
+      end
+
+      private
+
+      # Cryptor used by the module by default to encrypt data.
+      #
+      # @return [Cryptor] Default cryptor used to encrypt and decrypt data.
+      def default_cryptor
+        @default
+      end
+
+      # Additional cryptors that can be used to decrypt data if the
+      # <i>default_cryptor</i> can't.
+      #
+      # @return [Hash<String, Cryptor>] Map of Cryptor to their identifiers.
+      def additional_cryptors
+        @cryptors
+      end
+
+      # Extract metadata information from source data.
+      #
+      # @param data [String, nil] Encrypted data from which cryptor metadata
+      #   should be extracted.
+      # @param size [Integer] Size of cryptor-defined data.
+      # @return [String, nil] Extracted metadata or <i>nil</i> in case if
+      #   <i>size</i> is <b>0</b>.
+      def metadata(data, size)
+        return nil if !data || !size.positive?
+
+        data&.slice!(0..(size - 1))
+      end
+
+      # Find cryptor with a specified identifier.
+      #
+      # Data decryption can only be done with registered cryptors. An identifier
+      # in the cryptor data header is used to identify a suitable cryptor.
+      #
+      # @param identifier [String] A unicode cryptor identifier.
+      # @return [Cryptor, nil] Target cryptor or `nil` in case there is none
+      #   with the specified identifier.
+      def cryptor(identifier)
+        return default_cryptor if default_cryptor.identifier == identifier
+
+        additional_cryptors.fetch(identifier, nil)
+      end
+    end
+  end
+end

data/lib/pubnub/modules/crypto/crypto_provider.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Pubnub
+  module Crypto
+    # Base class which is used to implement a module that can be used to
+    # configure <b>PubNub</b> client or for manual data encryption and
+    # decryption.
+    class CryptoProvider
+      # Encrypt provided data.
+      #
+      # @param data [String] Source data for encryption.
+      # @return [String, nil] Encrypted data or <i>nil</i> in case of encryption
+      #   error.
+      def encrypt(data)
+        raise NotImplementedError, 'Subclass should provide "encrypt" method implementation.'
+      end
+
+      # Decrypt provided data.
+      #
+      # @param data [String] Encrypted data for decryption.
+      # @return [String, nil] Decrypted data or <i>nil</i> in case of decryption
+      #   error.
+      #
+      # @raise [UnknownCryptorError] If the <i>cryptor</i> for data processing is
+      #   not registered.
+      def decrypt(data)
+        raise NotImplementedError, 'Subclass should provide "decrypt" method implementation.'
+      end
+    end
+  end
+end

data/lib/pubnub/modules/crypto/cryptor.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Pubnub
+  module Crypto
+    # Encrypted data representation object.
+    #
+    # Objects contain both encrypted data and additional data created by cryptor
+    # that will be required to decrypt the data.
+    class EncryptedData
+      # Cryptor may provide here any information which will be useful when data
+      # should be decrypted.
+      #
+      # For example <i>metadata</i> may contain:
+      # * initialization vector
+      # * cipher key identifier
+      # * encrypted <i>data</i> length
+      #
+      # @return [String, nil] Cryptor-defined information.
+      attr_reader :metadata
+
+      # Encrypted data.
+      #
+      # @return [String] Encrypted data.
+      attr_reader :data
+
+      # Create encrypted data object.
+      #
+      # An object used to keep track of the results of data encryption and the
+      # additional data the <i>cryptor</i> needs to handle it later.
+      #
+      # @param data [String] Outcome of successful cryptor <i>encrypt</i> method
+      #   call.
+      # @param  metadata [String, nil] Additional information is provided by
+      #   <i>cryptor</i> so that encrypted data can be handled later.
+      def initialize(data, metadata = nil)
+        @data = data
+        @metadata = metadata
+      end
+    end
+
+    # Base class which is used to implement cryptor that should be used with
+    # <i>CryptorProvider</i> implementation for data encryption and decryption.
+    class Cryptor
+      # Identifier will be encoded into cryptor data header and passed along
+      # with encrypted <i>data</i> and <i>metadata</i>.
+      #
+      # The identifier <b>must</b> be 4 bytes long.
+      #
+      # @return [String] Unique cryptor identifier.
+      def identifier
+        raise NotImplementedError, 'Subclass should provide "identifier" method implementation.'
+      end
+
+      # Encrypt provided data.
+      #
+      # @param data [String] Source data for encryption.
+      # @return [EncryptedData, nil] Encrypted data or <i>nil</i> in case of
+      #   encryption error.
+      def encrypt(data)
+        raise NotImplementedError, 'Subclass should provide "encrypt" method implementation.'
+      end
+
+      # Decrypt provided data.
+      #
+      # @param data [EncryptedData] Encrypted data for decryption.
+      # @return [String, nil] Decrypted data or <i>nil</i> in case of decryption
+      #   error.
+      def decrypt(data)
+        raise NotImplementedError, 'Subclass should provide "decrypt" method implementation.'
+      end
+    end
+  end
+end

data/lib/pubnub/modules/crypto/cryptor_header.rb

@@ -0,0 +1,251 @@
+module Pubnub
+  module Crypto
+    # Cryptor data header.
+    #
+    # This instance used to parse header from received data and encode into
+    # binary for sending.
+    class CryptorHeader
+      module Versions
+        # Currently used cryptor data header schema version.
+        CURRENT_VERSION = 1
+
+        # Base class for cryptor data schema.
+        class CryptorHeaderData
+          # Cryptor header version.
+          #
+          # @return [Integer] Cryptor header version.
+          def version
+            raise NotImplementedError, 'Subclass should provide "version" method implementation.'
+          end
+
+          # Cryptor identifier.
+          #
+          # @return [String] Identifier of the cryptor which has been used to
+          #   encrypt data.
+          def identifier
+            raise NotImplementedError, 'Subclass should provide "identifier" method implementation.'
+          end
+
+          # Cryptor-defined data size.
+          #
+          # @return [Integer] Cryptor-defined data size.
+          def data_size
+            raise NotImplementedError, 'Subclass should provide "data_size" method implementation.'
+          end
+        end
+
+        # v1 cryptor header schema.
+        #
+        # This header consists of:
+        # * sentinel (4 bytes)
+        # * version (1 byte)
+        # * cryptor identifier (4 bytes)
+        # * cryptor data size (1 byte if less than 255 and 3 bytes in other cases)
+        # * cryptor-defined data
+        class CryptorHeaderV1Data < CryptorHeaderData
+          # Identifier of the cryptor which has been used to encrypt data.
+          #
+          # @return [String] Identifier of the cryptor which has been used to
+          #   encrypt data.
+          attr_reader :identifier
+
+          # Cryptor-defined data size.
+          #
+          # @return [Integer] Cryptor-defined data size.
+          attr_reader :data_size
+
+          # Create cryptor header data.
+          #
+          # @param identifier [String] Identifier of the cryptor which has been
+          #   used to encrypt data.
+          # @param data_size [Integer] Cryptor-defined data size.
+          def initialize(identifier, data_size)
+            @identifier = identifier
+            @data_size = data_size
+          end
+
+          def version
+            1
+          end
+        end
+      end
+
+      # Create cryptor header.
+      #
+      # @param identifier [String] Identifier of the cryptor which has been used
+      #   to encrypt data.
+      # @param metadata [String, nil] Cryptor-defined information.
+      def initialize(identifier = nil, metadata = nil)
+        @data = if identifier && identifier != '\x00\x00\x00\x00'
+                  Versions::CryptorHeaderV1Data.new(
+                    identifier.to_s,
+                    metadata&.length || 0
+                  )
+                end
+      end
+
+      # Parse cryptor header data to create instance.
+      #
+      # @param data [String] Data which <i>may</i> contain cryptor header
+      #   information.
+      # @return [CryptorHeader, nil] Header instance or <i>nil</i> in case of
+      #   encrypted data parse error.
+      #
+      # @raise [ArgumentError] Raise an exception if <i>data</i> is <i>nil</i>
+      #   or empty.
+      # @raise [UnknownCryptorError] Raise an exception if, during cryptor
+      #   header data parsing, an unknown cryptor header version is encountered.
+      def self.parse(data)
+        if data.nil? || data.empty?
+          raise ArgumentError, {
+            message: '\'data\' is required and should not be empty.'
+          }
+        end
+
+        # Data is too short to be encrypted. Assume legacy cryptor without
+        # header.
+        return CryptorHeader.new if data.length < 4 || data.unpack('A4').last != 'PNED'
+
+        # Malformed crypto header.
+        return nil if data.length < 10
+
+        # Unpack header bytes.
+        _, version, identifier, data_size = data.unpack('A4 C A4 C')
+
+        # Check whether version is within known range.
+        if version > current_version
+          raise UnknownCryptorError, {
+            message: 'Decrypting data created by unknown cryptor.'
+          }
+        end
+
+        if data_size == 255
+          data_size = data.unpack('A4 C A4 C n').last if data.length >= 12
+          return CryptorHeader.new if data.length < 12
+        end
+
+        header = CryptorHeader.new
+        header.send(
+          :update_header_data,
+          create_header_data(version.to_i, identifier.to_s, data_size.to_i)
+        )
+        header
+      end
+
+      # Overall header size.
+      #
+      # Full header size which includes:
+      # * sentinel
+      # * version
+      # * cryptor identifier
+      # * cryptor data size
+      # * cryptor-defined fields size.
+      def length
+        # Legacy payload doesn't have header.
+        return 0 if @data.nil?
+
+        9 + (data_size < 255 ? 1 : 3)
+      end
+
+      # Crypto header version Version module.
+      #
+      # @return [Integer] One of known versions from Version module.
+      def version
+        header_data&.version || 0
+      end
+
+      # Identifier of the cryptor which has been used to encrypt data.
+      #
+      # @return [String, nil] Identifier of the cryptor which has been used to
+      #   encrypt data.
+      def identifier
+        header_data&.identifier || nil
+      end
+
+      # Cryptor-defined information size.
+      #
+      # @return [Integer] Cryptor-defined information size.
+      def data_size
+        header_data&.data_size || 0
+      end
+
+      # Create cryptor header data object.
+      #
+      # @param version [Integer] Cryptor header data schema version.
+      # @param identifier [String] Encrypting cryptor identifier.
+      # @param size [Integer] Cryptor-defined data size
+      # @return [Versions::CryptorHeaderData] Cryptor header data.
+      def self.create_header_data(version, identifier, size)
+        Versions::CryptorHeaderV1Data.new(identifier, size) if version == 1
+      end
+
+      # Crypto header which is currently used to encrypt data.
+      #
+      # @return [Integer] Current cryptor header version.
+      def self.current_version
+        Versions::CURRENT_VERSION
+      end
+
+      # Serialize cryptor header.
+      #
+      # @return [String] Cryptor header data, which is serialized as a binary
+      #   string.
+      #
+      # @raise [ArgumentError] Raise an exception if a <i>cryptor</i> identifier
+      #   is not provided for a non-legacy <i>cryptor</i>.
+      def to_s
+        # We don't need to serialize header for legacy cryptor.
+        return '' if version.zero?
+
+        cryptor_identifier = identifier
+        if cryptor_identifier.nil? || cryptor_identifier.empty?
+          raise ArgumentError, {
+            message: '\'identifier\' is missing or empty.'
+          }
+        end
+
+        header_bytes = ['PNED', version, cryptor_identifier]
+        if data_size < 255
+          header_bytes.push(data_size)
+        else
+          header_bytes.push(255, data_size)
+        end
+
+        header_bytes.pack(data_size < 255 ? 'A4 C A4 C' : 'A4 C A4 C n')
+      end
+
+      private
+
+      # Versioned cryptor header data
+      #
+      # @return [Versions::CryptorHeaderData, nil] Cryptor header data.
+      def header_data
+        @data
+      end
+
+      # Update crypto header version.
+      #
+      # @param data [Versions::CryptorHeaderData] Header version number parsed from binary data.
+      def update_header_data(data)
+        @data = data
+      end
+
+      # Update crypto header version.
+      #
+      # @param value [Integer] Header version number parsed from binary data.
+      def update_version(value)
+        @version = value
+      end
+
+      # Update cryptor-defined data size.
+      #
+      # @param value [Integer] Cryptor-defined data size parsed from binary
+      #   data.
+      def update_data_size(value)
+        @data_size = value
+      end
+
+      private_class_method :create_header_data, :current_version
+    end
+  end
+end