rails_compatible_cookies_utils 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: bc47b3f417503da1fc90fb24f1551e5cc8976a82
+  data.tar.gz: e026fdd8cd7dc13534b7ad672547a325d9ff6ee1
+SHA512:
+  metadata.gz: 39986363fb9e3c772bebb8009fab0baad886423be46a57f67e2eda138c2dae59d3b86ac92c90401c0ffb17ae4c8b8ef2f4c53890c1209721c621f8dc841a8135
+  data.tar.gz: 488e3381c9765bde6d4aa9380a12629b85d0e0c3f750cd46438e15c7eb91a8fad5540179135d9785ee85c9f1513569f4ad75d00a6316dd31e339d80cc8dec25d

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.3.1
+before_install: gem install bundler -v 1.11.2

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in rails_compatible_cookies_utils.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Rodrigo Rosenfeld Rosas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,138 @@
+# RailsCompatibleCookiesUtils - Utility methods to deal with cookies managed by a Rails app
+
+This is a Ruby-only (2.0 or later) implementation of utility methods to manage cookies
+generated by a Rails app. It doesn't depend on any external gems.
+
+Just tell RailsCompatibleCookiesUtils the Rails app secret key and it will be able to handle
+signed and encrypted cookies (it can both read and write those values).
+
+This is useful if you intend to share your cookies (or session) among different Ruby web
+applications (they could be even running in the same domain behind a proxy for example) when
+at least one of the applications is not a Rails one.
+
+Or you could use this if you are switching from Rails to another Ruby web framework and want
+to deal with old valid sessions after deploying (either if it's a temporary strategy or you
+want to keep this encrypting and signing algorithms permanently).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rails_compatible_cookies_utils'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install rails_compatible_cookies_utils
+
+## Usage
+
+You may test the following examples in a REPL with `bin/console`.
+
+### Initialization
+
+Creating an instance using the default serializer in Rails 5 generated applications (JSON):
+
+```ruby
+cookies_utils = RailsCompatibleCookiesUtils.new 'secret_key_base'
+```
+
+Usually you'll pass the Rails app `secret_key_base` (`Rails.application.config.secret_key_base`)
+you want to share cookies with. You can also generate a Rails-like random secret key for other
+purposes if you want:
+
+```ruby
+secret_key_base = SecureRandom.hex 64
+```
+
+In previous Rails releases the default serializer was Marshal. If your app uses it, initialize
+it this way:
+
+```ruby
+cookies_utils = RailsCompatibleCookiesUtils.new 'secret_key_base', serializer: Marshal
+```
+
+### Thread-safety
+
+An instance of RailsCompatibleCookiesUtils is not thread-safe, so ensure to create a new
+instance for each thread using such an instance or make the calls in within a mutex synchronized
+block.
+
+### Read an encrypted cookie value
+
+This would be the equivalent of `cookies.encrypted['_myapp_session']`:
+
+```ruby
+raw_cookie_string = env['HTTP_COOKIE'] # this would be considering a Rack app
+cookies_utils.decrypt_cookie_key raw_cookie_string, '_myapp_session'
+```
+
+Or if you already have the parsed and unescaped cookie value:
+
+```ruby
+value = cookies_utils.cookies(env['HTTP_COOKIE'])['_myapp_session']
+# you may actually get the value from somewhere else
+cookies_utils.decrypt value
+```
+
+### Write an encrypted value to the cookies
+
+```ruby
+require 'cgi'
+value = { test: true }
+cookie = CGI::Cookie.new 'some_key', cookies_utils.encrypt value
+# or using a framework helper:
+# cookies['some_key'] = cookies_utils.encrypt value
+
+cookies_utils.decrypt(cookies_utils.encrypt 'secret') == 'secret'
+```
+
+### Signed only values
+
+Rails also allows you to just sign a cookie value without encrypting it
+(`cookies.signed['key'] = 'value'`). To verify and decode the value:
+
+```ruby
+cookies_utils.signed_cookie_key env['HTTP_COOKIE'], 'some_key'
+# or cookies_utils.verify_and_deserialize signed_serialized_value
+```
+
+Serialize and sign a cookie value with:
+
+```ruby
+require 'cgi'
+value = { test: true }
+cookie = CGI::Cookie.new 'some_key', cookies_utils.serialize_and_sign value
+# or using a framework helper:
+# cookies['some_key'] = cookies_utils.serialize_and_sign value
+
+cookies_utils.verify_and_deserialize(cookies_utils.serialize_and_sign 'secret') == 'secret'
+```
+
+### Invalid values handling
+
+If the value is invalid `decrypt_cookie_key`, `decrypt`, `signed_cookie_key`,
+`verify_and_deserialize` and `serialize_and_sign` will all return nil. All of
+them have a bang variant which will raise RailsCompatibleCookiesUtils::InvalidSignature
+instead in those cases (like `decrypt!`).
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome [on GitHub](https://github.com/rosenfeld/rails_compatible_cookies_utils).
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'rails_compatible_cookies_utils'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/rails_compatible_cookies_utils.rb

@@ -0,0 +1,157 @@
+require 'rails_compatible_cookies_utils/version'
+require 'json'
+require 'cgi'
+require 'openssl'
+require 'base64'
+
+class RailsCompatibleCookiesUtils
+
+  ##
+  # Initializes it by providing the required secret_key_base as defined by your Rails app.
+  # The default Rails serializer in recent versions is +JSON+, but +Marshal+ used to be the
+  # default. If your Rails application is old and still uses +Marshal+, set the +serializer+
+  # argument to +Marshal+: RailsCompatibleCookiesUtils.new(secret_key_base, serializer: Marshal).
+
+  def initialize(secret_key_base, serializer: JSON, encrypted_salt: 'encrypted cookie',
+       encrypted_signed_salt: 'signed encrypted cookie', signed_salt: 'signed cookie',
+       iterations: 1000, key_size: 64, cipher: 'aes-256-cbc', digest: 'SHA1')
+    @secret_key_base, @serializer, @encrypted_salt, @encrypted_signed_salt,
+        @signed_salt, @iterations, @key_size, @cipher, @digest =
+      secret_key_base, serializer, encrypted_salt, encrypted_signed_salt,
+        signed_salt, iterations, key_size, cipher, digest
+  end
+
+  # Decrypts an specific key from a raw cookie string. Returns nil if invalid.
+  def decrypt_cookie_key(cookie, key)
+    decrypt cookie_value(cookie, key)
+  end
+
+  # Decrypts an specific key from a raw cookie string.
+  # Raises RailsCompatibleCookiesUtils::InvalidSignature if invalid.
+  def decrypt_cookie_key!(cookie, key)
+    decrypt! cookie_value(cookie, key)
+  end
+
+  InvalidSignature = Class.new StandardError
+  # Decrypt an unescaped value and raise RailsCompatibleCookiesUtils::InvalidSignature if invalid.
+  def decrypt!(value)
+    decrypt value or raise InvalidSignature
+  end
+
+  # Decrypts an unescaped value and return nil if invalid.
+  def decrypt(value)
+    return nil unless encoded_encrypted = verify_and_decode(value, encrypted_signed_secret)
+    cipher = new_cipher
+    encrypted, iv = encoded_encrypted.split('--').map{|v| decode v }
+    cipher.decrypt
+    cipher.key = encrypted_secret
+    cipher.iv = iv
+    decrypted = cipher.update encrypted
+    decrypted << cipher.final
+    @serializer.load decrypted
+  end
+
+  # Decodes value, returning nil if it's invalid.
+  def verify_and_decode(value, secret)
+    return nil if value.nil? || !value.valid_encoding? || value.strip.empty?
+    data, digest = value.split '--'
+    return nil if [data, digest].any?{|v| v.nil? || v.strip.empty?}
+    return nil unless generate_digest(data, secret) == digest
+    decode data
+  end
+
+  def encrypted_secret
+    @encrypted_secret ||= generate_key @encrypted_salt
+  end
+
+  def generate_key(salt)
+    OpenSSL::PKCS5.pbkdf2_hmac_sha1 @secret_key_base, salt, @iterations, @key_size
+  end
+
+  def encrypted_signed_secret
+    @encrypted_signed_secret ||= generate_key @encrypted_signed_salt
+  end
+
+  def signed_secret
+    @signed_secret ||= generate_key @signed_salt
+  end
+
+  # Gets first value for +key+ from the raw +cookie+ (env['HTTP_COOKIE']).
+  def cookie_value(cookie, key)
+    cookies(cookie)[key]
+  end
+
+  # Returns a hash with the first value for each key from the raw cookie string.
+  def cookies(cookie)
+    Hash[CGI::Cookie::parse(cookie).map{|k, v| [k, v.first]}]
+  end
+
+  # Returns signed encrypted +value+.
+  def encrypt(value)
+    sign_and_encode _encrypt(value), encrypted_signed_secret
+  end
+
+  # Signs and encode value only, without encrypting (session.signed[key] = value).
+  def sign_and_encode(value, secret)
+    data = encode value
+    "#{data}--#{generate_digest data, secret}"
+  end
+
+  # Fetches a signed-only value from the raw cookie (env['HTTP_COOKIE']): session.signed['key'].
+  # Raises RailsCompatibleCookiesUtils::InvalidSignature if invalid.
+  def signed_cookie_key!(cookie, key)
+    signed_cookie_key cookie, key or raise InvalidSignature
+  end
+
+  # Fetches a signed-only value from the raw cookie (env['HTTP_COOKIE']): session.signed['key'].
+  # Returns nil if invalid.
+  def signed_cookie_key(cookie, key)
+    verify_and_deserialize cookie_value(cookie, key)
+  end
+
+  # Decodes and deserializes a signed value.
+  # Raises RailsCompatibleCookiesUtils::InvalidSignature if invalid.
+  def verify_and_deserialize!(value)
+    verify_and_deserialize value or raise InvalidSignature
+  end
+
+  # Decodes and deserializes a signed value, returning nil if invalid.
+  def verify_and_deserialize(value)
+    return nil unless decoded = verify_and_decode(value, signed_secret)
+    @serializer.load decoded
+  end
+
+  # Serializes and sign +value+ (session.signed['key'] = value)
+  def serialize_and_sign(value)
+    sign_and_encode @serializer.dump(value), signed_secret
+  end
+
+  private
+
+  def generate_digest(data, secret)
+    OpenSSL::HMAC.hexdigest(OpenSSL::Digest.const_get(@digest).new, secret, data)
+  end
+
+  def encode(data)
+    ::Base64.strict_encode64 data
+  end
+
+  def decode(data)
+    ::Base64.strict_decode64 data
+  end
+
+  def new_cipher
+    OpenSSL::Cipher.new @cipher
+  end
+
+  def _encrypt(value)
+    cipher = new_cipher
+    cipher.encrypt
+    cipher.key = encrypted_secret
+    iv = cipher.random_iv
+
+    encrypted = cipher.update @serializer.dump value
+    encrypted << cipher.final
+    "#{encode encrypted}--#{encode iv}"
+  end
+end

data/lib/rails_compatible_cookies_utils/version.rb

@@ -0,0 +1,3 @@
+class RailsCompatibleCookiesUtils
+  VERSION = '0.1.0'
+end

data/rails_compatible_cookies_utils.gemspec

@@ -0,0 +1,22 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'rails_compatible_cookies_utils/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'rails_compatible_cookies_utils'
+  spec.version       = RailsCompatibleCookiesUtils::VERSION
+  spec.authors       = ['Rodrigo Rosenfeld Rosas']
+  spec.email         = ['rr.rosas@gmail.com']
+
+  spec.summary       = %q{Provides utility methods to read and write cookies shared with a Rails app}
+  spec.homepage      = 'https://github.com/rosenfeld/rails_compatible_cookies_utils'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^spec/}) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.11'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+end

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: rails_compatible_cookies_utils
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Rodrigo Rosenfeld Rosas
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-07-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: 
+email:
+- rr.rosas@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/rails_compatible_cookies_utils.rb
+- lib/rails_compatible_cookies_utils/version.rb
+- rails_compatible_cookies_utils.gemspec
+homepage: https://github.com/rosenfeld/rails_compatible_cookies_utils
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Provides utility methods to read and write cookies shared with a Rails app
+test_files: []