# Module `resty.session.utils`

Common utilities for session library and storage backends

## Functions

table_new () | Creates a pre-sized table, just like the C API equivalent lua_createtable().
table_is_empty () | Returns `true` when the given Lua table contains neither non-nil array elements nor non-nil key-value pairs, or false otherwise.
is_fips_mode () | Returns whether OpenSSL is in FIPS-mode.
bpack (size, value) | Binary pack unsigned integer.
bunpack (size, value) | Binary unpack unsigned integer.
trim (value) | Trim whitespace from the start and from the end of string.
encode_json (value) | JSON encode value.
decode_json (value) | JSON decode value.
encode_base64url (value) | Base64 URL encode value.
decode_base64url (value) | Base64 URL decode value
base64_size (size) | Base64 size from original size (without padding).
deflate (data) | Compress the data with deflate algorithm.
inflate (data) | Decompress the data compressed with deflate algorithm.
rand_bytes (length) | Generate crypto random bytes.
sha256 (value) | Calculates SHA-256 hash of the value.
derive_hkdf_sha256 (ikm, nonce, usage, size) | Derive a new key using HKDF with SHA-256.
derive_pbkdf2_hmac_sha256 (pass, salt, usage, size, iterations) | Derive a new key using PBKDF2 with SHA-256.
derive_aes_gcm_256_key_and_iv (ikm, nonce[, safety]) | Derive a new AES-256 GCM-mode key and initialization vector.
derive_hmac_sha256_key (ikm, nonce) | Derive HMAC SHA-256 key for message authentication using HDKF with SHA-256, except on FIPS-mode it uses PBKDF2 with SHA-256 (single iteration).
encrypt_aes_256_gcm (key, iv, plaintext, aad) | Encrypt plain text using AES-256 in GCM-mode.
decrypt_aes_256_gcm (key, iv, ciphertext, aad, tag) | Decrypt ciphertext using AES-256 in GCM-mode.
hmac_sha256 (key, value) | Calculate message authentication code with HMAC with SHA-256.
load_storage (storage[, configuration]) | Loads session storage and creates a new instance using session configuration.
errmsg ([err], msg, ...) | Helper to format error messages.
get_name (storage, name, key, subject) | Helper to create a delimited key.
set_flag (flags, flag) | Helper to turn on a flag.
unset_flag (flags, flag) | Helper to turn off a flag.
has_flag (flags, flag) | Helper to check if flag is enabled.
meta_get_value (key, exp) | Helper to get the value used to store metadata for a certain aud and sub Empty exp means the session id has been invalidated
meta_get_next (val, index) | Function to extract the next key and exp from a serialized metadata list, starting from index
meta_get_latest (sessions) | Function to filter out the latest valid key:exp from a serialized list, used to store session metadata

## Functions

table_new ()
  Creates a pre-sized table, just like the C API equivalent lua_createtable().

  ### Returns:

  table a pre-sized table

  ### Usage:

      local tbl = require("resty.session.utils").table_new(100, 0)

table_is_empty ()
  Returns `true` when the given Lua table contains neither non-nil array elements nor non-nil key-value pairs, or false otherwise.

  ### Returns:

  boolean `true` if table is empty, otherwise `false`

  ### Usage:

      local empty = require("resty.session.utils").table_is_empty({})

is_fips_mode ()
  Returns whether OpenSSL is in FIPS-mode.

  ### Returns:

  boolean `true` if OpenSSL is in FIPS-mode, otherwise `false`

  ### Usage:

      local is_fips = require("resty.session.utils").is_fips_mode()

bpack (size, value)

  Binary pack unsigned integer.

  Returns binary packed version of an integer in little endian unsigned format.

  Size can be:

  - `1`, pack input as a little endian unsigned char (`<C`)
  - `2`, pack input as a little endian unsigned short (`<S`)
  - `3`, pack input as a little endian unsigned integer (truncated) (`<I`)
  - `4`, pack input as a little endian unsigned integer (`<I`)
  - `5`, pack input as a little endian unsigned long (truncated) (`<L`)
  - `6`, pack input as a little endian unsigned long (truncated) (`<L`)
  - `7`, pack input as a little endian unsigned long (truncated) (`<L`)
  - `8`, pack input as a little endian unsigned long (`<L`)

  ### Parameters:

  - size number size of binary packed output
  - value number value to binary pack

  ### Returns:

  string binary packed value

  ### Usage:

      local packed_128 = require("resty.session.utils").bpack(1, 128)
      local packed_now = require("resty.session.utils").bpack(8, ngx.time())

bunpack (size, value)

  Binary unpack unsigned integer.

  Returns number from a little endian unsigned binary packed format.

  Size can be:

  - `1`, unpack input from little endian unsigned char (`<C`)
  - `2`, unpack input from little endian unsigned short (`<S`)
  - `3`, unpack input from little endian unsigned integer (truncated) (`<I`)
  - `4`, unpack input from little endian unsigned integer (`<I`)
  - `5`, unpack input from little endian unsigned integer (truncated) (`<L`)
  - `6`, unpack input from little endian unsigned integer (truncated) (`<L`)
  - `7`, unpack input from little endian unsigned integer (truncated) (`<L`)
  - `8`, unpack input from little endian unsigned long (`<L`)

  ### Parameters:

  - size number size of binary packed output
  - value number value to binary pack

  ### Returns:

  number binary unpacked value

  ### Usage:

      local utils = require "resty.session.utils"
      local value = 128
      local packed_value = utils.bpack(1, value)
      local unpacked_value = utils.bunpack(1, packed_value)
      print(value == unpacked_value) -- true

trim (value)

  Trim whitespace from the start and from the end of string.

  Characters that are trimmed:

  - space `" "`
  - tab `"\t"`
  - carriage return `"\r"`
  - line feed `"\n"`
  - vertical tab `"\v"`
  - form feed `"\f"`

  ### Parameters:

  - value string string to trim

  ### Returns:

  string a whitespace trimmed string

  ### Usage:

      local trimmed = require("resty.session.utils").trim("  hello world  ")

encode_json (value)
  JSON encode value.

  ### Parameters:

  - value any value to json encode

  ### Returns:

  string json encoded value

  ### Usage:

      local json = require("resty.session.utils").encode_json({ hello = "world" })

decode_json (value)
  JSON decode value.

  ### Parameters:

  - value string string to json decode

  ### Returns:

  any json decoded value

  ### Usage:

      local tbl = require("resty.session.utils").decode_json('{ "hello": "world" }')

encode_base64url (value)
  Base64 URL encode value.

  ### Parameters:

  - value string string to base64 url encode

  ### Returns:

  string base64 url encoded value

  ### Usage:

      local encoded = require("resty.session.utils").encode_base64url("test")

decode_base64url (value)
  Base64 URL decode value

  ### Parameters:

  - value string string to base64 url decode

  ### Returns:

  string base64 url decoded value

  ### Usage:

      local utils = require "resty.session.utils"
      local encoded = utils.encode_base64url("test")
      local decoded = utils.decode_base64url(encoded)

base64_size (size)
  Base64 size from original size (without padding).

  ### Parameters:

  - size number original size

  ### Returns:

  number base64 url encoded size without padding

  ### Usage:

      local test = "test"
      local b64len = require("resty.session.utils").base64_size(#test)

deflate (data)
  Compress the data with deflate algorithm.

  ### Parameters:

  - data string data to deflate

  ### Returns:

  string deflated data

  ### Usage:

      local test = "test"
      local deflated = require("resty.session.utils").deflate(("a"):rep(100))

inflate (data)
  Decompress the data compressed with deflate algorithm.

  ### Parameters:

  - data string data to inflate

  ### Returns:

  string inflated data

  ### Usage:

      local utils = require "resty.session.utils"
      local deflated = utils.deflate(("a"):rep(100))
      local inflated = utils.inflate(deflated)

rand_bytes (length)
  Generate crypto random bytes.

  ### Parameters:

  - length number how many bytes of random data to generate

  ### Returns:

  1. string or nil random bytes
  2. string or nil error message

  ### Usage:

      local bytes = require("resty.session.utils").rand_bytes(32)

sha256 (value)
  Calculates SHA-256 hash of the value.

  ### Parameters:

  - value string value from which to calculate hash

  ### Returns:

  1. string or nil sha-256 hash (32 bytes)
  2. string or nil error message

  ### Usage:

      local hash, err = require("resty.session.utils").sha256("hello world")

derive_hkdf_sha256 (ikm, nonce, usage, size)
  Derive a new key using HKDF with SHA-256.

  ### Parameters:

  - ikm string initial key material
  - nonce string nonce
  - usage string e.g. `"encryption"` or `"authentication"`
  - size number how many bytes to return

  ### Returns:

  1. string or nil key material
  2. string or nil error message

  ### Usage:

      local utils = require "resty.session.utils"
      local ikm = utils.rand_bytes(32)
      local nonce = utils.rand_bytes(32)
      local key, err = utils.derive_hkdf_sha256(ikm, nonce, "encryption", 32)

derive_pbkdf2_hmac_sha256 (pass, salt, usage, size, iterations)
  Derive a new key using PBKDF2 with SHA-256.

  ### Parameters:

  - pass string password
  - salt string salt
  - usage string e.g. `"encryption"` or `"authentication"`
  - size number how many bytes to return
  - iterations number how many iterations to run, e.g. `10000`

  ### Returns:

  1. string or nil key material
  2. string or nil error message

  ### Usage:

      local utils = require "resty.session.utils"
      local pass = "my-super-secret-password"
      local salt = utils.rand_bytes(32)
      local key, err = utils.derive_pbkdf2_hmac_sha256(pass, salt, "encryption", 32, 10000)

derive_aes_gcm_256_key_and_iv (ikm, nonce[, safety])
  Derive a new AES-256 GCM-mode key and initialization vector.

  Safety can be: * `nil` or `"None"`: key and iv will be derived using HKDF with SHA-256, except on FIPS-mode uses PBKDF2 with SHA-256 (single iteration) * `Low`: key and iv will be derived using PBKDF2 with SHA-256 (1.000 iterations) * `Medium`: key and iv will be derived using PBKDF2 with SHA-256 (10.000 iterations) * `High`: key and iv will be derived using PBKDF2 with SHA-256 (100.000 iterations) * `Very High`: key and iv will be derived using PBKDF2 with SHA-256 (1.000.000 iterations)

  ### Parameters:

  - ikm string initial key material
  - nonce string nonce
  - safety string safety of key generation (optional)

  ### Returns:

  1. string or nil key
  2. string or nil error message
  3. string or nil initialization vector

  ### Usage:

      local utils = require "resty.session.utils"
      local ikm = utils.rand_bytes(32)
      local nonce = utils.rand_bytes(32)
      local key, err, iv = utils.derive_aes_gcm_256_key_and_iv(ikm, nonce, "Medium")

derive_hmac_sha256_key (ikm, nonce)
  Derive HMAC SHA-256 key for message authentication using HDKF with SHA-256, except on FIPS-mode it uses PBKDF2 with SHA-256 (single iteration).

  ### Parameters:

  - ikm string initial key material
  - nonce string nonce

  ### Returns:

  1. string or nil key
  2. string or nil error message

  ### Usage:

      local utils = require "resty.session.utils"
      local ikm = utils.rand_bytes(32)
      local nonce = utils.rand_bytes(32)
      local key, err = utils.derive_hmac_sha256_key(ikm, nonce)

encrypt_aes_256_gcm (key, iv, plaintext, aad)
  Encrypt plain text using AES-256 in GCM-mode.

  ### Parameters:

  - key string encryption key
  - iv string initialization vector
  - plaintext string plain text
  - aad string additional authenticated data

  ### Returns:

  1. string or nil ciphertext
  2. string or nil error message
  3. string or nil authentication tag

  ### Usage:

      local utils = require "resty.session.utils"
      local ikm = utils.rand_bytes(32)
      local nonce = utils.rand_bytes(32)
      local key, err, iv = utils.derive_aes_gcm_256_key_and_iv(ikm, nonce)
      local enc, err, tag = utils.encrypt_aes_256_gcm(key, iv, "hello", "john@doe.com")

decrypt_aes_256_gcm (key, iv, ciphertext, aad, tag)
  Decrypt ciphertext using AES-256 in GCM-mode.

  ### Parameters:

  - key string encryption key
  - iv string initialization vector
  - ciphertext string plain text
  - aad string additional authenticated data
  - tag string authentication tag

  ### Returns:

  1. string or nil plaintext
  2. string or nil error message

  ### Usage:

      local utils = require "resty.session.utils"
      local ikm = utils.rand_bytes(32)
      local nonce = utils.rand_bytes(32)
      local key, err, iv = utils.derive_aes_gcm_256_key_and_iv(ikm, nonce)
      local enc, err, tag = utils.encrypt_aes_256_gcm(key, iv, "hello", "john@doe.com")
      local out, err = utils.decrypt_aes_256_gcm(key, iv, ciphertext, "john@doe.com", tag)

hmac_sha256 (key, value)
  Calculate message authentication code with HMAC with SHA-256.

  ### Parameters:

  - key string key
  - value string value

  ### Returns:

  1. string or nil message authentication code (32 bytes)
  2. string or nil error message

  ### Usage:

      local utils = require "resty.session.utils"
      local ikm = utils.rand_bytes(32)
      local nonce = utils.rand_bytes(32)
      local key, err = utils.derive_hmac_sha256_key(ikm, nonce)
      local mac, err = utils.hmac_sha256(key, "hello")

load_storage (storage[, configuration])
  Loads session storage and creates a new instance using session configuration.

  ### Parameters:

  - storage string name of the storage to load
  - configuration table session configuration (optional)

  ### Returns:

  1. table or nil instance of session storage
  2. string or nil error message

  ### Usage:

      local postgres = require("resty.session.utils").load_storage("postgres", {
        postgres = {
          host = "127.0.0.1",
        }
      })

errmsg ([err], msg, ...)
  Helper to format error messages.

  ### Parameters:

  - err string or nil a possible error coming from underlying library (optional)
  - msg string or nil error message
  - ... any arguments for formatting the msg

  ### Returns:

  string formatted error message

  ### Usage:

      local utils = require "resty.session.utils"
      local test = "aaaa"
      local data, err = utils.deflate(test)
      if not data then
        print(utils.errmsg(err, "unable to deflate data '%s'", test)
      end

get_name (storage, name, key, subject)
  Helper to create a delimited key.

  ### Parameters:

  - storage table a storage implementation
  - name string name
  - key string key
  - subject string subject

  ### Returns:

  string formatted and delimited name
set_flag (flags, flag)
  Helper to turn on a flag.

  ### Parameters:

  - flags number flags on which the flag is applied
  - flag number flag that is applied

  ### Returns:

  number flags with the flag applied

  ### Usage:

      local flags = 0x0000
      local FLAG_DOG = 0x001
      flags = utils.set_flag(flags, FLAG_DOG)

unset_flag (flags, flag)
  Helper to turn off a flag.

  ### Parameters:

  - flags number flags on which the flag is removed
  - flag number flag that is removed

  ### Returns:

  number flags with the flag removed

  ### Usage:

      local options = 0x0000
      local FLAG_DOG = 0x001
      flags = utils.set_flag(options, FLAG_DOG)
      flags = utils.unset_flag(options, FLAG_DOG)

has_flag (flags, flag)
  Helper to check if flag is enabled.

  ### Parameters:

  - flags number flags on which the flag is checked
  - flag number flag that is checked

  ### Returns:

  boolean true if flag has is present, otherwise false

  ### Usage:

      local flags = 0x0000
      local FLAG_DOG = 0x001
      local FLAG_BONE = 0x010
      flags = utils.set_flag(flags, FLAG_DOG)
      flags = utils.set_flag(flags, FLAG_BONE)
      print(utils.has_flag(flags, FLAG_BONE)

meta_get_value (key, exp)
  Helper to get the value used to store metadata for a certain aud and sub Empty exp means the session id has been invalidated

  ### Parameters:

  - key string storage key
  - exp string expiration

  ### Returns:

  string the value to store in the metadata collection
meta_get_next (val, index)
  Function to extract the next key and exp from a serialized metadata list, starting from index

  ### Parameters:

  - val string list of key:exp;
  - index number start index

  ### Returns:

  1. key string session id
  2. err string error
  3. exp number expiration
  4. index number|nil index of the cursor
meta_get_latest (sessions)
  Function to filter out the latest valid key:exp from a serialized list, used to store session metadata

  ### Parameters:

  - sessions string list of key:exp;

  ### Returns:

  table valid sessions and their exp

generated by LDoc 1.5.0 Last updated 2025-07-29 12:02:00