class Utopia::Session

A middleware which provides a secure client-side session storage using a private symmetric encrpytion key.

Constants

CIPHER_ALGORITHM
DEFAULT_EXPIRES_AFTER

The session will expire if no requests were made within 24 hours:

DEFAULT_UPDATE_TIMEOUT

At least, the session will be updated every 1 hour:

MAXIMUM_SIZE
RACK_SESSION
SECRET_KEY

Attributes

expires_after[R]
key[R]
update_timeout[R]

Public Class Methods

new(app, session_name: RACK_SESSION, secret: nil, expires_after: DEFAULT_EXPIRES_AFTER, update_timeout: DEFAULT_UPDATE_TIMEOUT, secure: false, same_site: :lax, maximum_size: MAXIMUM_SIZE, **options) click to toggle source

@param session_name [String] The name of the session cookie. @param secret [Array] The secret text used to generate a symetric encryption key for the coookie data. @param same_site [Symbol, String] Controls how the cookie is provided to the site. @param expires_after [String] The cache-control header to set for static content. @param options [Hash<Symbol,Object>] Additional defaults used for generating the cookie by `Rack::Utils.set_cookie_header!`.

# File lib/utopia/session.rb, line 55
def initialize(app, session_name: RACK_SESSION, secret: nil, expires_after: DEFAULT_EXPIRES_AFTER, update_timeout: DEFAULT_UPDATE_TIMEOUT, secure: false, same_site: :lax, maximum_size: MAXIMUM_SIZE, **options)
        @app = app
        
        @session_name = session_name
        @cookie_name = @session_name + ".encrypted"
        
        if secret.nil? or secret.empty?
                raise ArgumentError, "invalid session secret: #{secret.inspect}"
        end
        
        # This generates a 32-byte key suitable for aes.
        @key = Digest::SHA2.digest(secret)
        
        @expires_after = expires_after
        @update_timeout = update_timeout
        
        @cookie_defaults = {
                domain: nil,
                path: "/",
                
                # The SameSite attribute controls when the cookie is sent to the server, from 3rd parties (None), from requests with external referrers (Lax) or from within the site itself (Strict).
                same_site: same_site,
                
                # The Secure attribute is meant to keep cookie communication limited to encrypted transmission, directing browsers to use cookies only via secure/encrypted connections. However, if a web server sets a cookie with a secure attribute from a non-secure connection, the cookie can still be intercepted when it is sent to the user by man-in-the-middle attacks. Therefore, for maximum security, cookies with the Secure attribute should only be set over a secure connection.
                secure: secure,
                
                # The HttpOnly attribute directs browsers not to expose cookies through channels other than HTTP (and HTTPS) requests. This means that the cookie cannot be accessed via client-side scripting languages (notably JavaScript), and therefore cannot be stolen easily via cross-site scripting (a pervasive attack technique).
                http_only: true,
        }.merge(options)
        
        @serialization = Serialization.new
        @maximum_size = maximum_size
end

Public Instance Methods

call(env) click to toggle source
# File lib/utopia/session.rb, line 109
def call(env)
        session_hash = prepare_session(env)

        status, headers, body = @app.call(env)

        update_session(env, session_hash, headers)

        return [status, headers, body]
end
freeze() click to toggle source
Calls superclass method
# File lib/utopia/session.rb, line 97
def freeze
        return self if frozen?
        
        @cookie_name.freeze
        @key.freeze
        @expires_after.freeze
        @update_timeout.freeze
        @cookie_defaults.freeze
        
        super
end

Protected Instance Methods

build_initial_session(request) click to toggle source

Constructs a valid session for the given request. These fields must match as per the checks performed in `valid_session?`:

# File lib/utopia/session.rb, line 140
def build_initial_session(request)
        {
                user_agent: request.user_agent,
                created_at: Time.now.utc,
                updated_at: Time.now.utc,
        }
end
commit(value, updated_at, headers) click to toggle source
# File lib/utopia/session.rb, line 190
def commit(value, updated_at, headers)
        cookie = {
                value: value,
                expires: expires(updated_at)
        }.merge(@cookie_defaults)
        
        Rack::Utils.set_cookie_header!(headers, @cookie_name, cookie)
end
decrypt(data) click to toggle source
# File lib/utopia/session.rb, line 213
def decrypt(data)
        if @maximum_size and data.bytesize > @maximum_size
                raise PayloadError, "Session payload size #{data.bytesize}bytes exceeds maximum allowed size #{@maximum_size}bytes!"
        end
        
        iv, e = data.unpack("m16m*")
        
        c = OpenSSL::Cipher.new(CIPHER_ALGORITHM)
        c.decrypt
        
        c.key = @key
        c.iv = iv
        
        d = c.update(e)
        d << c.final
        
        return @serialization.load(d)
end
encrypt(hash) click to toggle source
# File lib/utopia/session.rb, line 199
def encrypt(hash)
        c = OpenSSL::Cipher.new(CIPHER_ALGORITHM)
        c.encrypt
        
        # your pass is what is used to encrypt/decrypt
        c.key = @key
        c.iv = iv = c.random_iv
        
        e = c.update(@serialization.dump(hash))
        e << c.final
        
        return [iv, e].pack("m16m*")
end
expires(updated_at=Time.now.utc) click to toggle source
# File lib/utopia/session.rb, line 184
def expires(updated_at=Time.now.utc)
        if @expires_after
                return updated_at + @expires_after
        end
end
load_session_values(env) click to toggle source

Load session from user supplied cookie. If the data is invalid or otherwise fails validation, `build_iniital_session` is invoked. @return hash of values.

# File lib/utopia/session.rb, line 150
def load_session_values(env)
        request = Rack::Request.new(env)
        
        # Decrypt the data from the user if possible:
        if data = request.cookies[@cookie_name]
                begin
                        if values = decrypt(data)
                                validate_session!(request, values)
                                
                                return values
                        end
                rescue => error
                        request.logger&.error(error)
                end
        end
        
        # If we couldn't create a session
        return build_initial_session(request)
end
prepare_session(env) click to toggle source
# File lib/utopia/session.rb, line 121
def prepare_session(env)
        env[RACK_SESSION] = LazyHash.new do
                self.load_session_values(env)
        end
end
update_session(env, session_hash, headers) click to toggle source
# File lib/utopia/session.rb, line 127
def update_session(env, session_hash, headers)
        if session_hash.needs_update?(@update_timeout)
                values = session_hash.values
                
                values[:updated_at] = Time.now.utc
                
                data = encrypt(session_hash.values)
                
                commit(data, values[:updated_at], headers)
        end
end
validate_session!(request, values) click to toggle source
# File lib/utopia/session.rb, line 170
def validate_session!(request, values)
        if values[:user_agent] != request.user_agent
                raise PayloadError, "Invalid session because supplied user agent #{request.user_agent.inspect} does not match session user agent #{values[:user_agent].inspect}!"
        end

        if expires_at = expires(values[:updated_at])
                if expires_at < Time.now.utc
                        raise PayloadError, "Expired session cookie, user agent submitted a cookie that should have expired at #{expires_at}."
                end
        end
        
        return true
end