serket 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5ba69de85b66353c39bb9ab36bbe137c03096ace
-  data.tar.gz: 9992acd318cbc1aa4d739fcc6224f1bd71189314
+  metadata.gz: 9add635d8b06b59c7bc47526c0b22b90b9bedd17
+  data.tar.gz: b357446a204828c351bee22546f4e4f1365d8fe6
 SHA512:
-  metadata.gz: c8e7853161ae2026ec1eb2051000263c0da21ec2e171d01fde51d60900ce64c22c5c32fc83c66725c74ad873a8df79bcf0d401b40b71aebe6985a8104355678c
-  data.tar.gz: d01c0d8e9154170783a00cf2bccac560fdde8b4703428de75a7b26a1cc6be370ddbaf6215b4c5d1c151cc244fea4ecaf3d6382eb7011a85479247e1f51030dcf
+  metadata.gz: 6c613a58ca1b059019288a0240a44901d97697ab5fa6f76755a6c31816dcffe0b2ebaaf4e3f58c7487e20336ed927229bd77e282e1423cf2be890e24e7db91b1
+  data.tar.gz: d203cd2cc7363a52aee031cf942d96d01e8eb37d66f8080111d881a619217e5e90f0db4d99acf67d228dc7dc5e1e541503c47dfc326eb2447d7fb57599cd3335

data/README.md

@@ -76,6 +76,7 @@ There are a few more configuration options.
 | format                   | :delimited    | :delimited, :json                     |
 | symmetric_algorithm      | AES-256-CBC   | Any valid cipher from OpenSSL::Cipher |
 | delimiter                | ::            | Anything not base64                   |
+| encoding                 | utf-8         | Any valid ruby encoding               |
 
 These can all be modified in the configuration block, eg:
 
@@ -126,6 +127,15 @@ Serket.configure do |config|
 end
 ```
 
+You can do a sanity-check with your api endpoint by sending a post request for a model with decrypted_fields:
+```
+curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{"decrypted_model": {"name": "bm5gkjwdfv6QBUqFPEnOaw==::CtQJyXdbuLeVzmIOIr0h/F9yh7xvz5KWUgxe/u4IkORGOW4KjU4bw+Wzve2vV1nLYUEWJJprr8sb+grm+Ao2sngNejiHzSkJKqZA/Pclw/Ok8KgHgN7olUz4BoCSdivIDRIT9ar06sNBrqOvLd4iGUlpMkpLdSJ69K08ebSvg5tED+PcK/oI6SJoVxRoUMYdYa9AfeIS9Ld5BgvhsaJgCKr089kfH2CzwpzlmRfdxb2qgyDXnk9PG/4WUEjjbamF/R74FNBdWkTLxZeLGdMImh87CQ6AOJ/v8l1JSzpPWwEjtmhTbFEzJPuA01tP5U5D07si0esJnab/B48iACEoLg==::iSmdDgnTzkEUv0yLbtFa8Q=="}}' http://localhost:3000/api/v1/decrypted_models
+```
+
+This should automatically decrypt the name for the decrypted_model before saving if you use the provided private key located in spec/resources/test_private_key.pem (and keep the default configs for delimited with ::)
+
+**Just be sure to use your own keys in production!**
+
 ### Android Java Client
 
 You can see an example java client for use with Android in EncryptUtil.java

data/lib/serket/configuration.rb

@@ -1,11 +1,23 @@
 module Serket
+  # Controls various configuration options such as key locations, desired
+  # algorithms and expected cipher text format.
+  #
+  # * +private_key_path+ - The filepath to a RSA private key
+  # * +public_key_path+ - The filepath to a RSA public key
+  # * +delimiter+ - If the format is set to :delimited, use this delimiter.
+  #                 Must not be a character in base64.
+  # * +format+ - May be :delimited or :json
+  # * +symmetric_algorithm+ - May be any algorithm that may be used with OpenSSL::Cipher
+  # * +encoding+ - Any valid ruby encoding
+  #
   class Configuration
-    attr_accessor :private_key_path, :public_key_path, :delimiter, :format, :symmetric_algorithm
+    attr_accessor :private_key_path, :public_key_path, :delimiter, :format, :symmetric_algorithm, :encoding
 
     def initialize
       @delimiter = "::"
       @format = :delimited
       @symmetric_algorithm = 'AES-256-CBC'
+      @encoding = 'utf-8'
     end
   end
 end

data/lib/serket/decrypted_fields.rb

@@ -1,4 +1,23 @@
 module Serket
+  # If a class extends DecryptedFields, then the getter method will be overridden
+  # for each attribute that is listed.
+  #
+  # For example:
+  #
+  # class Person
+  #   extend Serket::DecryptedFields
+  #
+  #   decrypted_fields :name, :email
+  # end
+  #
+  # This will create a method name=(value) and email=(value)
+  #
+  # It assumes the encrypted name and email will be assigned to an
+  # instance of person, and will automatically decrypt the encrypted
+  # value using the configured private key.
+  #
+  # This currently relies on the write_attribute, which is available in
+  # ActiveRecord::Base.  This currently is only intended for use with rails.
   module DecryptedFields
     def decrypted_fields(*fields)
       fields.each do |field|

data/lib/serket/encrypted_fields.rb

@@ -1,4 +1,24 @@
 module Serket
+  # If a class extends EncryptedFields, then the getter method will be overridden
+  # for each attribute that is listed.
+  #
+  # For example:
+  #
+  # class Person
+  #   extend Serket::EncryptedFields
+  #
+  #   encrypted_fields :name, :email
+  # end
+  #
+  # This will create a method name=(value) and email=(value)
+  #
+  # When a value is assigned to name or email for a given person instance,
+  # it will automatically generate an encrypted version using the
+  # currently configured public key, and will store the cipher text instead
+  # of the plaintext value that was assigned.
+  #
+  # This currently relies on the write_attribute, which is available in
+  # ActiveRecord::Base.  This currently is only intended for use with rails.
   module EncryptedFields
     def encrypted_fields(*fields)
       fields.each do |field|

data/lib/serket/field_decrypter.rb

@@ -2,8 +2,10 @@ require 'openssl'
 require 'base64'
 
 module Serket
+  # Used to decrypt a field given a private key, field delimiter, symmetric
+  # algorithm, encoding, and format (:json or :delimited)
   class FieldDecrypter
-    attr_accessor :field_delimiter, :private_key_filepath, :symmetric_algorithm
+    attr_accessor :field_delimiter, :private_key_filepath, :symmetric_algorithm, :encoding
 
     def initialize(options = {})
       options ||= {}
@@ -12,16 +14,23 @@ module Serket
       @field_delimiter        = options[:field_delimiter]     || Serket.configuration.delimiter 
       @symmetric_algorithm    = options[:symmetric_algorithm] || Serket.configuration.symmetric_algorithm
       @format                 = options[:format]              || Serket.configuration.format
+      @encoding               = options[:encoding]            || Serket.configuration.encoding
     end
 
+    # Decrypt the provided cipher text, and return the plaintext
+    # Return nil if whitespace
     def decrypt(field)
       return if field !~ /\S/
       iv, encrypted_aes_key, encrypted_text = parse(field)
       private_key = OpenSSL::PKey::RSA.new(File.read(private_key_filepath))
       decrypted_aes_key = private_key.private_decrypt(Base64.decode64(encrypted_aes_key))
-      decrypt_data(iv, decrypted_aes_key, encrypted_text)
+      decrypted_field = decrypt_data(iv, decrypted_aes_key, encrypted_text)
+      decrypted_field.force_encoding(encoding)
     end
 
+    # What delimiter to use if the format is :delimited.
+    #
+    # Allow anything that is not base64.
     def field_delimiter=(delimiter)
       if delimiter =~ /[A-Za-z0-9\/+]/
         raise "This is not a valid delimiter!  Must not be a character in Base64."
@@ -39,6 +48,14 @@ module Serket
         aes.update(Base64.decode64(encrypted_text)) + aes.final
       end
 
+      # Extracts the initialization vector, encrypted key, and
+      # cipher text according to the specified format.
+      #
+      # delimited:
+      # * Expected format: iv::encrypted-key::ciphertext
+      #
+      # json:
+      # * Expected keys: iv, key, message
       def parse(field)
         case @format
         when :delimited

data/lib/serket/field_encrypter.rb

@@ -2,26 +2,32 @@ require 'openssl'
 require 'base64'
 
 module Serket
+  # Used to encrypt a field given a public key, field delimiter, symmetric
+  # algorithm, encoding and format (:json or :delimited)
   class FieldEncrypter
-    attr_accessor :field_delimiter, :public_key_filepath, :symmetric_algorithm
+    attr_accessor :field_delimiter, :public_key_filepath, :symmetric_algorithm, :encoding
 
     def initialize(options = {})
       options ||= {}
 
-      @public_key_filepath   = Serket.configuration.public_key_path
+      @public_key_filepath    = Serket.configuration.public_key_path
       @field_delimiter        = options[:field_delimiter]     || Serket.configuration.delimiter 
       @symmetric_algorithm    = options[:symmetric_algorithm] || Serket.configuration.symmetric_algorithm
       @format                 = options[:format]              || Serket.configuration.format
+      @encoding               = options[:encoding]            || Serket.configuration.encoding
     end
 
+    # Return encrypted string according to specified format.
+    # Return nil if field is whitespace.
     def encrypt(field)
       return if field !~ /\S/
       aes = OpenSSL::Cipher.new(symmetric_algorithm)
       aes_key = aes.random_key
       iv = aes.random_iv
-      encrypt_data(iv, aes_key, field)
+      encrypt_data(iv, aes_key, field.force_encoding(encoding))
     end
 
+    # Allow any field delimiter except a base64 character.
     def field_delimiter=(delimiter)
       if delimiter =~ /[A-Za-z0-9\/+]/
         raise "This is not a valid delimiter!  Must not be a character in Base64."
@@ -44,6 +50,8 @@ module Serket
         parse(Base64.encode64(iv), Base64.encode64(encrypted_aes_key), Base64.encode64(encrypted_text))
       end
 
+      # Format the final encrypted string to be returned depending
+      # on specified format.
       def parse(iv, encrypted_key, encrypted_text)
         case @format
         when :delimited

data/lib/serket/version.rb

@@ -1,3 +1,3 @@
 module Serket
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

data/spec/serket/field_encrypter_spec.rb

@@ -34,4 +34,24 @@ describe Serket::FieldEncrypter do
       @parsed_json.has_key?('message').should be_true
     end
   end
+
+  describe "encoding" do
+    it "should encrypt and decrypt an accent character" do
+      characters = %w(á é í ó ú ü ñ ¿ ¡)
+      characters.each do |c|
+        encrypted = @field_encrypter.encrypt(c)
+        decrypted = @field_decrypter.decrypt(encrypted)
+        c.should == decrypted
+      end
+    end
+
+    it "should encrypt and decrypt khmer" do
+      characters = %w(ឃ  ង ទ ម វ ស )
+      characters.each do |c|
+        encrypted = @field_encrypter.encrypt(c)
+        decrypted = @field_decrypter.decrypt(encrypted)
+        c.should == decrypted
+      end
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: serket
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Michael Nipper