Module resty.session.utils

Common utilities for session library and storage backends

Functions

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, plaintext, 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

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:

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:

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:

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:

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, plaintext, aad, tag)
Decrypt ciphertext using AES-256 in GCM-mode.

Parameters:

  • key string encryption key
  • iv string initialization vector
  • plaintext string plain text
  • aad string additional authenticated data
  • tag string authentication tag

Returns:

  1. string or nil ciphertext
  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:

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:

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:

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 2023-08-16 18:11:28