global_session 0.9.0

data/lib/global_session/session.rb

@@ -0,0 +1,343 @@
+# Standard library dependencies
+require 'set'
+require 'zlib'
+
+# Gem dependencies
+require 'uuidtools'
+
+module GlobalSession
+  # Ladies and gentlemen: the one and only, star of the show, GLOBAL SESSION!
+  #
+  # Session is designed to act as much like a Hash as possible. You can use
+  # most of the methods you would use with Hash: [], has_key?, each, etc. It has a
+  # few additional methods that are specific to itself, mostly involving whether
+  # it's expired, valid, supports a certain key, etc.
+  #
+  class Session
+    attr_reader :id, :authority, :created_at, :expired_at, :directory
+
+    # Create a new global session object.
+    #
+    # === Parameters
+    # directory(Directory):: directory implementation that the session should use for various operations
+    # cookie(String):: Optional, serialized global session cookie. If none is supplied, a new session is created.
+    # valid_signature_digest(String):: Optional, already-trusted signature. If supplied, the expensive RSA-verify operation will be skipped if the cookie's signature matches the value supplied.
+    #
+    # ===Raise
+    # InvalidSession:: if the session contained in the cookie has been invalidated
+    # ExpiredSession:: if the session contained in the cookie has expired
+    # MalformedCookie:: if the cookie was corrupt or malformed
+    # SecurityError:: if signature is invalid or cookie is not signed by a trusted authority
+    def initialize(directory, cookie=nil, valid_signature_digest=nil)
+      @configuration   = directory.configuration
+      @schema_signed   = Set.new((@configuration['attributes']['signed']))
+      @schema_insecure = Set.new((@configuration['attributes']['insecure']))
+      @directory       = directory
+
+      if cookie && !cookie.empty?
+        load_from_cookie(cookie, valid_signature_digest)
+      elsif @directory.local_authority_name
+        create_from_scratch
+      else
+        create_invalid
+      end
+    end
+
+    # Determine whether the session is valid. This method simply delegates to the
+    # directory associated with this session.
+    #
+    # === Return
+    # valid(true|false):: True if the session is valid, false otherwise
+    def valid?
+      @directory.valid_session?(@id, @expired_at)
+    end
+
+    # Serialize the session to a form suitable for use with HTTP cookies. If any
+    # secure attributes have changed since the session was instantiated, compute
+    # a fresh RSA signature.
+    #
+    # === Return
+    # cookie(String):: The B64cookie-encoded Zlib-compressed JSON-serialized global session hash
+    def to_s
+      if @cookie && !@dirty_insecure && !@dirty_secure
+        #use cached cookie if nothing has changed
+        return @cookie
+      end
+
+      hash = {'id'=>@id,
+              'tc'=>@created_at.to_i, 'te'=>@expired_at.to_i,
+              'ds'=>@signed}
+
+      if @signature && !@dirty_secure
+        #use cached signature unless we've changed secure state
+        authority = @authority
+      else
+        authority_check
+        authority = @directory.local_authority_name
+        hash['a'] = authority
+        digest    = canonical_digest(hash)
+        @signature = Encoding::Base64Cookie.dump(@directory.private_key.private_encrypt(digest))
+      end
+
+      hash['dx'] = @insecure
+      hash['s']  = @signature
+      hash['a']  = authority
+      
+      json = Encoding::JSON.dump(hash)
+      zbin = Zlib::Deflate.deflate(json, Zlib::BEST_COMPRESSION)
+      return Encoding::Base64Cookie.dump(zbin)
+    end
+
+    # Determine whether the global session schema allows a given key to be placed
+    # in the global session.
+    #
+    # === Parameters
+    # key(String):: The name of the key
+    #
+    # === Return
+    # supported(true|false):: Whether the specified key is supported
+    def supports_key?(key)
+      @schema_signed.include?(key) || @schema_insecure.include?(key)
+    end
+
+    # Determine whether this session contains a value with the specified key.
+    #
+    # === Parameters
+    # key(String):: The name of the key
+    #
+    # === Return
+    # contained(true|false):: Whether the session currently has a value for the specified key.
+    def has_key?(key)
+      @signed.has_key?(key) || @insecure.has_key?(key)
+    end
+
+    # Return the keys that are currently present in the global session.
+    #
+    # === Return
+    # keys(Array):: List of keys contained in the global session
+    def keys
+      @signed.keys + @insecure.keys
+    end
+
+    # Return the values that are currently present in the global session.
+    #
+    # === Return
+    # values(Array):: List of values contained in the global session
+    def values
+      @signed.values + @insecure.values
+    end
+
+    # Iterate over each key/value pair
+    #
+    # === Block
+    # An iterator which will be called with each key/value pair
+    #
+    # === Return
+    # Returns the value of the last expression evaluated by the block
+    def each_pair(&block) # :yields: |key, value|
+      @signed.each_pair(&block)
+      @insecure.each_pair(&block)
+    end
+
+    # Lookup a value by its key.
+    #
+    # === Parameters
+    # key(String):: the key
+    #
+    # === Return
+    # value(Object):: The value associated with +key+, or nil if +key+ is not present
+    def [](key)
+      key = key.to_s #take care of symbol-style keys
+      @signed[key] || @insecure[key]
+    end
+
+    # Set a value in the global session hash. If the supplied key is denoted as
+    # secure by the global session schema, causes a new signature to be computed
+    # when the session is next serialized.
+    #
+    # === Parameters
+    # key(String):: The key to set
+    # value(Object):: The value to set
+    #
+    # === Return
+    # value(Object):: Always returns the value that was set
+    #
+    # ===Raise
+    # InvalidSession:: if the session has been invalidated (and therefore can't be written to)
+    # ArgumentError:: if the configuration doesn't define the specified key as part of the global session
+    # NoAuthority:: if the specified key is secure and the local node is not an authority
+    # UnserializableType:: if the specified value can't be serialized as JSON
+    def []=(key, value)
+      key = key.to_s #take care of symbol-style keys
+      raise InvalidSession unless valid?
+
+      #Ensure that the value is serializable (will raise if not)
+      canonicalize(value)
+
+      if @schema_signed.include?(key)
+        authority_check
+        @signed[key]  = value
+        @dirty_secure = true
+      elsif @schema_insecure.include?(key)
+        @insecure[key] = value
+        @dirty_insecure = true
+      else
+        raise ArgumentError, "Attribute '#{key}' is not specified in global session configuration"
+      end
+
+      return value
+    end
+
+    # Invalidate this session by reporting its UUID to the Directory.
+    #
+    # === Return
+    # unknown(Object):: Returns whatever the Directory returns
+    def invalidate!
+      @directory.report_invalid_session(@id, @expired_at)
+    end
+
+    # Renews this global session, changing its expiry timestamp into the future.
+    # Causes a new signature will be computed when the session is next serialized.
+    #
+    # === Return
+    # true:: Always returns true
+    def renew!(expired_at=nil)
+      authority_check
+      minutes = @configuration['timeout'].to_i
+      expired_at ||= Time.at(Time.now.utc + 60 * minutes)
+      @expired_at = expired_at
+      @dirty_secure = true
+    end
+
+    # Return the SHA1 hash of the most recently-computed RSA signature of this session.
+    # This isn't really intended for the end user; it exists so the Web framework integration
+    # code can optimize request speed by caching the most recently verified signature in the
+    # local session and avoid re-verifying it on every request.
+    #
+    # === Return
+    # digest(String):: SHA1 hex-digest of most-recently-computed signature
+    def signature_digest
+      @signature ? digest(@signature) : nil
+    end
+
+    private
+
+    def authority_check # :nodoc:
+      unless @directory.local_authority_name
+        raise NoAuthority, 'Cannot change secure session attributes; we are not an authority'
+      end      
+    end
+
+    def canonical_digest(input) # :nodoc:
+      canonical = Encoding::JSON.dump(canonicalize(input))
+      return digest(canonical)
+    end
+
+    def digest(input) # :nodoc:
+      return Digest::SHA1.new().update(input).hexdigest
+    end
+
+    def canonicalize(input) # :nodoc:
+      case input
+        when Hash
+          output = Array.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, NilClass
+          output = input
+        else
+          raise UnserializableType, "Objects of type #{input.class.name} cannot be serialized in the global session"
+      end
+
+      return output
+    end
+
+    def load_from_cookie(cookie, valid_signature_digest) # :nodoc:
+      begin
+        zbin = Encoding::Base64Cookie.load(cookie)
+        json = Zlib::Inflate.inflate(zbin)
+        hash = Encoding::JSON.load(json)
+      rescue Exception => e
+        mc = MalformedCookie.new("Caused by #{e.class.name}: #{e.message}")
+        mc.set_backtrace(e.backtrace)
+        raise mc
+      end
+
+      id         = hash['id']
+      authority  = hash['a']
+      created_at = Time.at(hash['tc'].to_i).utc
+      expired_at = Time.at(hash['te'].to_i).utc
+      signed     = hash['ds']
+      insecure   = hash.delete('dx')
+      signature  = hash.delete('s')
+
+      unless valid_signature_digest == digest(signature)
+        #Check signature
+        expected = canonical_digest(hash)
+        signer   = @directory.authorities[authority]
+        raise SecurityError, "Unknown signing authority #{authority}" unless signer
+        got      = signer.public_decrypt(Encoding::Base64Cookie.load(signature))
+        unless (got == expected)
+          raise SecurityError, "Signature mismatch on global session cookie; tampering suspected"
+        end
+      end
+      
+      #Check trust in signing authority
+      unless @directory.trusted_authority?(authority)
+        raise SecurityError, "Global sessions signed by #{authority} are not trusted"
+      end
+
+      #Check expiration
+      unless expired_at > Time.now.utc
+        raise ExpiredSession, "Session expired at #{expired_at}"        
+      end
+
+      #Check other validity (delegate to directory)
+      unless @directory.valid_session?(id, expired_at)
+        raise InvalidSession, "Global session has been invalidated"
+      end
+
+      #If all validation stuff passed, assign our instance variables.
+      @id         = id
+      @authority  = authority
+      @created_at = created_at
+      @expired_at = expired_at
+      @signed     = signed
+      @insecure   = insecure
+      @signature  = signature
+      @cookie     = cookie
+    end
+
+    def create_from_scratch # :nodoc:
+      authority_check
+
+      @signed          = {}
+      @insecure        = {}
+      @created_at      = Time.now.utc
+      @authority       = @directory.local_authority_name
+
+      if defined?(::UUIDTools) # UUIDTools v2
+        @id = ::UUIDTools::UUID.timestamp_create.to_s
+      elsif defined?(::UUID)   # UUIDTools v1
+        @id = ::UUID.timestamp_create.to_s
+      else
+        raise TypeError, "Neither UUIDTools nor UUID defined; unsupported UUIDTools version?"
+      end
+
+      renew!
+    end
+
+    def create_invalid # :nodoc:
+      @id         = nil
+      @created_at = Time.now.utc
+      @expired_at = created_at
+      @signed     = {}
+      @insecure   = {}
+      @authority  = nil
+    end
+  end  
+end

data/lib/global_session.rb

@@ -0,0 +1,63 @@
+module GlobalSession
+  # Indicates that the global session configuration file is malformatted or missing
+  # required fields. Also used as a base class for other errors.
+  class ConfigurationError < Exception; end
+
+  # The general category of client-side errors. Used solely as a base class.
+  class ClientError < Exception; end
+
+  # Indicates that the global session configuration file is missing from disk.
+  #
+  class MissingConfiguration < ConfigurationError; end
+
+  # Indicates that a client submitted a request with a valid session cookie, but the
+  # session ID was reported as invalid by the Directory.
+  #
+  # See Directory#valid_session? for more information.
+  #
+  class InvalidSession < ClientError; end
+
+  # Indicates that a client submitted a request with a valid session cookie, but the
+  # session has expired.
+  #
+  class ExpiredSession < ClientError; end
+
+  # Indicates that a client submitted a request with a session cookie that could not
+  # be decoded or decompressed.
+  #
+  class MalformedCookie < ClientError; end
+
+  # Indicates that application code tried to put an unserializable object into the glboal
+  # session hash. Because the global session is serialized as JSON and not all Ruby types
+  # can be easily round-tripped to JSON and back without data loss, we constrain the types
+  # that can be serialized.
+  #
+  # See GlobalSession::Encoding::JSON for more information on serializable types.
+  #
+  class UnserializableType < ConfigurationError; end
+
+  # Indicates that the application code tried to write a secure session attribute or
+  # renew the global session. Both of these operations require a local authority
+  # because they require a new signature to be computed on the global session.
+  #
+  # See GlobalSession::Configuration and GlobalSession::Directory for more
+  # information.
+  #
+  class NoAuthority < ConfigurationError; end
+end
+
+#Make sure gem dependencies are activated.
+require 'uuidtools'
+require 'json'
+require 'active_support'
+
+#Require Ruby library dependencies
+require 'openssl'
+
+#Require the core suite of GlobalSession classes and modules
+basedir = File.dirname(__FILE__)
+require File.join(basedir, 'global_session', 'configuration')
+require File.join(basedir, 'global_session', 'directory')
+require File.join(basedir, 'global_session', 'encoding')
+require File.join(basedir, 'global_session', 'session')
+require File.join(basedir, 'global_session', 'integrated_session')

data/rails/init.rb

@@ -0,0 +1,3 @@
+#
+# Empty placeholder file so Rails 2.x will recognize us as a plugin
+#

data/rails_generators/global_session_authority/USAGE

@@ -0,0 +1 @@
+./script/generate global_session authority <name of authority>

data/rails_generators/global_session_authority/global_session_authority_generator.rb

@@ -0,0 +1,32 @@
+class GlobalSessionAuthorityGenerator < Rails::Generator::Base
+  def initialize(runtime_args, runtime_options = {})
+    super
+
+    @app_name  = File.basename(::Rails.root)
+    @auth_name = args.shift
+    raise ArgumentError, "Must specify name for global session authority, e.g. 'mycoolapp'" unless @auth_name
+  end
+
+  def manifest
+    record do |m|
+      new_key     = OpenSSL::PKey::RSA.generate( 1024 )
+      new_public  = new_key.public_key.to_pem
+      new_private = new_key.to_pem
+
+      dest_dir = File.join(::Rails.root, 'config', 'authorities')
+      FileUtils.mkdir_p(dest_dir)
+
+      File.open(File.join(dest_dir, @auth_name + ".pub"), 'w') do |f|
+        f.puts new_public
+      end
+
+      File.open(File.join(dest_dir, @auth_name + ".key"), 'w') do |f|
+        f.puts new_private
+      end
+
+      puts "***"
+      puts "*** Don't forget to delete config/authorities/#{@auth_name}.key"
+      puts "***"
+    end
+  end
+end

data/rails_generators/global_session_config/USAGE

@@ -0,0 +1 @@
+./script/generate global_session config <DNS domain for production cookie>

data/rails_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 'global_session.yml.erb',
+                 'config/global_session.yml',
+                 :assigns=>{:app_name=>@app_name,
+                            :app_domain=>@app_domain}
+    end
+  end
+end

data/rails_generators/global_session_config/templates/global_session.yml.erb

@@ -0,0 +1,49 @@
+# Common settings of the global session (that apply to all Rails environments)
+# are listed here. These may be overidden in the environment-specific section.
+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
+  ephemeral: false
+  
+# Test/spec runs
+test:
+  timeout: 15 #minutes
+  renew: 5 #minutes before expiration
+  cookie:
+    name: _session_gbl
+  #the name of the local authority (optional)
+  authority: test
+  #which authorities this app will trust
+  trust:
+  - test
+
+# Development mode
+development:
+  timeout: 60
+  renew: 15
+  cookie:
+    name: _session_gbl
+  authority: development
+  trust:
+  - development
+  - production
+
+# Production mode
+production:
+  timeout: 60
+  renew: 15
+  cookie:
+    name: _session_gbl
+    domain: <%= app_domain %>
+  authority: production
+  trust:
+  - production