suk

README

SUK - Single-use Keys

What if, instead of storing user information on the client side in a JWT token, you used a token containing a randomized key that holds client information on the server side? This session ID would be valid only for a specified duration and would expire immediately after use. This approach enhances security and minimizes the risk of unauthorized access.

This was intended to be used for web app authentication with HTTP cookies, but other applications may find it useful as well.

Need authentication? ───────────────────────────────┐
├── Yes                                             │
│   └── Is the user key valid?                      │
│       ├── Yes                                     │
│       │   └── Generate new one/Invalidate old one │ 
│       │       └── Continue execution normally ────┘
│       └── No
│           └── Authentication error
└── No
    └── Well, ok then.

Getting Started

Getting SUK

go get -u github.com/ed-henrique/suk

Running SUK

package main

import (
    "github.com/ed-henrique/suk"
)

func main() {
    resource := "important stuff here!"

    // Creates new session storage
    ss, _ := suk.New(suk.WithAutoClearExpiredKeys())

    // Removes session storage
    defer suk.Destroy(ss)

    // Sets resource to a randomly generated key
    key, _ := ss.Set(resource)

    // Gets the resource, invalidating the previous key
    resource, newKey, _ := ss.Get(key)

    // Removes both the key and the resource
    ss.Remove(newKey)
}

Examples

• Sample Server with Cookie Authentication

Documentation

Please refer to this.

Decisions

• Multiple cookies can connect to a single session, but they are not aware of each other
• If all cookies to a session are used up, the reference to the session is lost

Roadmap

• Extensive testing
• Make implementation concurrent-safe
• Use better algorithm for random and strong keys (refer to this)

Documentation

Overview

Package suk offers easy server-side session management using single-use keys.

You may use an in-memory map (default) or a Redis client to hold your sessions. Do note that, when using an in-memory map, the session data is lost as soon as the program stops.

Index

• Variables
• func Destroy(ss *SessionStorage)
• type Option
  • func WithAutoClearExpiredKeys() Option
  • func WithCustomRandomKeyGenerator(rkg func(uint64) (string, error)) Option
  • func WithKeyDuration(duration time.Duration) Option
  • func WithKeyLength(keyLength uint64) Option
  • func WithRedis(client *redis.Client, ctx context.Context) Option
• type SessionStorage
  • func New(opts ...Option) (*SessionStorage, error)
  • func (ss *SessionStorage) ClearExpired() error
  • func (ss *SessionStorage) Get(key string) (any, string, error)
  • func (ss *SessionStorage) Remove(key string) error
  • func (ss *SessionStorage) Set(session any) (string, error)

Variables

var (
	ErrNilRedisClient        = errors.New("The given Redis client is nil.")
	ErrRedisClientAlreadySet = errors.New("A Redis client was already registered for this session storage.")

	ErrZeroKeyLength = errors.New("The given key length must be at least 1.")

	ErrNonPositiveKeyDuration = errors.New("The given key duration must be positive.")

	ErrNilRandomKeyGenerator = errors.New("The given random key generator function is nil.")

	ErrCustomKeyLengthAlreadySet      = errors.New("A custom key length was already registered for this session storage.")
	ErrCustomKeyDurationAlreadySet    = errors.New("A custom key duration was already registered for this session storage.")
	ErrAutoClearExpiredKeysAlreadySet = errors.New("Auto clear for expired keys was already set for this session storage.")
)

var (
	ErrKeyWasExpired = errors.New("The given key has expired.")
	ErrNoKeyFound    = errors.New("No value was found with the given key.")
	ErrNilSession    = errors.New("The session passed can't be nil.")
)

Functions

func Destroy

func Destroy(ss *SessionStorage)

Destroy cleans up and removes a session storage.

Types

type Option

type Option interface {
	// contains filtered or unexported methods
}

func WithAutoClearExpiredKeys

func WithAutoClearExpiredKeys() Option

WithAutoClearExpiredKeys automatically clears expired keys at intervals based on the set key expiration time. By default, the clearing process occurs every 10 minutes, but this can be adjusted by setting a different key expiration time using WithTokenDuration.

func WithCustomRandomKeyGenerator

func WithCustomRandomKeyGenerator(rkg func(uint64) (string, error)) Option

WithCustomRandomKeyGenerator sets a custom function to generate the keys.

func WithKeyDuration

func WithKeyDuration(duration time.Duration) Option

WithKeyDuration sets a custom duration for generated keys. The default is 10 minutes.

func WithKeyLength

func WithKeyLength(keyLength uint64) Option

WithKeyLength sets a custom key length for generated keys. The default is 32, which gives an entropy of 192 for each key, which should be fine for most applications.

Be aware that low length keys are susceptible to guessing, as the entropy level goes down. To calculate entropy, do keyLength * log2(65).

func WithRedis

func WithRedis(client *redis.Client, ctx context.Context) Option

WithRedis uses the given Redis client to store the sessions, instead of using an in-memory storage. It also may receive a custom context to work on, but by default it uses context.Background().

type SessionStorage

type SessionStorage struct {
	// contains filtered or unexported fields
}

func New

func New(opts ...Option) (*SessionStorage, error)

New creates a new session storage.

func (*SessionStorage) ClearExpired

func (ss *SessionStorage) ClearExpired() error

ClearExpired removes all expired keys. For Redis, this function is a no-op as Redis handles expiration automatically. To enable similar behavior for the default syncMap, start the SessionStorage with the WithAutoClearExpiredKeys option.

func (*SessionStorage) Get

func (ss *SessionStorage) Get(key string) (any, string, error)

Get retrieves the session and generates a new key for it.

func (*SessionStorage) Remove

func (ss *SessionStorage) Remove(key string) error

Remove deletes the specified key and its associated value.

func (*SessionStorage) Set

func (ss *SessionStorage) Set(session any) (string, error)

Set assigns the session and returns a key for it.