has_global_session 0.8.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Tony Spataro <code@tracker.xeger.net>
+
+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

@@ -0,0 +1,151 @@
+= Introduction
+
+HasGlobalSession enables multiple heterogeneous Web applications to share
+session state in a cryptographically secure way, facilitating single sign-on
+and enabling easier development of large-scale distributed applications that
+make use of architectural strategies such as sharding or separation of concerns.
+
+This plugin does not provide a complete solution for authentication. In
+particular, it does *not* provide any of the following:
+
+* <b>federation</b> -- aka cross-domain single sign-on -- use OpenID for that.
+
+* <b>authentication</b> -- the application's controllers must authenticate the user.
+
+* <b>secrecy</b> -- global session attributes can be signed but never encrypted;
+  protect against third-party snooping using SSL, and if you don't want your
+  users to see their session state, put it in a database.
+
+* <b>replication</b> -- the authentication authorities must have some way to
+  share information about the database of users, their passwords, etc.
+
+* <b>single sign-out</b> -- the authorities must have some way to broadcast a
+  notification when sessions are invalidated; they can override the default
+  Directory implementation to do realtime revocation checking.
+
+== Global Session Contents
+
+Global session state is stored as a cookie in the user's browser. The cookie
+is a Zlib-compressed JSON dictionary containing the following stuff:
+* session metadata (UUID, created-at, expires-at, certifying-authority)
+* signed session attributes (e.g. the authenticated user ID)
+* insecure session attributes (e.g. the last-visited URL)
+* a cryptographic signature of the metadata and signed attributes
+
+The global session is unserialized and its signature is verified whenever
+a controller asks for the global session. The cookie's value is updated
+whenever its attributes change. As an optimization, the signature is only
+recomputed when the metadata or signed attributes have changed; insecure
+attributes can change "for free."
+
+Because the security properties of attributes can vary, HasGlobalSession
+requires all _possible_ attributes to be declared up-front in the config
+file. The 'attributes' section of the config file defines the _schema_
+for the global session: which attributes can be used, and which must be
+cryptographically signed in order to be used.
+
+Since the session is serialized as JSON, only a limited range of object
+types can be stored in it: strings, numbers, lists, hashes and other Ruby
+primitives. Ruby booleans (true/false) do not translate well into JSON
+and should be avoided.
+
+= Example
+
+1) Create a basic config file and edit it to suit your needs:
+      $ script/generate global_session_config mycoolapp.com
+
+2) Create an authentication authority:
+      $ script/generate global_session_authority mycoolapp
+
+3) Declare that some or all of your application's controllers will have access
+   to the global session:
+      class ApplicationController < ActionController::Base
+        has_global_session
+      end
+
+4) Make use of the global session hash in your controllers:
+      global_session['user'] = @user.id
+      ...
+      @current_user = User.find(global_session['user'])
+
+= Detailed Information
+
+== Global Session Domain
+
+We refer to collection of _all_ Web application instances capable of using the
+global session as the "domain." The global session domain may consist of any
+number of distinct servers, possibly hidden behind load balancers or proxies.
+The servers within the domain may all be running the same Rails application,
+or they may be running different codebases that represent different parts of
+a distributed application. (They may also be using app frameworks other than
+Rails.)
+
+The only constraint imposed by HasGlobalSession is that all servers within the
+domain must have end-user-facing URLs within the same second-level DNS domain.
+This is due to limitations imposed by the HTTP cookie mechanism: for privacy
+reasons, cookies will only be sent to servers within the same domain as the
+server that first created them.
+
+For example, in my HasGlobalSession configuration file I might specify that my
+cookie's domain is "example.com". My app servers at app1.example.com and
+app2.example.com would be part of the global session domain, but my business
+partner's application at www.partner.com could not participate.
+
+== Authorities and Relying Parties
+
+A Web application that can create or update the global session is said to
+be an "authority" (because it's trusted by other parties to make assertions
+about global session state). An application that can read the global session
+is said to be a "relying party." In practice, every application is a relying
+party but not all of them need to be authorities.
+
+There is an RSA key pair associated with each authority. The authority's
+public key is distribued to all relying parties, but the private key must
+remain a secret to that authority (which may consist of many individual
+servers).
+
+This system allows for significant flexibility when configuring a distributed
+app's global session. There must be at least one authority, but for many apps
+one authority (plus an arbitrary number of relying parties, which do not need
+a key pair) will be sufficient.
+
+In general, two systems should be part of the same authority if there is no
+trust boundary between them -- that is to say, trust between the two systems
+is unlimited in both directions.
+
+Here are some reasons you might consider dividing your systems into different
+authorities:
+* beta/staging system vs. production system
+* system hosted by a third party vs. system hosted internally
+* e-commerce server vs. storefront server
+
+== The Directory
+
+The Directory is a Ruby object instantiated by HasGlobalSession in order to
+perform lookups of public and private keys. Given an authority name (as found
+in a session cookie), the Directory can find the corresponding public key.
+
+If the local system is an authority itself, the method #my_authority_name will
+return non-nil and #my_private_key will return a private key suitable for
+signing session attributes.
+
+The Directory implementation included with HasGlobalSession uses the filesystem
+as the backing store for its key pairs. Its #initialize method accepts a
+filesystem path that will be searched for *.pub and *.key files containing PEM-
+encoded public and private keys (the same format used by OpenSSH).
+
+When used with a Rails app, HasGlobalSession expects to find its keystore in
+config/authorities. You can use the global_session generator to create new key
+pairs. Remember never to check a *.key file into a public repository!! (In
+contrast, *.pub files can be distributed freely.) 
+
+If you wish all of the systems to stop trusting an authority, simply delete
+its public key from config/authorities.
+
+= To-Do
+
+* Configurable session expiry
+* Option to auto-renew session
+* Option for non-sticky global session (cookie expires at close of browser session, not at global session expiration!)
+
+Copyright (c) 2010 Tony Spataro <code@tracker.xeger.net>, released under the MIT license

data/has_global_session.gemspec

@@ -0,0 +1,32 @@
+# -*- encoding: utf-8 -*-
+
+require 'rubygems'
+
+spec = Gem::Specification.new do |s|
+  s.required_rubygems_version = nil if s.respond_to? :required_rubygems_version=
+  s.required_ruby_version = Gem::Requirement.new(">= 1.8.7")
+
+  s.name    = 'has_global_session'
+  s.version = '0.8.0'
+  s.date    = '2010-06-01'
+
+  s.authors = ['Tony Spataro']
+  s.email   = 'code@tracker.xeger.net'
+  s.homepage= 'http://github.com/xeger/has_global_session'
+  
+  s.summary = %q{Secure single-domain session sharing plugin for Rails.}
+  s.description = %q{This Rails plugin allows several Rails web apps that share the same back-end user database to share session state in a cryptographically secure way, facilitating single sign-on in a distributed web app. It only provides session sharing and does not concern itself with authentication or replication of the user database.}
+
+  s.add_runtime_dependency('uuidtools', [">= 2.1.1"])
+
+  basedir = File.dirname(__FILE__)
+  candidates = ['has_global_session.gemspec', 'init.rb', 'MIT-LICENSE', 'README'] +
+            Dir['lib/**/*'] +
+            Dir['rails/**/*']
+  s.files = candidates.sort
+end
+
+if $PROGRAM_NAME == __FILE__
+   Gem.manage_gems if Gem::RubyGemsVersion.to_f < 1.0
+   Gem::Builder.new(spec).build
+end

data/init.rb

@@ -0,0 +1,4 @@
+# Stub to invoke real init.rb when HasGlobalSession is installed as a Rails
+# plugin.
+basedir = File.dirname(__FILE__)
+require File.join(basedir, 'rails', 'init')

data/lib/generators/global_session_config/USAGE

@@ -0,0 +1,2 @@
+./script/generate global_session config <DNS domain for cookie>
+./script/generate global_session authority <name of authority>

data/lib/generators/global_session_config/global_session_config_generator.rb

@@ -0,0 +1,19 @@
+class GlobalSessionConfigGenerator < Rails::Generator::Base
+  def initialize(runtime_args, runtime_options = {})
+    super
+
+    @app_name   = File.basename(RAILS_ROOT)
+    @app_domain = args.shift
+    raise ArgumentError, "Must specify DNS domain for global session cookie, e.g. 'example.com'" unless @app_domain
+  end
+
+  def manifest
+    record do |m|
+      
+      m.template 'templates/global_session.yml.erb',
+                 'config/global_session.yml',
+                 :assigns=>{:app_name=>@app_name,
+                            :app_domain=>@app_domain}
+    end
+  end
+end

data/lib/generators/global_session_config/templates/global_session.yml.erb

@@ -0,0 +1,30 @@
+# Common settings of the global session (that apply to all Rails environments)
+# are listed here. These may be overidden in the environment-specific section,
+# but it seldom makes sense to do so.
+common:
+  attributes:
+    # Signed attributes of the global session
+    signed:
+    - user
+    # Untrusted attributes of the global session
+    insecure:
+    - account
+  # Enable local session integration in order to use the ActionController
+  # method #session to access both local AND global session state, with
+  # global attributes always taking precedence over local attributes.
+  integrated: true
+
+development:
+  cookie:
+    name: __<%= app_name %>_development
+    domain: localhost
+
+test:
+  cookie:
+    name: __<%= app_name %>_test
+    domain: localhost
+
+production:
+  cookie:
+    name: __<%= app_name %>_global
+    domain: <%= app_domain %>

data/lib/has_global_session/configuration.rb

@@ -0,0 +1,34 @@
+module HasGlobalSession
+  module Configuration
+    mattr_accessor :config_file
+    mattr_accessor :environment
+    
+    def self.[](key)
+      unless @config
+        raise MissingConfiguration, "config_file is nil; cannot read configuration" unless config_file
+        raise MissingConfiguration, "environment is nil; must be specified" unless environment
+        @config = YAML.load(File.read(config_file))
+        validate
+      end
+      if @config.has_key?(environment) && @config[environment].has_key?(key)
+        return @config[environment][key]
+      else
+        @config['common'][key]
+      end
+    end
+
+    def self.validate
+      ['attributes/signed', 'integrated', 'cookie/name', 'cookie/domain'].each do |path|
+        elements = path.split '/'
+        object = self[elements.shift]
+        elements.each do |element|
+          object = object[element]
+          if object.nil?
+            msg = "#{File.basename(config_file)} does not specify required element #{elements.map { |x| "['#{x}']"}.join('')}"
+            raise MissingConfiguration, msg
+          end
+        end
+      end
+    end
+  end  
+end

data/lib/has_global_session/directory.rb

@@ -0,0 +1,30 @@
+module HasGlobalSession
+  class Directory
+    attr_reader :authorities, :my_private_key, :my_authority_name
+
+    def initialize(keystore_directory)
+      certs = Dir[File.join(keystore_directory, '*.pub')]
+      keys  = Dir[File.join(keystore_directory, '*.key')]
+
+      @authorities = {}
+      certs.each do |cert_file|
+        basename = File.basename(cert_file)
+        authority = basename[0...(basename.rindex('.'))] #chop trailing .ext
+        @authorities[authority] = OpenSSL::PKey::RSA.new(File.read(cert_file))
+        raise TypeError, "Expected #{basename} to contain an RSA public key" unless @authorities[authority].public?
+      end
+
+      raise ArgumentError, "Excepted 0 or 1 key files, found #{keys.size}" if ![0, 1].include?(keys.size)
+      if (key_file = keys[0])
+        basename = File.basename(key_file)
+        @my_private_key  = OpenSSL::PKey::RSA.new(File.read(key_file))
+        raise TypeError, "Expected #{basename} to contain an RSA private key" unless @my_private_key.private?
+        @my_authority_name = basename[0...(basename.rindex('.'))] #chop trailing .ext
+      end
+    end
+
+    def invalidated_session?(uuid)
+      false
+    end
+  end  
+end

data/lib/has_global_session/global_session.rb

@@ -0,0 +1,152 @@
+# Standard library dependencies
+require 'set'
+require 'zlib'
+
+# Gem dependencies
+require 'uuidtools'
+
+module HasGlobalSession 
+  class GlobalSession
+    attr_reader :id, :authority, :created_at, :expires_at
+
+    def initialize(directory, cookie=nil)
+      @schema_signed   = Set.new((Configuration['attributes']['signed'] rescue []))
+      @schema_insecure = Set.new((Configuration['attributes']['insecure'] rescue []))
+      @directory       = directory
+
+      if cookie
+        #User presented us with a cookie; let's decrypt and verify it
+        zbin = Base64.decode64(cookie)
+        json = Zlib::Inflate.inflate(zbin)
+        hash = ActiveSupport::JSON.decode(json)
+        @id         = hash['id']
+        @created_at = Time.at(hash['tc'].to_i)
+        @expires_at = Time.at(hash['te'].to_i)
+        @signed     = hash['ds']
+        @insecure   = hash['dx']
+        @signature  = hash['s']
+        @authority  = hash['a']
+
+        hash.delete('s')
+        expected = digest(hash)
+        signer   = @directory.authorities[@authority]
+        raise SecurityError, "Unknown signing authority #{@authority}" unless signer
+        got      = signer.public_decrypt(Base64.decode64(@signature))
+        unless (got == expected)
+          raise SecurityError, "Signature mismatch on global session cookie; tampering suspected"
+        end
+
+        if expired? || @directory.invalidated_session?(@id)
+          raise ExpiredSession, "Global session cookie has expired"
+        end
+
+      else
+        @signed          = {}
+        @insecure        = {}
+        @id              = UUIDTools::UUID.timestamp_create.to_s
+        @created_at      = Time.now.utc
+        @expires_at      = 2.hours.from_now.utc #TODO configurable
+        @authority       = @directory.my_authority_name
+        @dirty_secure    = true
+      end
+    end
+
+    def supports_key?(key)
+      @schema_signed.include?(key) || @schema_insecure.include?(key)
+    end
+
+    def expired?
+      (@expires_at <= Time.now)
+    end
+
+    def expire!
+      @expires_at = Time.at(0)
+      @dirty_secure = true
+    end
+
+    def to_s
+      hash = {'id'=>@id,
+              'tc'=>@created_at.to_i, 'te'=>@expires_at.to_i,
+              'ds'=>@signed, 'dx'=>@insecure}
+
+      if @signature && !@dirty_secure
+        #use cached signature unless we've changed secure state
+        authority = @authority
+        signature = @signature
+      else
+        authority = @directory.my_authority_name
+        hash['a'] = authority
+        digest    = digest(hash)
+        signature = Base64.encode64(@directory.my_private_key.private_encrypt(digest))
+      end
+
+      hash['s'] = signature
+      hash['a'] = authority
+      json = ActiveSupport::JSON.encode(hash)
+      zbin = Zlib::Deflate.deflate(json, Zlib::BEST_COMPRESSION)
+      return Base64.encode64(zbin)
+    end
+
+    def [](key)
+      @signed[key] || @insecure[key]
+    end
+
+    def []=(key, value)
+      if @schema_signed.include?(key)
+        unless @directory.my_private_key && @directory.my_authority_name
+          raise StandardError, 'Cannot change secure session attributes; we are not an authority'
+        end
+
+        @signed[key]  = value
+        @dirty_secure = true
+      elsif @schema_insecure.include?(key)
+        @insecure[key] = value
+      else
+        raise ArgumentError, "Attribute '#{key}' is not specified in global session configuration"
+      end
+    end
+
+    def has_key?(key)
+      @signed.has_key(key) || @insecure.has_key?(key)
+    end
+    
+    def keys
+      @signed.keys + @insecure.keys
+    end
+
+    def values
+      @signed.values + @insecure.values
+    end
+
+    def each_pair(&block)
+      @signed.each_pair(&block)
+      @insecure.each_pair(&block)
+    end
+
+    private
+
+    def digest(input)
+      canonical = ActiveSupport::JSON.encode(canonicalize(input))
+      return Digest::SHA1.new().update(canonical).hexdigest
+    end
+
+    def canonicalize(input)
+      case input
+        when Hash
+          output = ActiveSupport::OrderedHash.new
+          ordered_keys = input.keys.sort
+          ordered_keys.each do |key|
+            output[canonicalize(key)] = canonicalize(input[key])
+          end
+        when Array
+          output = input.collect { |x| canonicalize(x) }
+        when Numeric, String, ActiveSupport::OrderedHash
+          output = input
+        else
+          raise TypeError, "Objects of type #{input.class.name} cannot be serialized in the global session"
+      end
+
+      return output
+    end
+  end  
+end

data/lib/has_global_session/integrated_session.rb

@@ -0,0 +1,41 @@
+module HasGlobalSession
+  class IntegratedSession
+    def initialize(local_session, global_session)
+      @local_session = local_session
+      @global_session = global_session
+    end
+
+    def [](key)
+      if @global_session.supports_key?(key)
+        @global_session[key]
+      else
+        @local_session[key]
+      end
+    end
+
+    def []=(key, value)
+      if @global_session.supports_key?(key)
+        @global_session[key] = value
+      else
+        @local_session[key] = value
+      end
+    end
+
+    def has_key?(key)
+      @global_session.has_key(key) || @local_session.has_key?(key)
+    end
+
+    def keys
+      @global_session.keys + @local_session.keys
+    end
+
+    def values
+      @global_session.values + @local_session.values
+    end
+
+    def each_pair(&block)
+      @global_session.each_pair(&block)
+      @local_session.each_pair(&block)
+    end
+  end
+end

data/lib/has_global_session.rb

@@ -0,0 +1,10 @@
+module HasGlobalSession
+  class MissingConfiguration < Exception; end
+  class SessionExpired < Exception; end  
+end
+
+basedir = File.dirname(__FILE__)
+require File.join(basedir, 'has_global_session', 'configuration')
+require File.join(basedir, 'has_global_session', 'directory')
+require File.join(basedir, 'has_global_session', 'global_session')
+require File.join(basedir, 'has_global_session', 'integrated_session')

data/rails/action_controller_instance_methods.rb

@@ -0,0 +1,48 @@
+module HasGlobalSession
+  module ActionControllerInstanceMethods
+    def global_session
+      return @global_session if @global_session
+
+      begin
+        cookie = cookies[Configuration['cookie']['name']]
+        directory = Directory.new(File.join(RAILS_ROOT, 'config', 'authorities'))
+
+        begin
+          #unserialize the global session from the cookie, or
+          #initialize a new global session if cookie == nil
+          @global_session = GlobalSession.new(directory, cookie)
+        rescue SessionExpired
+          #if the cookie is present but expired, silently
+          #initialize a new global session
+          @global_session = GlobalSession.new(directory)
+        end
+      rescue Exception => e
+        cookies.delete Configuration['cookie']['name']
+        raise e
+      end
+    end
+
+    if Configuration['integrated']
+      def session
+        @integrated_session ||= IntegratedSession.new(super, global_session)
+        return @integrated_session
+      end
+    end
+
+    def global_session_update_cookie
+      if @global_session
+        if @global_session.expired?
+          options = {:value   => nil,
+                     :domain  => Configuration['cookie']['domain'],
+                     :expires => Time.at(0)}
+        else
+          options = {:value   => @global_session.to_s,
+                     :domain  => Configuration['cookie']['domain'],
+                     :expires => @global_session.expires_at}
+        end
+
+        cookies[Configuration['cookie']['name']] = options
+      end
+    end
+  end
+end

data/rails/init.rb

@@ -0,0 +1,18 @@
+basedir = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+require File.join(basedir, 'lib', 'has_global_session')
+
+# Tie the Configuration module to Rails' filesystem structure
+# and operating environment.
+HasGlobalSession::Configuration.config_file =
+  File.join(RAILS_ROOT, 'config', 'global_session.yml')
+HasGlobalSession::Configuration.environment = RAILS_ENV
+
+require File.join(basedir, 'rails', 'action_controller_instance_methods')
+
+# Enable ActionController integration.
+class ActionController::Base
+  def self.has_global_session
+    include HasGlobalSession::ActionControllerInstanceMethods
+    after_filter  :global_session_update_cookie
+  end
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification 
+name: has_global_session
+version: !ruby/object:Gem::Version 
+  version: 0.8.0
+platform: ruby
+authors: 
+- Tony Spataro
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-06-01 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: uuidtools
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.1.1
+    version: 
+description: This Rails plugin allows several Rails web apps that share the same back-end user database to share session state in a cryptographically secure way, facilitating single sign-on in a distributed web app. It only provides session sharing and does not concern itself with authentication or replication of the user database.
+email: code@tracker.xeger.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- MIT-LICENSE
+- README
+- has_global_session.gemspec
+- init.rb
+- lib/generators/global_session_config/USAGE
+- lib/generators/global_session_config/global_session_config_generator.rb
+- lib/generators/global_session_config/templates/global_session.yml.erb
+- lib/has_global_session.rb
+- lib/has_global_session/configuration.rb
+- lib/has_global_session/directory.rb
+- lib/has_global_session/global_session.rb
+- lib/has_global_session/integrated_session.rb
+- rails/action_controller_instance_methods.rb
+- rails/init.rb
+has_rdoc: true
+homepage: http://github.com/xeger/has_global_session
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: 1.8.7
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Secure single-domain session sharing plugin for Rails.
+test_files: []
+