symmetric-encryption 0.4.0 → 0.5.0

data/lib/{symmetric/railties/symmetric_encrypted_validator.rb → symmetric_encryption/railties/symmetric_encryption_validator.rb}

@@ -2,17 +2,17 @@
 #
 # Example:
 #  class MyModel < ActiveRecord::Base
-#    validates :encrypted_ssn, :symmetric_encrypted => true
+#    validates :encrypted_ssn, :symmetric_encryption => true
 #  end
 #
 #  m = MyModel.new
 #  m.valid?
 #  #  => false
-#  m.encrypted_ssn = Symmetric::Encryption.encrypt('123456789')
+#  m.encrypted_ssn = SymmetricEncryption.encrypt('123456789')
 #  m.valid?
 #  #  => true
-class SymmetricEncryptedValidator < ActiveModel::EachValidator
+class SymmetricEncryptionValidator < ActiveModel::EachValidator
   def validate_each(record, attribute, value)
-    record.errors.add(attribute, "must be a value encrypted using Symmetric::Encryption.encrypt") unless Symmetric::Encryption.encrypted?(value)
+    record.errors.add(attribute, "must be a value encrypted using SymmetricEncryption.encrypt") unless SymmetricEncryption.encrypted?(value)
   end
 end

data/lib/symmetric_encryption/reader.rb

@@ -0,0 +1,221 @@
+module SymmetricEncryption
+  # Read from encrypted files and other IO streams
+  #
+  # Features:
+  # * Decryption on the fly whilst reading files
+  # * Large file support by only buffering small amounts of data in memory
+  #
+  # # Example: Read and decrypt a line at a time from a file
+  # SymmetricEncryption::Reader.open('test_file') do |file|
+  #   file.each_line {|line| p line }
+  # end
+  #
+  # # Example: Read and decrypt entire file in memory
+  # # Not recommended for large files
+  # SymmetricEncryption::Reader.open('test_file') {|f| f.read }
+  #
+  # # Example: Reading a limited number of bytes at a time from the file
+  # SymmetricEncryption::Reader.open('test_file') do |file|
+  #   file.read(1)
+  #   file.read(5)
+  #   file.read
+  # end
+  #
+  # # Example: Read and decrypt 5 bytes at a time until the end of file is reached
+  # SymmetricEncryption::Reader.open('test_file') do |file|
+  #   while !file.eof? do
+  #     file.read(5)
+  #   end
+  # end
+  #
+  # # Example: Read, Unencrypt and decompress data in a file
+  # SymmetricEncryption::Reader.open('encrypted_compressed.zip', :compress => true) do |file|
+  #   file.each_line {|line| p line }
+  # end
+  class Reader
+    # Open a file for reading, or use the supplied IO Stream
+    #
+    # Parameters:
+    #   filename_or_stream:
+    #     The filename to open if a string, otherwise the stream to use
+    #     The file or stream will be closed on completion, use .initialize to
+    #     avoid having the stream closed automatically
+    #
+    #   options:
+    #     :compress [true|false]
+    #          Uses Zlib to decompress the data after it is decrypted
+    #          Note: This option is only used if the file does not have a header
+    #                indicating whether it is compressed
+    #          Default: false
+    #
+    #     :version
+    #          Version of the encryption key to use when decrypting and the
+    #          file/stream does not include a header at the beginning
+    #          Default: Current primary key
+    #
+    #     :mode
+    #          See File.open for open modes
+    #          Default: 'r'
+    #
+    #     :buffer_size
+    #          Amount of data to read at a time
+    #          Default: 4096
+    #
+    # Note: Decryption occurs before decompression
+    def self.open(filename_or_stream, options={}, &block)
+      raise "options must be a hash" unless options.respond_to?(:each_pair)
+      mode = options.fetch(:mode, 'r')
+      compress = options.fetch(:compress, false)
+      ios = filename_or_stream.is_a?(String) ? ::File.open(filename_or_stream, mode) : filename_or_stream
+
+      begin
+        file = self.new(ios, options)
+        file = Zlib::GzipReader.new(file) if file.compressed? || compress
+        block.call(file)
+      ensure
+        file.close if file
+      end
+    end
+
+    # Decrypt data before reading from the supplied stream
+    def initialize(ios,options={})
+      @ios         = ios
+      @buffer_size = options.fetch(:buffer_size, 4096).to_i
+      @compressed  = nil
+      @read_buffer = ''
+
+      # Read first block and check for the header
+      buf = @ios.read(@buffer_size)
+      if buf.start_with?(SymmetricEncryption::MAGIC_HEADER)
+        # Header includes magic header and version byte
+        # Remove header and extract flags
+        header, flags = buf.slice!(0..MAGIC_HEADER_SIZE).unpack(MAGIC_HEADER_UNPACK)
+        @compressed = flags & 0b1000_0000_0000_0000
+        @version = @compressed ? flags - 0b1000_0000_0000_0000 : flags
+      else
+        @version = options[:version]
+      end
+
+      # Use primary cipher by default, but allow a secondary cipher to be selected for encryption
+      @cipher = SymmetricEncryption.cipher(@version)
+      raise "Cipher with version:#{@version} not found in any of the configured SymmetricEncryption ciphers" unless @cipher
+      @stream_cipher = @cipher.send(:openssl_cipher, :decrypt)
+
+      # First call to #update should return an empty string anyway
+      @read_buffer << @stream_cipher.update(buf)
+      @read_buffer << @stream_cipher.final if @ios.eof?
+    end
+
+    # Returns whether the stream being read is compressed
+    #
+    # Should be called before any reads are performed to determine if the file or
+    # stream is compressed.
+    #
+    # Returns true when the header is present in the stream and it is compressed
+    # Returns false when the header is present in the stream and it is not compressed
+    # Returns nil when the header is not present in the stream
+    #
+    # Note: The file will not be decompressed automatically when compressed.
+    #       To decompress the data automatically call SymmetricEncryption.open
+    def compressed?
+      @compressed
+    end
+
+    # Returns the Cipher encryption version used to encrypt this file
+    # Returns nil when the header was not present in the stream and no :version
+    #         option was supplied
+    #
+    # Note: When no header is present, the version is set to the one supplied
+    #       in the options
+    def version
+      @version
+    end
+
+    # Close the IO Stream
+    #
+    # Note: Also closes the passed in io stream or file
+    #
+    # It is recommended to call Symmetric::EncryptedStream.open or Symmetric::EncryptedStream.io
+    # rather than creating an instance of Symmetric::EncryptedStream directly to
+    # ensure that the encrypted stream is closed before the stream itself is closed
+    def close(close_child_stream = true)
+      @ios.close if close_child_stream
+    end
+
+    # Read from the stream and return the decrypted data
+    # See IOS#read
+    #
+    # Reads at most length bytes from the I/O stream, or to the end of file if
+    # length is omitted or is nil. length must be a non-negative integer or nil.
+    #
+    # At end of file, it returns nil or "" depending on length.
+    def read(length=nil)
+      data = nil
+      if length
+        return '' if length == 0
+        # Read length bytes
+        while (@read_buffer.length < length) && !@ios.eof?
+          read_block
+        end
+        if @read_buffer.length > length
+          data = @read_buffer.slice!(0..length-1)
+        else
+          data = @read_buffer
+          @read_buffer = ''
+        end
+      else
+        # Capture anything already in the buffer
+        data = @read_buffer
+        @read_buffer = ''
+
+        if !@ios.eof?
+          # Read entire file
+          buf = @ios.read || ''
+          data << @stream_cipher.update(buf) if buf && buf.length > 0
+          data << @stream_cipher.final
+        end
+      end
+      data
+    end
+
+    # Reads a single decrypted line from the file up to and including the optional sep_string.
+    # Returns nil on eof
+    # The stream must be opened for reading or an IOError will be raised.
+    def readline(sep_string = "\n")
+      # Read more data until we get the sep_string
+      while (index = @read_buffer.index(sep_string)).nil? && !@ios.eof?
+        read_block
+      end
+      index ||= -1
+      @read_buffer.slice!(0..index)
+    end
+
+    # ios.each(sep_string="\n") {|line| block } => ios
+    # ios.each_line(sep_string="\n") {|line| block } => ios
+    # Executes the block for every line in ios, where lines are separated by sep_string.
+    # ios must be opened for reading or an IOError will be raised.
+    def each_line(sep_string = "\n")
+      while !eof?
+        yield readline(sep_string)
+      end
+      self
+    end
+
+    alias_method :each, :each_line
+
+    # Returns whether the end of file has been reached for this stream
+    def eof?
+      (@read_buffer.size == 0) && @ios.eof?
+    end
+
+    private
+
+    # Read a block of data and append the decrypted data in the read buffer
+    def read_block
+      buf = @ios.read(@buffer_size)
+      @read_buffer << @stream_cipher.update(buf) if buf && buf.length > 0
+      @read_buffer << @stream_cipher.final if @ios.eof?
+    end
+
+  end
+end

data/lib/symmetric_encryption/symmetric_encryption.rb

@@ -0,0 +1,280 @@
+require 'base64'
+require 'openssl'
+require 'zlib'
+require 'yaml'
+
+# Encrypt using 256 Bit AES CBC symmetric key and initialization vector
+# The symmetric key is protected using the private key below and must
+# be distributed separately from the application
+module SymmetricEncryption
+
+  # Defaults
+  @@cipher = nil
+  @@secondary_ciphers = []
+
+  # Set the Primary Symmetric Cipher to be used
+  def self.cipher=(cipher)
+    raise "Cipher must be similar to SymmetricEncryption::Ciphers" unless cipher.respond_to?(:encrypt) && cipher.respond_to?(:decrypt)
+    @@cipher = cipher
+  end
+
+  # Returns the Primary Symmetric Cipher being used
+  # If a version is supplied, then the cipher matching that version will be
+  # returned or nil if no match was found
+  def self.cipher(version = nil)
+    return @@cipher if version.nil? || (@@cipher.version == version)
+    secondary_ciphers.find {|c| c.version == version}
+  end
+
+  # Set the Secondary Symmetric Ciphers Array to be used
+  def self.secondary_ciphers=(secondary_ciphers)
+    raise "secondary_ciphers must be a collection" unless secondary_ciphers.respond_to? :each
+    secondary_ciphers.each do |cipher|
+      raise "secondary_ciphers can only consist of SymmetricEncryption::Ciphers" unless cipher.respond_to?(:encrypt) && cipher.respond_to?(:decrypt)
+    end
+    @@secondary_ciphers = secondary_ciphers
+  end
+
+  # Returns the Primary Symmetric Cipher being used
+  def self.secondary_ciphers
+    @@secondary_ciphers
+  end
+
+  # AES Symmetric Decryption of supplied string
+  #  Returns decrypted string
+  #  Returns nil if the supplied str is nil
+  #  Returns "" if it is a string and it is empty
+  #
+  # Note: If secondary ciphers are supplied in the configuration file the
+  #   first key will be used to decrypt 'str'. If it fails each cipher in the
+  #   order supplied will be tried.
+  #   It is slow to try each cipher in turn, so should be used during migrations
+  #   only
+  #
+  # Raises: OpenSSL::Cipher::CipherError when 'str' was not encrypted using
+  # the supplied key and iv
+  #
+  def self.decrypt(str)
+    raise "Call SymmetricEncryption.load! or SymmetricEncryption.cipher= prior to encrypting or decrypting data" unless @@cipher
+    binary = ::Base64.decode64(str) if str
+    begin
+      @@cipher.decrypt(binary)
+    rescue OpenSSL::Cipher::CipherError => exc
+      @@secondary_ciphers.each do |cipher|
+        begin
+          return cipher.decrypt(binary)
+        rescue OpenSSL::Cipher::CipherError
+        end
+      end
+      raise exc
+    end
+  end
+
+  # AES Symmetric Encryption of supplied string
+  #  Returns result as a Base64 encoded string
+  #  Returns nil if the supplied str is nil
+  #  Returns "" if it is a string and it is empty
+  def self.encrypt(str)
+    raise "Call SymmetricEncryption.load! or SymmetricEncryption.cipher= prior to encrypting or decrypting data" unless @@cipher
+
+    # Encrypt data as a binary string
+    result = @@cipher.encrypt(str)
+
+    # Base 64 Encoding of binary data
+    result = ::Base64.encode64(result) if result
+    result
+  end
+
+  # Invokes decrypt
+  #  Returns decrypted String
+  #  Return nil if it fails to decrypt a String
+  #
+  # Useful for example when decoding passwords encrypted using a key from a
+  # different environment. I.e. We cannot decode production passwords
+  # in the test or development environments but still need to be able to load
+  # YAML config files that contain encrypted development and production passwords
+  def self.try_decrypt(str)
+    raise "Call SymmetricEncryption.load! or SymmetricEncryption.cipher= prior to encrypting or decrypting data" unless @@cipher
+    begin
+      decrypt(str)
+    rescue OpenSSL::Cipher::CipherError
+      nil
+    end
+  end
+
+  # Returns [true|false] as to whether the data could be decrypted
+  #   Parameters:
+  #     encrypted_data: Encrypted string
+  def self.encrypted?(encrypted_data)
+    raise "Call SymmetricEncryption.load! or SymmetricEncryption.cipher= prior to encrypting or decrypting data" unless @@cipher
+
+    # First make sure Base64 encoded data still ends with "\n" since it could be used in a key field somewhere
+    return false unless encrypted_data.end_with?("\n")
+
+    # For now have to decrypt it fully
+    !try_decrypt(encrypted_data).nil?
+  end
+
+  # Load the Encryption Configuration from a YAML file
+  #  filename:
+  #    Name of file to read.
+  #        Mandatory for non-Rails apps
+  #        Default: Rails.root/config/symmetric-encryption.yml
+  #  environment:
+  #    Which environments config to load. Usually: production, development, etc.
+  #    Default: Rails.env
+  def self.load!(filename=nil, environment=nil)
+    config = read_config(filename, environment)
+
+    # Check for hard coded key, iv and cipher
+    if config[:key]
+      @@cipher = Cipher.new(config)
+      @@secondary_ciphers = []
+    else
+      private_rsa_key = config[:private_rsa_key]
+      @@cipher, *@@secondary_ciphers = config[:ciphers].collect do |cipher_conf|
+        cipher_from_encrypted_files(
+          private_rsa_key,
+          cipher_conf[:cipher],
+          cipher_conf[:key_filename],
+          cipher_conf[:iv_filename])
+      end
+    end
+
+    true
+  end
+
+  # Future: Generate private key in config file generator
+  #new_key = OpenSSL::PKey::RSA.generate(2048)
+
+  # Generate new random symmetric keys for use with this Encryption library
+  #
+  # Note: Only the current Encryption key settings are used
+  #
+  # Creates Symmetric Key .key
+  #   and initilization vector .iv
+  #       which is encrypted with the above Public key
+  #
+  # Warning: Existing files will be overwritten
+  def self.generate_symmetric_key_files(filename=nil, environment=nil)
+    config = read_config(filename, environment)
+    cipher_cfg = config[:ciphers].first
+    key_filename = cipher_cfg[:key_filename]
+    iv_filename = cipher_cfg[:iv_filename]
+    cipher = cipher_cfg[:cipher]
+
+    raise "The configuration file must contain a 'private_rsa_key' parameter to generate symmetric keys" unless config[:private_rsa_key]
+    rsa_key = OpenSSL::PKey::RSA.new(config[:private_rsa_key])
+
+    # Generate a new Symmetric Key pair
+    key_pair = SymmetricEncryption::Cipher.random_key_pair(cipher || 'aes-256-cbc', !iv_filename.nil?)
+
+    # Save symmetric key after encrypting it with the private RSA key, backing up existing files if present
+    File.rename(key_filename, "#{key_filename}.#{Time.now.to_i}") if File.exist?(key_filename)
+    File.open(key_filename, 'wb') {|file| file.write( rsa_key.public_encrypt(key_pair[:key]) ) }
+
+    if iv_filename
+      File.rename(iv_filename, "#{iv_filename}.#{Time.now.to_i}") if File.exist?(iv_filename)
+      File.open(iv_filename, 'wb') {|file| file.write( rsa_key.public_encrypt(key_pair[:iv]) ) }
+    end
+    puts("Generated new Symmetric Key for encryption. Please copy #{key_filename} and #{iv_filename} to the other web servers in #{environment}.")
+  end
+
+  # Generate a 22 character random password
+  def self.random_password
+    Base64.encode64(OpenSSL::Cipher.new('aes-128-cbc').random_key)[0..-4]
+  end
+
+  # Binary encrypted data includes this magic header so that we can quickly
+  # identify binary data versus base64 encoded data that does not have this header
+  unless defined? MAGIC_HEADER
+    MAGIC_HEADER = '@EnC'
+    MAGIC_HEADER_SIZE = MAGIC_HEADER.size
+    MAGIC_HEADER_UNPACK = "A#{MAGIC_HEADER_SIZE}v"
+  end
+
+  protected
+
+  # Returns the Encryption Configuration
+  #
+  # Read the configuration from the YAML file and return in the latest format
+  #
+  #  filename:
+  #    Name of file to read.
+  #        Mandatory for non-Rails apps
+  #        Default: Rails.root/config/symmetric-encryption.yml
+  #  environment:
+  #    Which environments config to load. Usually: production, development, etc.
+  def self.read_config(filename=nil, environment=nil)
+    config = YAML.load_file(filename || File.join(Rails.root, "config", "symmetric-encryption.yml"))[environment || Rails.env]
+
+    # Default cipher
+    default_cipher = config['cipher'] || 'aes-256-cbc'
+    cfg = {}
+
+    # Hard coded symmetric_key? - Dev / Testing use only!
+    if symmetric_key = (config['key'] || config['symmetric_key'])
+      raise "SymmetricEncryption Cannot hard code Production encryption keys in #{filename}" if (environment || Rails.env) == 'production'
+      cfg[:key]     = symmetric_key
+      cfg[:iv]      = config['iv'] || config['symmetric_iv']
+      cfg[:cipher]  = default_cipher
+
+    elsif ciphers = config['ciphers']
+      raise "Missing mandatory config parameter 'private_rsa_key'" unless cfg[:private_rsa_key] = config['private_rsa_key']
+
+      cfg[:ciphers] = ciphers.collect do |cipher_cfg|
+        key_filename = cipher_cfg['key_filename'] || cipher_cfg['symmetric_key_filename']
+        raise "Missing mandatory 'key_filename' for environment:#{environment} in #{filename}" unless key_filename
+        iv_filename = cipher_cfg['iv_filename'] || cipher_cfg['symmetric_iv_filename']
+        {
+          :cipher       => cipher_cfg['cipher'] || default_cipher,
+          :key_filename => key_filename,
+          :iv_filename  => iv_filename,
+        }
+      end
+
+    else
+      # Migrate old format config
+      raise "Missing mandatory config parameter 'private_rsa_key'" unless cfg[:private_rsa_key] = config['private_rsa_key']
+      cfg[:ciphers] = [ {
+          :cipher       => default_cipher,
+          :key_filename => config['symmetric_key_filename'],
+          :iv_filename  => config['symmetric_iv_filename'],
+        } ]
+    end
+
+    cfg
+  end
+
+  # Returns an instance of SymmetricEncryption::Cipher initialized from keys
+  # stored in files
+  #
+  # Raises an Exception on failure
+  #
+  # Parameters:
+  #   cipher
+  #     Encryption cipher for the symmetric encryption key
+  #   private_key
+  #     Key used to unlock file containing the actual symmetric key
+  #   key_filename
+  #     Name of file containing symmetric key encrypted using the public
+  #     key matching the supplied private_key
+  #   iv_filename
+  #     Optional. Name of file containing symmetric key initialization vector
+  #     encrypted using the public key matching the supplied private_key
+  def self.cipher_from_encrypted_files(private_rsa_key, cipher, key_filename, iv_filename = nil)
+    # Load Encrypted Symmetric keys
+    encrypted_key = File.read(key_filename)
+    encrypted_iv = File.read(iv_filename) if iv_filename
+
+    # Decrypt Symmetric Keys
+    rsa = OpenSSL::PKey::RSA.new(private_rsa_key)
+    iv = rsa.private_decrypt(encrypted_iv) if iv_filename
+    Cipher.new(
+      :key    => rsa.private_decrypt(encrypted_key),
+      :iv     => iv,
+      :cipher => cipher
+    )
+  end
+
+end