lua-resty-session

# lua-resty-session

**lua-resty-session** is a secure, and flexible session library for OpenResty.

## TL;DR;

- Sessions are immutable (each save generates a new session), and lockless.
- Session data is AES-256-GCM encrypted with a key derived using HKDF-SHA256
  (on FIPS-mode it uses PBKDF2 with SHA-256 instead.
- Session has a fixed size header that is protected with HMAC-SHA256 MAC with
  a key derived using HKDF-SHA256 (on FIPS-mode it uses PBKDF2 with SHA-256 instead).
- Session data can be stored in a stateless cookie or in various backend storages.
- A single session cookie can maintain multiple sessions across different audiences.

*Note:* Version 4.0.0 was a rewrite of this library with a lot of lessons learned
during the years. If you still use older version, please refer
[old documentation](https://github.com/bungle/lua-resty-session/tree/v3.10).


## Status

This library is considered production ready.


## Synopsis

```nginx
worker_processes  1;

events {
  worker_connections 1024;
}

http {
  init_by_lua_block {
    require "resty.session".init({
      remember = true,
      audience = "demo",
      secret   = "RaJKp8UQW1",
      storage  = "cookie",
    })
  }

  server {
    listen       8080;
    server_name  localhost;
    default_type text/html;

    location / {
      content_by_lua_block {
        ngx.say([[
          <html>
          <body>
            <a href=/start>Start the test</a>
          </body>
          </html>
        ]])
      }
    }

    location /start {
      content_by_lua_block {
        local session = require "resty.session".new()
        session:set_subject("OpenResty Fan")
        session:set("quote", "The quick brown fox jumps over the lazy dog")
        local ok, err = session:save()

        ngx.say(string.format([[
          <html>
          <body>
            <p>Session started (%s)</p>
            <p><a href=/started>Check if it really was</a></p>
          </body>
          </html>
        ]], err or "no error"))
      }
    }

    location /started {
      content_by_lua_block {
        local session, err = require "resty.session".start()

        ngx.say(string.format([[
          <html>
          <body>
            <p>Session was started by %s (%s)</p>
            <p><blockquote>%s</blockquote></p>
            <p><a href=/modify>Modify the session</a></p>
          </body>
          </html>
        ]],
          session:get_subject() or "Anonymous",
          err or "no error",
          session:get("quote") or "no quote"
        ))
      }
    }

    location /modify {
      content_by_lua_block {
        local session, err = require "resty.session".start()
        session:set_subject("Lua Fan")
        session:set("quote", "Lorem ipsum dolor sit amet")
        local _, err_save = session:save()

        ngx.say(string.format([[
          <html>
          <body>
            <p>Session was modified (%s)</p>
            <p><a href=/modified>Check if it is modified</a></p>
          </body>