Class: GlobalSession::Session::V1
- Defined in:
- lib/global_session/session/v1.rb
Overview
V1 uses JSON serialization and Zlib compression. Its JSON structure is a Hash with the following format:
{'id': <uuid_string> ,
'a': <signing_authority_string>,
'tc': <creation_timestamp_integer>,
'te': <expiration_timestamp_integer>,
'ds': {<signed_data_hash>},
'dx': {<unsigned_data_hash>},
's': <binary_signature_string>}
Limitations of V1 include the following:
-
Compressing the JSON usually INCREASES the size of the compressed data
-
The sign and verify algorithms, while safe, do not comply fully with PKCS7; they rely on the OpenSSL low-level crypto API instead of using the higher-level EVP (envelope) API.
Constant Summary collapse
- HEADER =
Pattern that matches strings that are probably a V1 session cookie.
/^eN/
Instance Attribute Summary
Attributes inherited from Abstract
#authority, #created_at, #directory, #expired_at, #id, #insecure, #signed
Class Method Summary collapse
-
.decode_cookie(cookie) ⇒ Object
Utility method to decode a cookie; good for console debugging.
Instance Method Summary collapse
-
#[](key) ⇒ Object
Lookup a value by its key.
-
#[]=(key, value) ⇒ Object
Set a value in the global session hash.
-
#dirty? ⇒ Boolean
Determine whether any state has changed since the session was loaded.
-
#each_pair(&block) ⇒ Object
Iterate over each key/value pair.
-
#keys ⇒ Object
Return the keys that are currently present in the global session.
-
#signature_digest ⇒ Object
Return the SHA1 hash of the most recently-computed RSA signature of this session.
-
#to_s ⇒ Object
Serialize the session to a form suitable for use with HTTP cookies.
-
#values ⇒ Object
Return the values that are currently present in the global session.
Methods inherited from Abstract
#delete, #has_key?, #initialize, #inspect, #invalidate!, #new_record?, #renew!, #supports_key?, #to_h, #valid?
Constructor Details
This class inherits a constructor from GlobalSession::Session::Abstract
Class Method Details
.decode_cookie(cookie) ⇒ Object
Utility method to decode a cookie; good for console debugging. This performs no validation or security check of any sort.
Parameters
- cookie(String)
-
well-formed global session cookie
50 51 52 53 54 |
# File 'lib/global_session/session/v1.rb', line 50 def self.() zbin = GlobalSession::Encoding::Base64Cookie.load() json = Zlib::Inflate.inflate(zbin) return GlobalSession::Encoding::JSON.load(json) end |
Instance Method Details
#[](key) ⇒ Object
Lookup a value by its key.
Parameters
- key(String)
-
the key
Return
- value(Object)
-
The value associated with
key
, or nil ifkey
is not present
134 135 136 137 |
# File 'lib/global_session/session/v1.rb', line 134 def [](key) key = key.to_s #take care of symbol-style keys @signed[key] || @insecure[key] end |
#[]=(key, value) ⇒ Object
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
155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 |
# File 'lib/global_session/session/v1.rb', line 155 def []=(key, value) key = key.to_s #take care of symbol-style keys raise GlobalSession::InvalidSession unless valid? #Ensure that the value is serializable (will raise if not) canonicalize(value) if @schema_signed.include?(key) @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 |
#dirty? ⇒ Boolean
Determine whether any state has changed since the session was loaded.
95 96 97 |
# File 'lib/global_session/session/v1.rb', line 95 def dirty? !!(super || @dirty_secure || @dirty_insecure) end |
#each_pair(&block) ⇒ Object
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
122 123 124 125 |
# File 'lib/global_session/session/v1.rb', line 122 def each_pair(&block) # :yields: |key, value| @signed.each_pair(&block) @insecure.each_pair(&block) end |
#keys ⇒ Object
Return the keys that are currently present in the global session.
Return
- keys(Array)
-
List of keys contained in the global session
103 104 105 |
# File 'lib/global_session/session/v1.rb', line 103 def keys @signed.keys + @insecure.keys end |
#signature_digest ⇒ Object
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
183 184 185 |
# File 'lib/global_session/session/v1.rb', line 183 def signature_digest @signature ? digest(@signature) : nil end |
#to_s ⇒ Object
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)
-
Base64Cookie-encoded, Zlib-compressed JSON-serialized global session
62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 |
# File 'lib/global_session/session/v1.rb', line 62 def to_s if @cookie && !dirty? #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_timestamps || @dirty_secure) #use cached signature unless we've changed secure state = @authority else = @directory. hash['a'] = digest = canonical_digest(hash) @signature = GlobalSession::Encoding::Base64Cookie.dump(@directory.private_key.private_encrypt(digest)) end hash['dx'] = @insecure hash['s'] = @signature hash['a'] = json = GlobalSession::Encoding::JSON.dump(hash) zbin = Zlib::Deflate.deflate(json, Zlib::BEST_COMPRESSION) return GlobalSession::Encoding::Base64Cookie.dump(zbin) end |
#values ⇒ Object
Return the values that are currently present in the global session.
Return
- values(Array)
-
List of values contained in the global session
111 112 113 |
# File 'lib/global_session/session/v1.rb', line 111 def values @signed.values + @insecure.values end |