README.md in symmetric-encryption-3.4.0 vs README.md in symmetric-encryption-3.6.0

- old
+ new

@@ -1,6 +1,6 @@ -symmetric-encryption +symmetric-encryption [![Build Status](https://secure.travis-ci.org/reidmorrison/symmetric-encryption.png?branch=master)](http://travis-ci.org/reidmorrison/symmetric-encryption) ==================== * http://github.com/reidmorrison/symmetric-encryption ## Introduction @@ -13,34 +13,10 @@ and consistent way Symmetric Encryption uses OpenSSL to encrypt and decrypt data, and can therefore expose all the encryption algorithms supported by OpenSSL. -## Upgrading from earlier versions to SymmetricEncryption V3 - -In version 3 of SymmetricEncryption, the following changes have been made that -may have backward compatibility issues: - -* SymmetricEncryption.decrypt no longer rotates through all the decryption keys - when previous ciphers fail to decrypt the encrypted string. - In a very small, yet significant number of cases it was possible to decrypt data - using the incorrect key. Clearly the data returned was garbage, but it still - returned a string of data instead of throwing an exception. - See SymmetricEncryption.select_cipher to supply your own custom logic to - determine the correct cipher to use when the encrypted string does not have a - header and multiple ciphers are defined. - -* Configuration file format prior to V1 is no longer supported - -* New configuration option has been added to support setting encryption keys - from environment variables - -* Cipher.parse_magic_header! now returns a Struct instead of an Array - -* New config options :encrypted_key and :encrypted_iv to support setting - the encryption key in environment variables - ## Security Many solutions that encrypt data require the encryption keys to be stored in the applications source code or leave it up to the developer to secure the keys on the application servers. symmetric-encryption takes care of securing the @@ -98,20 +74,21 @@ The random IV and key are stored in the header of the output stream so that it is available when reading back the encrypted file/stream. The key is placed in a header on the file in encrypted form using the current global key/cipher. The ActiveRecord attr_encrypted method supports the :random_iv => true option. -Similarly for Mongoid the :random_iv => true option can be added. +Similarly for MongoMapper and Mongoid the :random_iv => true option can be added. Note that encrypting the same input string with the same key and :random_iv => true option will result in different encrypted output every time it is encrypted. ## Features * Encryption of passwords in configuration files * Encryption of ActiveRecord model attributes by prefixing attributes / column names with encrypted_ +* Encryption of MongoMapper keys by using :encrypted_key * Encryption of Mongoid model fields by adding :encrypted option to field definitions * Externalization of symmetric encryption keys so that they are not in the source code, or the source code control system * Validator for ActiveRecord Models to ensure fields contain encrypted data @@ -132,12 +109,12 @@ ## Recommendations * Add the encryption header to all encrypted strings. See the _always_add_header_ option in the configuration file. -* Set :random_iv => true for all ActiveRecord attributes and Mongoid fields - which are not used in indexes and will not be used as part of a query. +* Add `random_iv: true` for all ActiveRecord attributes, MongoMapper keys, and + Mongoid fields which are not used in indexes and will not be used as part of a query. ## Binary Data On decryption an attempt is made to encode the data as UTF-8, if it fails it will be returned as BINARY encoded. @@ -172,35 +149,35 @@ # By specifying the type as :integer the value will be returned as an integer and # can be set as an integer, even though it is stored in the database as an # encrypted string # # Requires users table to have a column called encrypted_age of type string - attr_encrypted :age, :type => :integer + attr_encrypted :age, type: integer # Since string and long_string are not used in the where clause of any SQL # queries it is better to ensure that the encrypted value is always different # by encrypting every value with a random Initialization Vector. # # Note: Encrypting the same value twice will result in different encrypted - # values when :random_iv => true - attr_encrypted :string, :random_iv => true + # values when :random_iv is true + attr_encrypted :string, random_iv: true # Long encrypted strings can also be compressed prior to encryption to save # disk space - attr_encrypted :long_string, :random_iv => true, :compress => true + attr_encrypted :long_string, random_iv: true, compress: true # By specifying the type as :json the value will be serialized to JSON # before encryption and deserialized from JSON after decryption. # # It is sometimes useful to use compression on large fields, so we can enable # compression before the string is encrypted # # Requires users table to have a column called encrypted_values of type string - attr_encrypted :values, :type => :json, :compress => true + attr_encrypted :values, type: :json, compress: true - validates :encrypted_bank_account_number, :symmetric_encryption => true - validates :encrypted_social_security_number, :symmetric_encryption => true + validates :encrypted_bank_account_number, symmetric_encryption: true + validates :encrypted_social_security_number, symmetric_encryption: true end # Create a new user instance assigning a bank account number user = User.new user.bank_account_number = '12345' @@ -208,11 +185,11 @@ # Saves the bank_account_number in the column encrypted_bank_account_number in # encrypted form user.save! # Short example using create -User.create(:bank_account_number => '12345') +User.create(bank_account_number: '12345') ``` Several types are supported for ActiveRecord models when encrypting or decrypting data. Each type maps to the built-in Ruby types as follows: @@ -224,50 +201,96 @@ - :time => Time - :date => Date - :json => Uses JSON serialization, useful for hashes and arrays - :yaml => Uses YAML serialization, useful for hashes and arrays +### MongoMapper Example + +To encrypt a field in a MongoMapper document, use `encrypted_key` instead of `key` +when specifying a key. + +```ruby + field :encrypted_age, type: String, encrypted: {type: :integer} +end + +# User model MongoMapper +class User + include MongoMapper::Document + + key :name, String + encrypted_key :bank_account_number, String + encrypted_key :social_security_number, String + encrypted_key :life_history, String, encrypted: { random_iv: true, compress: true } + + # Encrypted fields are _always_ stored in Mongo as a String + # To get the result back as an Integer, Symmetric Encryption will automatically + # perform the necessary conversions + encrypted_key :integer_value, Integer + encrypted_key :float_value, Float + encrypted_key :decimal_value, BigDecimal + encrypted_key :datetime_value, DateTime + encrypted_key :time_value, Time + encrypted_key :date_value, Date + encrypted_key :true_value, Boolean + encrypted_key :data_json, Hash, encrypted: {random_iv: true, compress: true} + # By default Hash is saved as JSON, to save as YAML add the type specifier: + encrypted_key :data_yaml, Hash, encrypted: {random_iv: true, compress: true, type: :yaml} + + # Optionally add validation to ensure that encrypted fields are in fact encrypted + # before the data is saved + validates :encrypted_bank_account_number, symmetric_encryption: true + validates :encrypted_social_security_number, symmetric_encryption: true +end + +# Create a new user document +User.create(bank_account_number: '12345') + +# When finding a document, always use the encrypted form of the field name +user = User.where(encrypted_bank_account_number: SymmetricEncryption.encrypt('12345')).first + +# Fields can be accessed using their unencrypted names +puts user.bank_account_number +``` + ### Mongoid Example -To encrypt a field in a Mongoid document, just add ":encrypted => true" at the end +To encrypt a field in a Mongoid document, just add "encrypted: true" at the end of the field specifier. The field name must currently begin with "encrypted_" ```ruby # User model in Mongoid class User include Mongoid::Document - field :name, :type => String - field :encrypted_bank_account_number, :type => String, :encrypted => true - field :encrypted_social_security_number, :type => String, :encrypted => true - field :encrypted_life_history, :type => String, :encrypted => {:compress => true, :random_iv => true} + field :name, type: String + field :encrypted_bank_account_number, type: String, encrypted: true + field :encrypted_social_security_number, type: String, encrypted: true + field :encrypted_life_history, type: String, encrypted: {compress: true, random_iv: true} # Encrypted fields are _always_ stored in Mongo as a String # To get the result back as an Integer, Symmetric Encryption can do the # necessary conversions by specifying the internal type as an option # to :encrypted # #see SymmetricEncryption::COERCION_TYPES for full list of types - field :encrypted_age, :type => String, :encrypted => {:type => :integer} + field :encrypted_age, type: String, encrypted: {type: :integer} end # Create a new user document -User.create(:bank_account_number => '12345') +User.create(bank_account_number: '12345') # When finding a document, always use the encrypted form of the field name -user = User.where(:encrypted_bank_account_number => SymmetricEncryption.encrypt('12345')).first +user = User.where(encrypted_bank_account_number: SymmetricEncryption.encrypt('12345')).first # Fields can be accessed using their unencrypted names puts user.bank_account_number ``` -Note: At this time Symmetric Encryption only supports Mongoid fields with a type of String - ### Validation Example ```ruby class MyModel < ActiveRecord::Base - validates :encrypted_ssn, :symmetric_encryption => true + validates :encrypted_ssn, symmetric_encryption: true end m = MyModel.new m.valid? # => false @@ -328,11 +351,11 @@ ``` Example: Compress, Encrypt and write data to a file ```ruby -SymmetricEncryption::Writer.open('encrypted_compressed.zip', :compress => true) do |file| +SymmetricEncryption::Writer.open('encrypted_compressed.zip', compress: true) do |file| file.write "Hello World\n" file.write "Compress this\n" file.write "Keep this safe and secure\n" end ``` @@ -342,13 +365,13 @@ Before generating keys we can use SymmetricEncryption in a standalone test environment: ```ruby # Use test encryption keys SymmetricEncryption.cipher = SymmetricEncryption::Cipher.new( - :key => '1234567890ABCDEF1234567890ABCDEF', - :iv => '1234567890ABCDEF', - :cipher_name => 'aes-128-cbc' + key: '1234567890ABCDEF1234567890ABCDEF', + iv: '1234567890ABCDEF', + cipher_name: 'aes-128-cbc' ) encrypted = SymmetricEncryption.encrypt('hello world') puts SymmetricEncryption.decrypt(encrypted) ``` @@ -683,29 +706,53 @@ compression Note: Adds a 6 byte header prior to encoding, only if :random_iv is false Default: false ``` +## Upgrading from earlier versions to SymmetricEncryption V3 + +In version 3 of SymmetricEncryption, the following changes have been made that +may have backward compatibility issues: + +* SymmetricEncryption.decrypt no longer rotates through all the decryption keys + when previous ciphers fail to decrypt the encrypted string. + In a very small, yet significant number of cases it was possible to decrypt data + using the incorrect key. Clearly the data returned was garbage, but it still + returned a string of data instead of throwing an exception. + See SymmetricEncryption.select_cipher to supply your own custom logic to + determine the correct cipher to use when the encrypted string does not have a + header and multiple ciphers are defined. + +* Configuration file format prior to V1 is no longer supported + +* New configuration option has been added to support setting encryption keys + from environment variables + +* Cipher.parse_magic_header! now returns a Struct instead of an Array + +* New config options :encrypted_key and :encrypted_iv to support setting + the encryption key in environment variables + Meta ---- * Code: `git clone git://github.com/reidmorrison/symmetric-encryption.git` * Home: <https://github.com/reidmorrison/symmetric-encryption> * Issues: <http://github.com/reidmorrison/symmetric-encryption/issues> * Gems: <http://rubygems.org/gems/symmetric-encryption> This project uses [Semantic Versioning](http://semver.org/). -Authors -------- +Author +------ [Reid Morrison](https://github.com/reidmorrison) Contributors ------------ -[M. Scott Ford](https://github.com/mscottford) -[Adam St. John](https://github.com/astjohn) +* [M. Scott Ford](https://github.com/mscottford) +* [Adam St. John](https://github.com/astjohn) License ------- Copyright 2012, 2013, 2014 Reid Morrison