module AttrEncrypted

Adds attr_accessors that encrypt and decrypt an object's attributes

Public Instance Methods

attr_encrypted(*attributes) click to toggle source

encode_salt:          Defaults to true.

default_encoding:     Defaults to 'm' (base64).

marshal:              If set to true, attributes will be marshaled as well
                      as encrypted. This is useful if you're planning on
                      encrypting something other than a string.
                      Defaults to false.

marshaler:            The object to use for marshaling.
                      Defaults to Marshal.

dump_method:          The dump method name to call on the <tt>:marshaler</tt> object to.
                      Defaults to 'dump'.

load_method:          The load method name to call on the <tt>:marshaler</tt> object.
                      Defaults to 'load'.

encryptor:            The object to use for encrypting.
                      Defaults to Encryptor.

encrypt_method:       The encrypt method name to call on the <tt>:encryptor</tt> object.
                      Defaults to 'encrypt'.

decrypt_method:       The decrypt method name to call on the <tt>:encryptor</tt> object.
                      Defaults to 'decrypt'.

if:                   Attributes are only encrypted if this option evaluates
                      to true. If you pass a symbol representing an instance
                      method then the result of the method will be evaluated.
                      Any objects that respond to <tt>:call</tt> are evaluated as well.
                      Defaults to true.

unless:               Attributes are only encrypted if this option evaluates
                      to false. If you pass a symbol representing an instance
                      method then the result of the method will be evaluated.
                      Any objects that respond to <tt>:call</tt> are evaluated as well.
                      Defaults to false.

mode:                 Selects encryption mode for attribute: choose <tt>:single_iv_and_salt</tt> for compatibility
                      with the old attr_encrypted API: the IV is derived from the encryption key by the underlying Encryptor class; salt is not used.
                      The <tt>:per_attribute_iv_and_salt</tt> mode uses a per-attribute IV and salt. The salt is used to derive a unique key per attribute.
                      A <tt>:per_attribute_iv</default> mode derives a unique IV per attribute; salt is not used.
                      Defaults to <tt>:per_attribute_iv</tt>.

allow_empty_value:    Attributes which have nil or empty string values will not be encrypted unless this option
                      has a truthy value.

You can specify your own default options

class User
  # Now all attributes will be encoded and marshaled by default
  attr_encrypted_options.merge!(encode: true, marshal: true, some_other_option: true)
  attr_encrypted :configuration, key: 'my secret key'
end

Example

class User
  attr_encrypted :email, key: 'some secret key'
  attr_encrypted :configuration, key: 'some other secret key', marshal: true
end

@user = User.new
@user.encrypted_email # nil
@user.email? # false
@user.email = 'test@example.com'
@user.email? # true
@user.encrypted_email # returns the encrypted version of 'test@example.com'

@user.configuration = { time_zone: 'UTC' }
@user.encrypted_configuration # returns the encrypted version of configuration

See README for more examples

# File lib/attr_encrypted.rb, line 136
def attr_encrypted(*attributes)
  options = attributes.last.is_a?(Hash) ? attributes.pop : {}
  options = attr_encrypted_default_options.dup.merge!(attr_encrypted_options).merge!(options)

  options[:encode] = options[:default_encoding] if options[:encode] == true
  options[:encode_iv] = options[:default_encoding] if options[:encode_iv] == true
  options[:encode_salt] = options[:default_encoding] if options[:encode_salt] == true

  attributes.each do |attribute|
    encrypted_attribute_name = (options[:attribute] ? options[:attribute] : [options[:prefix], attribute, options[:suffix]].join).to_sym

    instance_methods_as_symbols = attribute_instance_methods_as_symbols

    if attribute_instance_methods_as_symbols_available?
      attr_reader encrypted_attribute_name unless instance_methods_as_symbols.include?(encrypted_attribute_name)
      attr_writer encrypted_attribute_name unless instance_methods_as_symbols.include?(:"#{encrypted_attribute_name}=")

      iv_name = "#{encrypted_attribute_name}_iv".to_sym
      attr_reader iv_name unless instance_methods_as_symbols.include?(iv_name)
      attr_writer iv_name unless instance_methods_as_symbols.include?(:"#{iv_name}=")

      salt_name = "#{encrypted_attribute_name}_salt".to_sym
      attr_reader salt_name unless instance_methods_as_symbols.include?(salt_name)
      attr_writer salt_name unless instance_methods_as_symbols.include?(:"#{salt_name}=")
    end

    define_method(attribute) do
      instance_variable_get("@#{attribute}") || instance_variable_set("@#{attribute}", decrypt(attribute, send(encrypted_attribute_name)))
    end

    define_method("#{attribute}=") do |value|
      send("#{encrypted_attribute_name}=", encrypt(attribute, value))
      instance_variable_set("@#{attribute}", value)
    end

    define_method("#{attribute}?") do
      value = send(attribute)
      value.respond_to?(:empty?) ? !value.empty? : !!value
    end

    encrypted_attributes[attribute.to_sym] = options.merge(attribute: encrypted_attribute_name)
  end
end

Also aliased as: attr_encryptor

attr_encrypted?(attribute) click to toggle source

Checks if an attribute is configured with attr_encrypted

Example

class User
  attr_accessor :name
  attr_encrypted :email
end

User.attr_encrypted?(:name)  # false
User.attr_encrypted?(:email) # true

# File lib/attr_encrypted.rb, line 225
def attr_encrypted?(attribute)
  encrypted_attributes.has_key?(attribute.to_sym)
end

attr_encrypted_options() click to toggle source

Default options to use with calls to attr_encrypted

It will inherit existing options from its superclass

# File lib/attr_encrypted.rb, line 185
def attr_encrypted_options
  @attr_encrypted_options ||= superclass.attr_encrypted_options.dup
end

attr_encryptor(*attributes)

Alias for: attr_encrypted

decrypt(attribute, encrypted_value, options = {}) click to toggle source

Decrypts a value for the attribute specified

Example

class User
  attr_encrypted :email
end

email = User.decrypt(:email, 'SOME_ENCRYPTED_EMAIL_STRING')

# File lib/attr_encrypted.rb, line 238
def decrypt(attribute, encrypted_value, options = {})
  options = encrypted_attributes[attribute.to_sym].merge(options).compact
  if options[:if] && !options[:unless] && not_empty?(encrypted_value)
    encrypted_value = encrypted_value.unpack(options[:encode]).first if options[:encode]
    value = options[:encryptor].send(options[:decrypt_method], options.merge!(value: encrypted_value))
    if options[:marshal]
      value = options[:marshaler].send(options[:load_method], value)
    elsif defined?(Encoding)
      encoding = Encoding.default_internal || Encoding.default_external
      value = value.force_encoding(encoding.name)
    end
    value
  else
    encrypted_value
  end
end

encrypt(attribute, value, options = {}) click to toggle source

Encrypts a value for the attribute specified

Example

class User
  attr_encrypted :email
end

encrypted_email = User.encrypt(:email, 'test@example.com')

# File lib/attr_encrypted.rb, line 264
def encrypt(attribute, value, options = {})
  options = encrypted_attributes[attribute.to_sym].merge(options)
  if options[:if] && !options[:unless] && (options[:allow_empty_value] || not_empty?(value))
    value = options[:marshal] ? options[:marshaler].send(options[:dump_method], value) : value.to_s
    encrypted_value = options[:encryptor].send(options[:encrypt_method], options.merge!(value: value))
    encrypted_value = [encrypted_value].pack(options[:encode]) if options[:encode]
    encrypted_value
  else
    value
  end
end

encrypted_attributes() click to toggle source

Contains a hash of encrypted attributes with virtual attribute names as keys and their corresponding options as values

Example

class User
  attr_encrypted :email, key: 'my secret key'
end

User.encrypted_attributes # { email: { attribute: 'encrypted_email', key: 'my secret key' } }

# File lib/attr_encrypted.rb, line 290
def encrypted_attributes
  @encrypted_attributes ||= superclass.encrypted_attributes.dup
end

method_missing(method, *arguments, &block) click to toggle source

Forwards calls to :encrypt_#{attribute} or :decrypt_#{attribute} to the corresponding encrypt or decrypt method if attribute was configured with attr_encrypted

Example

class User
  attr_encrypted :email, key: 'my secret key'
end

User.encrypt_email('SOME_ENCRYPTED_EMAIL_STRING')

Calls superclass method

# File lib/attr_encrypted.rb, line 304
def method_missing(method, *arguments, &block)
  if method.to_s =~ /^((en|de)crypt)_(.+)$/ && attr_encrypted?($3)
    send($1, $3, *arguments)
  else
    super
  end
end

not_empty?(value) click to toggle source

# File lib/attr_encrypted.rb, line 276
def not_empty?(value)
  !value.nil? && !(value.is_a?(String) && value.empty?)
end

Protected Instance Methods

attribute_instance_methods_as_symbols() click to toggle source

# File lib/attr_encrypted.rb, line 496
def attribute_instance_methods_as_symbols
  instance_methods.collect { |method| method.to_sym }
end

attribute_instance_methods_as_symbols_available?() click to toggle source

# File lib/attr_encrypted.rb, line 500
def attribute_instance_methods_as_symbols_available?
  true
end

Private Instance Methods

attr_encrypted_default_options() click to toggle source

# File lib/attr_encrypted.rb, line 189
def attr_encrypted_default_options
  {
    prefix:            'encrypted_',
    suffix:            '',
    if:                true,
    unless:            false,
    encode:            false,
    encode_iv:         true,
    encode_salt:       true,
    default_encoding:  'm',
    marshal:           false,
    marshaler:         Marshal,
    dump_method:       'dump',
    load_method:       'load',
    encryptor:         Encryptor,
    encrypt_method:    'encrypt',
    decrypt_method:    'decrypt',
    mode:              :per_attribute_iv,
    algorithm:         'aes-256-gcm',
    allow_empty_value: false,
  }
end