README.md in symmetric-encryption-3.2 vs README.md in symmetric-encryption-3.3

- old
+ new

@@ -1,9 +1,9 @@ symmetric-encryption ==================== -* http://github.com/ClarityServices/symmetric-encryption +* http://github.com/reidmorrison/symmetric-encryption ## Introduction Any project that wants to meet PCI compliance has to ensure that the data is encrypted whilst in flight and at rest. Amongst many other other requirements all passwords @@ -161,22 +161,44 @@ ```ruby class User < ActiveRecord::Base # Requires table users to have a column called encrypted_bank_account_number attr_encrypted :bank_account_number - # Requires table users to have a column called encrypted_social_security_number + # Requires users table to have a column called encrypted_social_security_number + # + # Note: Encrypting the same value twice will result in the _same_ encrypted value + # when :random_iv => false, or is not specified attr_encrypted :social_security_number + # 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 + # 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 # Long encrypted strings can also be compressed prior to encryption to save # disk space 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 + 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 @@ -189,10 +211,23 @@ # Short example using create 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: + +- :string => String +- :integer => Integer +- :float => Float +- :decimal => BigDecimal +- :datetime => DateTime +- :time => Time +- :date => Date +- :json => Uses JSON serialization, useful for hashes and arrays +- :yaml => Uses YAML serialization, useful for hashes and arrays + ### Mongoid Example 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_" @@ -203,10 +238,17 @@ 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} end # Create a new user document User.create(:bank_account_number => '12345') @@ -215,10 +257,12 @@ # 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 @@ -325,10 +369,17 @@ rake symmetric_encryption:encrypt Note: Passwords must be encrypted in the environment in which they will be used. Since each environment should have its own symmetric encryption keys +Note: To use the rake task 'symmetric_encryption:encrypt' the gem 'highline' + must first be installed by adding to bundler or installing directly: + +```ruby +gem install 'highline' +``` + Encrypt a file INFILE="Gemfile.lock" OUTFILE="Gemfile.lock.encrypted" rake symmetric_encryption:encrypt_file Encrypt and compress a file @@ -612,26 +663,31 @@ ``` Meta ---- -* Code: `git clone git://github.com/ClarityServices/symmetric-encryption.git` -* Home: <https://github.com/ClarityServices/symmetric-encryption> -* Issues: <http://github.com/ClarityServices/symmetric-encryption/issues> +* 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 ------- -Reid Morrison :: reidmo@gmail.com :: @reidmorrison +[Reid Morrison](https://github.com/reidmorrison) +Contributors +------------ + +[M. Scott Ford](https://github.com/mscottford) + License ------- -Copyright 2012 Clarity Services, Inc. +Copyright 2012, 2013, 2014 Reid Morrison Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at @@ -641,11 +697,11 @@ distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -Compliance +Disclaimer ---------- -Although this library has assisted Clarity in meeting PCI Compliance it in no -way guarantees that PCI Compliance will be met by anyone using this library -for encryption purposes. +Although this library has assisted in meeting PCI Compliance and has passed +previous PCI audits, it in no way guarantees that PCI Compliance will be +achieved by anyone using this library.