global_session 3.0.5 → 3.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b314fdf883f6db5a94056c8f4425b645ce26ce26
+  data.tar.gz: f2598c6bc89cf364070919a0d7d4704660721664
+SHA512:
+  metadata.gz: cce6b5236c84c60d94df3342a78c2f63bb5289c9d8c31c089983d1e3eb7905b83f5aa5e50f444061d3bd320745411a564db932153c71d04f7a40e2afecad3032
+  data.tar.gz: d2e8e7feb7641b439ff2e44f3e145c6f7f1f131ece9044c5edcc662c3a73a49ba590b7de1a623c751808c35dad02ffe18d06a251e7a5c18520e0d0b3fb849056

data/.travis.yml

@@ -0,0 +1,8 @@
+language: ruby
+cache: bundler
+rvm:
+  - 1.8.7
+  - 2.1
+script:
+  - bundle exec rake ci:spec
+bundler_args: --without development

data/CHANGELOG.rdoc

@@ -1,4 +1,22 @@
-== 2.0
+== 3.1 (2015-01-27)
+
+Split Directory class into Directory & Keystore, retaining some backward-compatibility shims
+inside Directory. In v4, these shims will be removed and all key management concerns will be
+handled by Keystore; the Directory class will be limited to session creation, renewal, and
+validity checking.
+
+== 3.0 (2013-10-03)
+
+The format of the global session cookie has been reinvented again! It once again uses JSON
+(because msgpack was not widely supported in other languages/OSes) but retains the compact
+array encoding introduced in v2.
+
+The cryptographic signature scheme has been changed for better compatibility; we now use
+PKCS1 v1.5 sign and verify operations instead of "raw" RSA. v2 and v1 sessions are fully
+supported for read/write, but any session created with the v3 gem will use the v3 crypto
+scheme.
+
+== 2.0 (2012-11-06)
 
 The format of the global session cookie has been reinvented; it now uses msgpack and delegates
 all crypto to RightSupport::Crypto::SignedHash. Together with a few other optimizations, the
@@ -11,16 +29,15 @@ The "integrated" feature is no longer supported for the Rails integration layer;
 attributes must always be accessed separately from local session attributes, through the
 #global_session reader method that is mixed into ActionController::Base.
 
-== 1.0
+== 1.0 (2011-01-01)
 
-Mostly interface-compatible with 0.9.
+General Availability release. Mostly interface-compatible with 0.9.
 
-== 0.9
+== 0.9 (2010-12-07)
 
 Rack middleware implementation is feature-complete and has major spec coverage. Rails integration
 is untested and may contain bugs.
 
 === 0.9.0 (2010-12-22)
 
-* Initial commit ported from 'rack' branch of old has_global_session project
-
+Initial commit ported from 'rack' branch of old has_global_session project

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2009-2012 RightScale, Inc.
+Copyright (c) 2009-2015 RightScale, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -1,39 +1,40 @@
+Copyright (c) 2009-2015 RightScale, Inc. <support@rightscale.com>; see LICENSE for more details.
+
 = Introduction
 
 GlobalSession enables multiple heterogeneous Web applications to share
 session state in a cryptographically secure way, facilitating single sign-on
-and enabling easier development of distributed applications that
-make use of architectural strategies such as sharding or separation of concerns.
+and enabling easier development of distributed applications that make use of
+architectural strategies such as sharding or separation of concerns.
 
-In other words: it glues your semi-related Web apps together so they share the
-same bits of session state. This is done by putting the session itself into
-cookies.
+In other words: it glues your Web apps together by letting them share session state.
+This is done by putting the session itself into a cookie and adding some crypto to
+protect against tampering.
 
 Maintained by
- - [Sapphire Team](https://wookiee.rightscale.com/display/rightscale/Meet+the+Sapphire+Team)
+ - [RightScale Engineering](https://github.com/rightscale)
 
 Merge to master whitelist
  - @tony-spataro-rs
- - @ryanwilliamson
 
 == What Is It Not?
 
-This plugin does not provide a complete solution for identity management. In
+This gem does not provide a complete solution for identity management. In
 particular, it does not provide any of the following:
 
-* <b>federation</b> -- aka cross-domain single sign-on -- use OpenID for that.
+* <b>federation</b> -- aka cross-domain single sign-on -- use SAML for that.
 
 * <b>authentication</b> -- the application must authenticate the user.
 
 * <b>authorization</b> -- the application is responsible for using the contents
   of the global session to make authorization decisions.
 
-* <b>secrecy</b> -- global session attributes can be signed but never encrypted;
-  protect against third-party snooping using SSL. Group secrecy is expensive;
+* <b>secrecy</b> -- global session attributes can be signed but never encrypted.
+  Protect against third-party snooping using SSL. Group secrecy is expensive;
   if you don't want your users to see their session state, put it in a database,
   or in an encrypted local session cookie.
 
-* <b>replication</b> -- the authentication authorities must have some way to
+* <b>replication</b> -- the session authorities must have some way to
   share information about the database of users in order to authenticate
   them and place identifying information into the global session.
 
@@ -41,7 +42,9 @@ particular, it does not provide any of the following:
   notification when sessions are invalidated; they can override the default
   Directory implementation to do realtime revocation checking.
 
-= Example
+= Examples
+
+== Integration with Rails
 
 1) Create a basic config file and edit it to suit your needs:
     $ script/generate global_session_config mycoolapp.com
@@ -59,32 +62,45 @@ particular, it does not provide any of the following:
     ...
     @current_user = User.find(global_session['user'])
 
+== Integration with Other Ruby Web Frameworks
+
+Install the GlobalSession middleware into your Rack stack; pass a config and a directory
+object to its initializer. For instance, in config.ru:
+
+    configuration = GlobalSession::Configuration.new('path/to/config.yml', RACK_ENV)
+    directory = GlobalSession::Directory.new(configuration, 'path/to/keystore')
+    use ::GlobalSession::Rack::Middleware, configuration, directory
+
 = 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:
+Global session state is stored as a cookie in the user's browser and/or sent
+with every request as an HTTP Authorization header. If your app uses the
+Authorization header, then it's responsible for communicating new or changed
+header values to clients out-of-band (i.e. as part of an OAuth refresh-token
+operation). If your app uses the cookie, GlobalSession will take care of
+updating the cookie whenever session values change.
+
+Data-wise, the session is a JSON dictionary containing the following stuff:
 * session metadata (UUID, created-at, expires-at, signing-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 one of its attributes. The cookie's value is updated
-whenever attributes change. As an optimization, the signature is only
-recomputed when the metadata or signed attributes have changed; insecure
-attributes can change "for free."
+Rack receives a request. The cookie's value is updated whenever 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, GlobalSession
 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, which can be trusted
-to make authorization decisions (because they are signed), and are insecure
-and therefore act only as "hints" about the session.
+to make authorization decisions (because they are signed), and which are
+insecure and act only as "hints" about the session.
 
 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.
+types can be stored in it: nil, strings, numbers, lists, hashes, booleans
+and other Ruby primitives.
 
 = Detailed Information
 
@@ -109,6 +125,9 @@ cookie's domain is "example.com". My app nodes at app1.example.com and
 app2.example.com would be part of the global session domain, but my business
 partner's application at app3.partner.com could not participate.
 
+If your app uses an Authorization header instead of cookies, the domain-name
+constraint does not apply!
+
 == Authorities and Relying Parties
 
 A node that can create or update the global session is said to be an "authority"
@@ -135,19 +154,19 @@ 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 node vs. storefront node vs. admin node
+* e-commerce app vs. storefront app vs. admin app
 
-== The Directory
+== The Keystore
 
-The Directory is a Ruby object instantiated by GlobalSession 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.
+The Directory is a Ruby object that provides lookups of public and private
+keys. Given an authority name (as found in a session cookie), the Directory
+can find the corresponding RSA public key.
 
-If the local system is an authority itself, #local_authority_name will
-return non-nil and #private_key will return a private key suitable for
-signing session attributes.
+If the local system is an authority itself, #private_key_name will
+return the authority name and #private_key will return an RSA private key
+suitable for signing session attributes.
 
-The Directory implementation included with GlobalSession uses the filesystem
+The Keystore implementation included with GlobalSession uses the filesystem
 as the backing store for its key pairs. Its #initialize method accepts a
 filesystem path that will be searched for files containing PEM-encoded public
 and private keys (the same format used by OpenSSH). This simple Directory
@@ -161,11 +180,39 @@ implementation relies on the following conventions:
 When used with a Rails app, GlobalSession 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!! (*.pub
-files can be checked into source control and distributed freely.) 
+files can be checked into source control and distributed freely.)
 
 If you wish all of the systems to stop trusting an authority, simply delete
 its public key from config/authorities and re-deploy your app.
 
+The keystore needs to be told where to find its keys. This is accomplished by
+setting some configuration attributes like so:
+
+    keystore:
+      public:
+        - config/authorities
+        - config/more_authorities
+      private: config/authorities/my_private.key
+
+The filename of keys is relevant; after stripping the *.pub or *.key extension,
+the remainder of the file's basename is taken to be the authority name. For
+instance, "production.pub" is the public key of the authority named "production"
+and "development.key" is the private key of the authority named "development."
+
+== The Directory
+
+The Directory is a Ruby object that performs session management operations,
+including:
+* Checking whether sessions have become invalid (e.g. after sign-out)
+* Creating new sessions
+* Unserializing existing sessions
+* Renewing sessions if they will expire
+* Updating session signatures
+
+In GlobalSession v3, Directory also presents methods for key management, but
+these are all delegated to the Keystore class. In v4, the concerns of Directory
+and Keystore will be fully separated.
+
 === Implementing Your Own Directory Provider
 
 To replace or enhance the built-in Directory, simply create a new class that
@@ -173,7 +220,6 @@ extends Directory and put the class somewhere in your app (the lib directory
 is a good choice). In the GlobalSession configuration file, specify the
 class name of the directory under the 'common' section, like so:
 
-  common:
-    directory: MyCoolDirectory
-
-Copyright (c) 2010 Tony Spataro <code@tracker.xeger.net>, released under the MIT license
+    common:
+      directory:
+        class: MyCoolDirectory

data/Rakefile

@@ -2,6 +2,7 @@
 require 'rubygems'
 require 'rake'
 require 'right_develop'
+require 'right_support'
 require 'spec/rake/spectask'
 require 'rubygems/package_task'
 require 'rake/clean'
@@ -17,28 +18,29 @@ Spec::Rake::SpecTask.new do |t|
   end
 end
 
-desc "run functional tests"
+desc "Run functional tests"
 Cucumber::Rake::Task.new do |t|
   t.cucumber_opts = %w{--tags ~@slow --color --format pretty}
 end
 
-require 'jeweler'
-Jeweler::Tasks.new do |gem|
-  # gem is a Gem::Specification; see http://docs.rubygems.org/read/chapter/20 for more options
-  gem.name = "global_session"
-  gem.homepage = "https://github.com/rightscale/global_session"
-  gem.license = "MIT"
-  gem.summary = %Q{Secure single-domain session sharing plugin for Rack and Rails.}
-  gem.description = %Q{This Rack middleware allows several web apps in an authentication domain to share session state, 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.}
-  gem.email = "support@rightscale.com"
-  gem.authors = ['Tony Spataro']
-  gem.files.exclude 'Gemfile*'
-  gem.files.exclude 'features/**/*'
-  gem.files.exclude 'fixtures/**/*'
-  gem.files.exclude 'features/**/*'
-  gem.files.exclude 'spec/**/*'
+if require_succeeds? 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    # gem is a Gem::Specification; see http://docs.rubygems.org/read/chapter/20 for more options
+    gem.name = "global_session"
+    gem.homepage = "https://github.com/rightscale/global_session"
+    gem.license = "MIT"
+    gem.summary = %Q{Secure single-domain session sharing plugin for Rack and Rails.}
+    gem.description = %Q{This Rack middleware allows several web apps in an authentication domain to share session state, 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.}
+    gem.email = "support@rightscale.com"
+    gem.authors = ['Tony Spataro']
+    gem.files.exclude 'Gemfile*'
+    gem.files.exclude 'features/**/*'
+    gem.files.exclude 'fixtures/**/*'
+    gem.files.exclude 'features/**/*'
+    gem.files.exclude 'spec/**/*'
+  end
+  Jeweler::RubygemsDotOrgTasks.new
 end
-Jeweler::RubygemsDotOrgTasks.new
 
 CLEAN.include('pkg')
 

data/VERSION

@@ -1 +1 @@
-3.0.5
+3.1.0

data/global_session.gemspec

@@ -2,16 +2,16 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: global_session 3.0.5 ruby lib
+# stub: global_session 3.1.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "global_session"
-  s.version = "3.0.5"
+  s.version = "3.1.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib"]
   s.authors = ["Tony Spataro"]
-  s.date = "2014-11-12"
+  s.date = "2014-12-31"
   s.description = "This Rack middleware allows several web apps in an authentication domain to share session state, 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.email = "support@rightscale.com"
   s.extra_rdoc_files = [
@@ -19,6 +19,7 @@ Gem::Specification.new do |s|
     "README.rdoc"
   ]
   s.files = [
+    ".travis.yml",
     "CHANGELOG.rdoc",
     "LICENSE",
     "README.rdoc",
@@ -30,6 +31,7 @@ Gem::Specification.new do |s|
     "lib/global_session/configuration.rb",
     "lib/global_session/directory.rb",
     "lib/global_session/encoding.rb",
+    "lib/global_session/keystore.rb",
     "lib/global_session/rack.rb",
     "lib/global_session/rails.rb",
     "lib/global_session/rails/action_controller_class_methods.rb",
@@ -48,7 +50,7 @@ Gem::Specification.new do |s|
   ]
   s.homepage = "https://github.com/rightscale/global_session"
   s.licenses = ["MIT"]
-  s.rubygems_version = "2.2.0"
+  s.rubygems_version = "2.2.2"
   s.summary = "Secure single-domain session sharing plugin for Rack and Rails."
 
   if s.respond_to? :specification_version then
@@ -57,49 +59,31 @@ Gem::Specification.new do |s|
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
       s.add_runtime_dependency(%q<json>, ["~> 1.4"])
       s.add_runtime_dependency(%q<rack-contrib>, ["~> 1.0"])
-      s.add_runtime_dependency(%q<right_support>, ["< 3.0", ">= 2.8.2"])
+      s.add_runtime_dependency(%q<right_support>, ["< 4.0", ">= 2.8.2"])
       s.add_runtime_dependency(%q<simple_uuid>, [">= 0.2.0"])
-      s.add_development_dependency(%q<cucumber>, ["~> 1.0"])
-      s.add_development_dependency(%q<debugger>, ["~> 1.5"])
-      s.add_development_dependency(%q<flexmock>, ["~> 0.8"])
-      s.add_development_dependency(%q<httpclient>, [">= 0"])
-      s.add_development_dependency(%q<jeweler>, ["~> 1.8.3"])
-      s.add_development_dependency(%q<msgpack>, ["~> 0.4"])
-      s.add_development_dependency(%q<rake>, ["~> 0.8"])
-      s.add_development_dependency(%q<right_develop>, ["~> 1.2"])
-      s.add_development_dependency(%q<rspec>, ["~> 1.3"])
       s.add_development_dependency(%q<ruby-debug>, ["~> 0.10"])
+      s.add_development_dependency(%q<pry>, ["~> 0.10"])
+      s.add_development_dependency(%q<pry-byebug>, ["~> 2.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.8.3"])
     else
       s.add_dependency(%q<json>, ["~> 1.4"])
       s.add_dependency(%q<rack-contrib>, ["~> 1.0"])
-      s.add_dependency(%q<right_support>, ["< 3.0", ">= 2.8.2"])
+      s.add_dependency(%q<right_support>, ["< 4.0", ">= 2.8.2"])
       s.add_dependency(%q<simple_uuid>, [">= 0.2.0"])
-      s.add_dependency(%q<cucumber>, ["~> 1.0"])
-      s.add_dependency(%q<debugger>, ["~> 1.5"])
-      s.add_dependency(%q<flexmock>, ["~> 0.8"])
-      s.add_dependency(%q<httpclient>, [">= 0"])
-      s.add_dependency(%q<jeweler>, ["~> 1.8.3"])
-      s.add_dependency(%q<msgpack>, ["~> 0.4"])
-      s.add_dependency(%q<rake>, ["~> 0.8"])
-      s.add_dependency(%q<right_develop>, ["~> 1.2"])
-      s.add_dependency(%q<rspec>, ["~> 1.3"])
       s.add_dependency(%q<ruby-debug>, ["~> 0.10"])
+      s.add_dependency(%q<pry>, ["~> 0.10"])
+      s.add_dependency(%q<pry-byebug>, ["~> 2.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.8.3"])
     end
   else
     s.add_dependency(%q<json>, ["~> 1.4"])
     s.add_dependency(%q<rack-contrib>, ["~> 1.0"])
-    s.add_dependency(%q<right_support>, ["< 3.0", ">= 2.8.2"])
+    s.add_dependency(%q<right_support>, ["< 4.0", ">= 2.8.2"])
     s.add_dependency(%q<simple_uuid>, [">= 0.2.0"])
-    s.add_dependency(%q<cucumber>, ["~> 1.0"])
-    s.add_dependency(%q<debugger>, ["~> 1.5"])
-    s.add_dependency(%q<flexmock>, ["~> 0.8"])
-    s.add_dependency(%q<httpclient>, [">= 0"])
-    s.add_dependency(%q<jeweler>, ["~> 1.8.3"])
-    s.add_dependency(%q<msgpack>, ["~> 0.4"])
-    s.add_dependency(%q<rake>, ["~> 0.8"])
-    s.add_dependency(%q<right_develop>, ["~> 1.2"])
-    s.add_dependency(%q<rspec>, ["~> 1.3"])
     s.add_dependency(%q<ruby-debug>, ["~> 0.10"])
+    s.add_dependency(%q<pry>, ["~> 0.10"])
+    s.add_dependency(%q<pry-byebug>, ["~> 2.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.8.3"])
   end
 end
 

data/lib/global_session.rb

@@ -87,6 +87,7 @@ require 'openssl'
 
 #Require the core suite of GlobalSession classes and modules
 require 'global_session/configuration'
+require 'global_session/keystore'
 require 'global_session/directory'
 require 'global_session/encoding'
 require 'global_session/session'