symmetric-encryption 4.1.2 → 4.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ada00eaa90ed1edb19723bfc1e0e34f3e6f8be5f060b6c2a79eaf046483f77b0
-  data.tar.gz: 0bf3ae34653d9598fc0a0be1058aa366f1e401b053bad92995ef08f00dc1fcbc
+  metadata.gz: cc6728652282c5b73acde1b45427e7dbce0092ceecc197a052f5364b83c53e28
+  data.tar.gz: dad8b275ffd46adf20d2b3f51c7673b79e1cc359750626d4207f203a207c14f0
 SHA512:
-  metadata.gz: 8299b773b5fbe49452187aeaa746343e9aff7c49a86f226142ae105a1aa9d1ad29401aa44297d19c6ae79161c2e8f0a9ad4f159e36c7191df5b36bb704367ef1
-  data.tar.gz: f9a37ecd2aa9c95eeb543e08be08de1a859bb1e0745241d9e983534e9b3df334bcc1486f6a46430ab2bfeaa5286a5902bffacaced9c9c0d53526cfe16d29b357
+  metadata.gz: efd513c2c0b22b5252583a3d8207d89f907b695f6edf6c75d0f7a2c9177e8d32d5566d7228f36b7039318d4e72380f4cee4090048cf40f7bf50a492bf525fcc5
+  data.tar.gz: bac21c5250923fd85134cc3a59e220ec2c87c85e4dc7f4efef280110c01852dd202256bcad5671d96dd7c7424c531b2bd237f0f9f85d5ac22bce24415ab6fcde

data/README.md

@@ -1,9 +1,9 @@
 # Symmetric Encryption
-![](https://img.shields.io/gem/v/symmetric-encryption.svg) ![](https://img.shields.io/travis/rocketjob/symmetric-encryption.svg) ![](https://img.shields.io/gem/dt/symmetric-encryption.svg)  ![](https://img.shields.io/badge/status-production%20ready-blue.svg)
+[![Gem Version](https://img.shields.io/gem/v/symmetric-encryption.svg)](https://rubygems.org/gems/symmetric-encryption) [![Build Status](https://github.com/reidmorrison/symmetric-encryption/workflows/build/badge.svg)](https://github.com/reidmorrison/symmetric-encryption/actions?query=workflow%3Abuild) [![Downloads](https://img.shields.io/gem/dt/symmetric-encryption.svg)](https://rubygems.org/gems/symmetric-encryption) [![License](https://img.shields.io/badge/license-Apache%202.0-brightgreen.svg)](http://opensource.org/licenses/Apache-2.0) ![](https://img.shields.io/badge/status-Production%20Ready-blue.svg) 
 
-* http://github.com/rocketjob/symmetric-encryption
+* https://encryption.rocketjob.io/
 
-Transparently encrypt ActiveRecord, Mongoid, and MongoMapper attributes. Encrypt passwords in configuration files. Encrypt entire files at rest.
+Transparently encrypt ActiveRecord, and Mongoid attributes. Encrypt passwords in configuration files. Encrypt entire files at rest.
 
 ## Introduction
 
@@ -19,9 +19,7 @@ expose all the encryption algorithms supported by OpenSSL.
 
 ## Documentation
 
-[Symmetric Encryption Guide](http://rocketjob.github.io/symmetric-encryption)
-
-[Reference Documentation](http://www.rubydoc.info/gems/symmetric-encryption/)
+[Symmetric Encryption Guide](https://encryption.rocketjob.io/)
 
 ## Rocket Job
 
@@ -168,7 +166,7 @@ may have backward compatibility issues:
 
 [Reid Morrison](https://github.com/reidmorrison)
 
-[Contributors](https://github.com/rocketjob/symmetric-encryption/graphs/contributors)
+[Contributors](https://github.com/reidmorrison/symmetric-encryption/graphs/contributors)
 
 ## Versioning
 

data/Rakefile

@@ -1,30 +1,30 @@
 # Setup bundler to avoid having to run bundle exec all the time.
-require 'rubygems'
-require 'bundler/setup'
+require "rubygems"
+require "bundler/setup"
 
-require 'rake/testtask'
-require_relative 'lib/symmetric_encryption/version'
+require "rake/testtask"
+require_relative "lib/symmetric_encryption/version"
 
 task :gem do
-  system 'gem build symmetric-encryption.gemspec'
+  system "gem build symmetric-encryption.gemspec"
 end
 
 task publish: :gem do
   system "git tag -a v#{SymmetricEncryption::VERSION} -m 'Tagging #{SymmetricEncryption::VERSION}'"
-  system 'git push --tags'
+  system "git push --tags"
   system "gem push symmetric-encryption-#{SymmetricEncryption::VERSION}.gem"
   system "rm symmetric-encryption-#{SymmetricEncryption::VERSION}.gem"
 end
 
 Rake::TestTask.new(:test) do |t|
-  t.pattern = 'test/**/*_test.rb'
+  t.pattern = "test/**/*_test.rb"
   t.verbose = true
   t.warning = false
 end
 
 # By default run tests against all appraisals
-if !ENV['APPRAISAL_INITIALIZED'] && !ENV['TRAVIS']
-  require 'appraisal'
+if !ENV["APPRAISAL_INITIALIZED"] && !ENV["TRAVIS"]
+  require "appraisal"
   task default: :appraisal
 else
   task default: :test

data/bin/symmetric-encryption

@@ -1,5 +1,5 @@
 #!/usr/bin/env ruby
 
-require 'symmetric_encryption'
+require "symmetric_encryption"
 
 SymmetricEncryption::CLI.run!(ARGV)

data/lib/symmetric-encryption.rb

@@ -1 +1 @@
-require 'symmetric_encryption'
+require "symmetric_encryption"

data/lib/symmetric_encryption/active_record/attr_encrypted.rb

@@ -0,0 +1,129 @@
+module SymmetricEncryption
+  module ActiveRecord
+    module AttrEncrypted
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      module ClassMethods
+        # Transparently encrypt and decrypt values stored via ActiveRecord.
+        #
+        # Parameters:
+        # * Symbolic names of each method to create which has a corresponding
+        #   method already defined in rails starting with: encrypted_
+        # * Followed by an optional hash:
+        #     :random_iv [true|false]
+        #       Whether the encrypted value should use a random IV every time the
+        #       field is encrypted.
+        #       It is recommended to set this to true where feasible. If the encrypted
+        #       value could be used as part of a SQL where clause, or as part
+        #       of any lookup, then it must be false.
+        #       Setting random_iv to true will result in a different encrypted output for
+        #       the same input string.
+        #       Note: Only set to true if the field will never be used as part of
+        #         the where clause in an SQL query.
+        #       Note: When random_iv is true it will add a 8 byte header, plus the bytes
+        #         to store the random IV in every returned encrypted string, prior to the
+        #         encoding if any.
+        #       Default: false
+        #       Highly Recommended where feasible: true
+        #
+        #     :type [Symbol]
+        #       The type for this field, #see SymmetricEncryption::COERCION_TYPES
+        #       Default: :string
+        #
+        #     :compress [true|false]
+        #       Whether to compress str before encryption
+        #       Should only be used for large strings since compression overhead and
+        #       the overhead of adding the 'magic' header may exceed any benefits of
+        #       compression
+        #       Note: Adds a 6 byte header prior to encoding, only if :random_iv is false
+        #       Default: false
+        def attr_encrypted(*attributes, random_iv: nil, type: :string, compress: false)
+          # Ensure ActiveRecord has created all its methods first
+          # Ignore failures since the table may not yet actually exist
+          begin
+            define_attribute_methods
+          rescue StandardError
+            nil
+          end
+
+          random_iv = true if random_iv.nil? && SymmetricEncryption.randomize_iv?
+
+          if random_iv.nil?
+            warn("attr_encrypted() no longer allows a default value for option `random_iv`. Add `random_iv: false` if it is required.")
+          end
+
+          attributes.each do |attribute|
+            SymmetricEncryption::Generator.generate_decrypted_accessors(
+              self,
+              attribute,
+              "encrypted_#{attribute}",
+              random_iv: random_iv,
+              type:      type,
+              compress:  compress
+            )
+            encrypted_attributes[attribute.to_sym] = "encrypted_#{attribute}".to_sym
+          end
+        end
+
+        # Contains a hash of encrypted attributes with virtual attribute names as keys and real attribute
+        # names as values
+        #
+        # Example
+        #
+        #   class User < ActiveRecord::Base
+        #     attr_encrypted :email
+        #   end
+        #
+        #   User.encrypted_attributes  =>  { email: encrypted_email }
+        def encrypted_attributes
+          @encrypted_attributes ||= superclass.respond_to?(:encrypted_attributes) ? superclass.encrypted_attributes.dup : {}
+        end
+
+        # Return the name of all encrypted virtual attributes as an Array of symbols
+        # Example: [:email, :password]
+        def encrypted_keys
+          @encrypted_keys ||= encrypted_attributes.keys
+        end
+
+        # Return the name of all encrypted columns as an Array of symbols
+        # Example: [:encrypted_email, :encrypted_password]
+        def encrypted_columns
+          @encrypted_columns ||= encrypted_attributes.values
+        end
+
+        # Returns whether an attribute has been configured to be encrypted
+        #
+        # Example
+        #
+        #   class User < ActiveRecord::Base
+        #     attr_accessor :name
+        #     attr_encrypted :email
+        #   end
+        #
+        #   User.encrypted_attribute?(:name) # false
+        #   User.encrypted_attribute?(:email) # true
+        def encrypted_attribute?(attribute)
+          encrypted_keys.include?(attribute)
+        end
+
+        # Returns whether the attribute is the database column to hold the
+        # encrypted data for a matching encrypted attribute
+        #
+        # Example
+        #
+        #   class User < ActiveRecord::Base
+        #     attr_accessor :name
+        #     attr_encrypted :email
+        #   end
+        #
+        #   User.encrypted_column?(:encrypted_name) # false
+        #   User.encrypted_column?(:encrypted_email) # true
+        def encrypted_column?(attribute)
+          encrypted_columns.include?(attribute)
+        end
+      end
+    end
+  end
+end

data/lib/symmetric_encryption/active_record/encrypted_attribute.rb

@@ -0,0 +1,37 @@
+module SymmetricEncryption
+  module ActiveRecord
+    class EncryptedAttribute < ::ActiveModel::Type::String
+      def initialize(random_iv: true, compress: false, type: :string)
+        @random_iv      = random_iv
+        @compress       = compress
+        @encrypted_type = type
+      end
+
+      def deserialize(value)
+        return if value.nil?
+
+        SymmetricEncryption.decrypt(value, type: encrypted_type)
+      end
+
+      def serialize(value)
+        return if value.nil?
+
+        SymmetricEncryption.encrypt(
+          value,
+          type:      encrypted_type,
+          compress:  compress,
+          random_iv: random_iv
+        )
+      end
+
+      private
+
+      # Symmetric Encryption uses coercible gem to handle casting
+      def cast_value(value)
+        value
+      end
+
+      attr_reader :random_iv, :compress, :encrypted_type
+    end
+  end
+end

data/lib/symmetric_encryption/cipher.rb

@@ -1,4 +1,4 @@
-require 'openssl'
+require "openssl"
 module SymmetricEncryption
   # Hold all information related to encryption keys
   # as well as encrypt and decrypt data using those keys.
@@ -12,7 +12,7 @@ module SymmetricEncryption
     attr_writer :key
 
     # Returns [Cipher] from a cipher config instance.
-    def self.from_config(cipher_name: 'aes-256-cbc',
+    def self.from_config(cipher_name: "aes-256-cbc",
                          version: 0,
                          always_add_header: true,
                          encoding: :base64strict,
@@ -50,6 +50,8 @@ module SymmetricEncryption
     #       This is the recommended format since newlines in the values to
     #       SQL queries are cumbersome. Also the newline reformatting is unnecessary
     #       It is not the default for backward compatibility
+    #     :base64urlsafe
+    #       Same as base64strict except that base64urlsafe uses '-' instead of '+' and '_' instead of '/'.
     #     :base64
     #       Return as a base64 encoded string
     #     :base16
@@ -58,7 +60,7 @@ module SymmetricEncryption
     #       Return as raw binary data string. Note: String can contain embedded nulls
     #     Default: :base64strict
     #
-    #   version [Fixnum]
+    #   version [Integer]
     #     Optional. The version number of this encryption key
     #     Used by SymmetricEncryption to select the correct key when decrypting data
     #     Valid Range: 0..255
@@ -72,7 +74,7 @@ module SymmetricEncryption
     #     Default: true
     def initialize(key:,
                    iv: nil,
-                   cipher_name: 'aes-256-cbc',
+                   cipher_name: "aes-256-cbc",
                    version: 0,
                    always_add_header: true,
                    encoding: :base64strict)
@@ -84,7 +86,9 @@ module SymmetricEncryption
       @version           = version.to_i
       @always_add_header = always_add_header
 
-      raise(ArgumentError, "Cipher version has a valid range of 0 to 255. #{@version} is too high, or negative") if (@version > 255) || @version.negative?
+      return unless (@version > 255) || @version.negative?
+
+      raise(ArgumentError, "Cipher version has a valid range of 0 to 255. #{@version} is too high, or negative")
     end
 
     # Change the encoding
@@ -112,7 +116,7 @@ module SymmetricEncryption
     #     to convert it to a string
     #
     #   random_iv [true|false]
-    #     Whether the encypted value should use a random IV every time the
+    #     Whether the encrypted value should use a random IV every time the
     #     field is encrypted.
     #     Notes:
     #     * Setting random_iv to true will result in a different encrypted output for
@@ -131,7 +135,7 @@ module SymmetricEncryption
     #     * Should only be used for large strings since compression overhead and
     #       the overhead of adding the encryption header may exceed any benefits of
     #       compression
-    def encrypt(str, random_iv: false, compress: false, header: always_add_header)
+    def encrypt(str, random_iv: SymmetricEncryption.randomize_iv?, compress: false, header: always_add_header)
       return if str.nil?
 
       str = str.to_s
@@ -167,7 +171,9 @@ module SymmetricEncryption
       decrypted = binary_decrypt(decoded)
 
       # Try to force result to UTF-8 encoding, but if it is not valid, force it back to Binary
-      decrypted.force_encoding(SymmetricEncryption::BINARY_ENCODING) unless decrypted.force_encoding(SymmetricEncryption::UTF8_ENCODING).valid_encoding?
+      unless decrypted.force_encoding(SymmetricEncryption::UTF8_ENCODING).valid_encoding?
+        decrypted.force_encoding(SymmetricEncryption::BINARY_ENCODING)
+      end
 
       decrypted
     end
@@ -180,7 +186,7 @@ module SymmetricEncryption
     #
     # Returned string is UTF8 encoded except for encoding :none
     def encode(binary_string)
-      return binary_string if binary_string.nil? || (binary_string == '')
+      return binary_string if binary_string.nil? || (binary_string == "")
 
       encoder.encode(binary_string)
     end
@@ -190,7 +196,7 @@ module SymmetricEncryption
     #
     # Returned string is Binary encoded
     def decode(encoded_string)
-      return encoded_string if encoded_string.nil? || (encoded_string == '')
+      return encoded_string if encoded_string.nil? || (encoded_string == "")
 
       encoder.decode(encoded_string)
     end
@@ -246,7 +252,7 @@ module SymmetricEncryption
     #     Default: `always_add_header`
     #
     # See #encrypt to encrypt and encode the result as a string.
-    def binary_encrypt(str, random_iv: false, compress: false, header: always_add_header)
+    def binary_encrypt(str, random_iv: SymmetricEncryption.randomize_iv?, compress: false, header: always_add_header)
       return if str.nil?
 
       string = str.to_s
@@ -316,8 +322,8 @@ module SymmetricEncryption
 
       openssl_cipher = ::OpenSSL::Cipher.new(header.cipher_name || cipher_name)
       openssl_cipher.decrypt
-      openssl_cipher.key  = header.key || @key
-      if (iv              = header.iv || @iv)
+      openssl_cipher.key = header.key || @key
+      if (iv = header.iv || @iv)
         openssl_cipher.iv = iv
       end
       result = openssl_cipher.update(data)
@@ -327,7 +333,7 @@ module SymmetricEncryption
 
     # Returns the magic header after applying the encoding in this cipher
     def encoded_magic_header
-      @encoded_magic_header ||= encoder.encode(SymmetricEncryption::Header::MAGIC_HEADER).delete('=').strip
+      @encoded_magic_header ||= encoder.encode(SymmetricEncryption::Header::MAGIC_HEADER).delete("=").strip
     end
 
     # Returns [String] object represented as a string, filtering out the key