kong.vault

This module can be used to resolve, parse, and verify vault references.

get_subfield(value, key)

This function extracts a subfield from a JSON object. It first decodes the JSON string into a Lua table, then checks for the presence and type of a specific key.

Parameters

  • value : The JSON string to be parsed and decoded.
  • key : The specific subfield to be searched for within the JSON object.

Returns

  • On success, returns the value associated with the specified key in the JSON object. If the key does not exist or its value is not a string, returns nil along with an error message. If the input value cannot be parsed as a JSON object, also returns nil along with an error message.

adjust_ttl(ttl, vault_config)

This function adjusts the ‘time-to-live’ (TTL) according to the configuration provided in ‘vault_config’. If the TTL is not a number or if it falls outside of the configured minimum or maximum TTL, it will be adjusted accordingly.

Parameters

  • ttl : The initial time-to-live value.
  • vault_config : The configuration table for the vault, which may contain ‘ttl’, ‘min_ttl’, and ‘max_ttl’ fields.

Returns

  • Returns the adjusted TTL. If the initial TTL is not a number, it returns the ‘ttl’ field from the ‘vault_config’ table or 0 if it doesn’t exist. If the initial TTL is greater than ‘max_ttl’ from ‘vault_config’, it returns ‘max_ttl’. If the initial TTL is less than ‘min_ttl’ from ‘vault_config’, it returns ‘min_ttl’. Otherwise, it returns the original TTL.

get_vault(prefix)

This function retrieves a vault by its prefix. It either fetches the vault from a cache or directly accesses it. The vault is expected to be found in a database (db) or cache. If not found, an error message is returned.

Parameters

  • prefix : The unique identifier of the vault to be retrieved.

Returns

  • Returns the vault if it’s found. If the vault is not found, it returns nil along with an error message.

get_vault_strategy_and_schema_during_init(name)

Fetches the strategy and schema for a given vault during initialization.

This function checks if the vault exists in VAULT_NAMES, fetches the associated strategy and schema from the STRATEGIES and SCHEMAS tables, respectively. If the strategy or schema isn’t found in the tables, it attempts to fetch them from the application’s database or by requiring them from a module.

The fetched strategy and schema are then stored back into the STRATEGIES and SCHEMAS tables for later use. If the init method exists in the strategy, it’s also executed.

Parameters

  • name : string The name of the vault to fetch the strategy and schema for.

Returns

  1. strategy: The fetched or required strategy for the given vault.

  2. schema: The fetched or required schema for the given vault.

  3. string|nil: An error message, if an error occurred while fetching or requiring the strategy or schema.

parse_and_resolve_reference(reference)

Function parse_and_resolve_reference processes a reference to retrieve configuration settings, a strategy to be used, and the hash of the reference. The function first parses the reference. Then, it gets the strategy, the schema, and the base configuration settings for the vault based on the parsed reference. It checks the license type if required by the strategy. Finally, it gets the configuration and the hash of the reference.

Parameters

  • reference : The reference to be parsed and resolved.

Returns

  • The configuration, a nil value (as a placeholder for an error that did not occur), the parsed reference, the strategy to be used, and the hash of the reference. If an error occurs, it returns nil and an error message.

Usage

  1. local config, _, parsed_reference, strategy, hash = parse_and_resolve_reference(reference)

get_from_vault(strategy, config, parsed_reference, cache_key, reference)

Function get_from_vault retrieves a value from the vault using the provided strategy. The function first retrieves a value from the vault and its ttl (time-to-live). It then adjusts the ttl within configured bounds, stores the value in the SHDICT cache with a ttl that includes a resurrection time, and stores the value in the LRU cache with the adjusted ttl.

Parameters

  • strategy : The strategy to be used to retrieve the value from the vault.
  • config : The configuration settings to be used.
  • parsed_reference : The parsed reference key to lookup in the vault.
  • cache_key : The key to be used when storing the value in the cache.
  • reference : The original reference key.

Returns

  • The retrieved value from the vault. If an error occurs, it returns nil and an error message.

Usage

  1. local value, err = get_from_vault(strategy, config, parsed_reference, cache_key, reference)

renew_from_vault(reference)

Function renew_from_vault attempts to retrieve a value from the vault. It first parses and resolves the reference, then uses the resulting strategy, config, parsed_reference, and cache_key to attempt to get the value from the vault.

Parameters

  • reference : The reference key to lookup in the vault.

Returns

  • The retrieved value from the vault corresponding to the provided reference. If the value is not found or if an error occurs, it returns nil and an error message.

Usage

  1. local value, err = renew_from_vault(reference)

get(reference, cache_only)

Function get retrieves a value from local (LRU) or shared dictionary (SHDICT) cache. If the value is not found in these caches and cache_only is not set, it attempts to retrieve the value from a vault.

Parameters

  • reference : The reference key to lookup in the cache and potentially the vault.
  • cache_only : Optional boolean flag. If set to true, the function will not attempt to retrieve the value from the vault if it’s not found in the caches.

Returns

  • The retrieved value corresponding to the provided reference. If the value is not found, it returns nil and an error message.

Usage

  1. local value, err = get(reference, cache_only)

get_from_cache(references)

Function get_from_cache retrieves values from a cache.

This function uses the provided references to fetch values from a cache. The fetching process will return cached values if they exist.

Parameters

  • references : A list or table of reference keys. Each reference key corresponds to a value in the cache.

Returns

  • The retrieved values corresponding to the provided references. If a value does not exist in the cache for a particular reference, it is not clear from the given code what will be returned.

Usage

  1. local values = get_from_cache(references)

update(config)

Function update recursively updates a configuration table.

This function updates a configuration table by replacing reference fields with values fetched from a cache. The references are specified in a $refs field, which should be a table mapping from field names to reference keys.

If a reference cannot be fetched from the cache, the corresponding field is set to an empty string and an error is logged.

Parameters

  • config : A table representing the configuration to update. If config is not a table, the function immediately returns it without any modifications.

Returns

  • The updated configuration table. If the $refs field is not a table or is empty, the function returns config as is.

Usage

  1. local updated_config = update(config)

try(callback, options)

Function try attempts to execute a provided callback function with the provided options. If the callback function fails, the try function will attempt to resolve references and update the values in the options table before re-attempting the callback function. NOTE: This function currently only detects changes by doing a shallow comparison. As a result, it might trigger more retries than necessary - when a config option has a table value and it seems “changed” even if the “new value” is a new table with the same keys and values inside.

Parameters

  • callback : The callback function to execute. This function should take an options table as its argument.
  • options : The options table to provide to the callback function. This table may include a “$refs” field which is a table mapping reference names to their values.

Returns

  • Returns the result of the callback function if it succeeds, otherwise it returns nil and an error message.

rotate_secrets()

Function rotate_secrets rotates the secrets in the shared dictionary cache (SHDICT). It iterates over all keys in the SHDICT and, if a key corresponds to a reference and the ttl of the key is less than or equal to the resurrection period, it refreshes the value associated with the reference.

Returns

  • Returns true after it has finished iterating over all keys in the SHDICT.

Usage

  1. local success = rotate_secrets()

kong.vault.flush()

Flushes vault config and the references LRU cache.

Usage

  1. kong.vault.flush()

kong.vault.is_reference(reference)

Checks if the passed in reference looks like a reference. Valid references start with {vault:// and end with }.

If you need more thorough validation, use kong.vault.parse_reference.

Parameters

  • reference (string): reference to check

Returns

  • boolean: true is the passed in reference looks like a reference, otherwise false

Usage

  1. kong.vault.is_reference("{vault://env/key}") -- true
  2. kong.vault.is_reference("not a reference")   -- false

kong.vault.parse_reference(reference)

Parses and decodes the passed in reference and returns a table containing its components.

Given a following resource:

  1.  "{vault://env/cert/key?prefix=SSL_#1}"

This function will return following table:

  1.  {
  2.    name     = "env",  -- name of the Vault entity or Vault strategy
  3.    resource = "cert", -- resource where secret is stored
  4.    key      = "key",  -- key to lookup if the resource is secret object
  5.    config   = {       -- if there are any config options specified
  6.      prefix = "SSL_"
  7.    },
  8.    version  = 1       -- if the version is specified
  9.  }

Parameters

  • reference (string): reference to parse

Returns

  1. table|nil: a table containing each component of the reference, or nil on error

  2. string|nil: error message on failure, otherwise nil

Usage

  1. local ref, err = kong.vault.parse_reference("{vault://env/cert/key?prefix=SSL_#1}") -- table

kong.vault.get(reference)

Resolves the passed in reference and returns the value of it.

Parameters

  • reference (string): reference to resolve

Returns

  1. string|nil: resolved value of the reference

  2. string|nil: error message on failure, otherwise nil

Usage

  1. local value, err = kong.vault.get("{vault://env/cert/key}")

kong.vault.update(options)

Helper function for secret rotation based on TTLs. Currently experimental.

Parameters

  • options (table): options containing secrets and references (this function modifies the input options)

Returns

  • table: options with updated secret values

Usage

  1. local options = kong.vault.update({
  2.   cert = "-----BEGIN CERTIFICATE-----...",
  3.   key = "-----BEGIN RSA PRIVATE KEY-----...",
  4.   cert_alt = "-----BEGIN CERTIFICATE-----...",
  5.   key_alt = "-----BEGIN EC PRIVATE KEY-----...",
  6.   ["$refs"] = {
  7.     cert = "{vault://aws/cert}",
  8.     key = "{vault://aws/key}",
  9.     cert_alt = "{vault://aws/cert-alt}",
  10.     key_alt = "{vault://aws/key-alt}",
  11.   }
  12. })
  14. -- or
  16. local options = {
  17.   cert = "-----BEGIN CERTIFICATE-----...",
  18.   key = "-----BEGIN RSA PRIVATE KEY-----...",
  19.   cert_alt = "-----BEGIN CERTIFICATE-----...",
  20.   key_alt = "-----BEGIN EC PRIVATE KEY-----...",
  21.   ["$refs"] = {
  22.     cert = "{vault://aws/cert}",
  23.     key = "{vault://aws/key}",
  24.     cert_alt = "{vault://aws/cert-alt}",
  25.     key_alt = "{vault://aws/key-alt}",
  26.   }
  27. }
  28. kong.vault.update(options)

kong.vault.try(callback, options)

Helper function for automatic secret rotation. Currently experimental.

Parameters

  • callback (function): callback function
  • options (table): options containing credentials and references

Returns

  1. string|nil: return value of the callback function

  2. string|nil: error message on failure, otherwise nil

Usage

  1. local function connect(options)
  2.   return database_connect(options)
  3. end
  5. local connection, err = kong.vault.try(connect, {
  6.   username = "john",
  7.   password = "doe",
  8.   ["$refs"] = {
  9.     username = "{vault://aws/database-username}",
  10.     password = "{vault://aws/database-password}",
  11.   }
  12. })

invoke_strategy(strategy, config, parsed_reference)

Invokes a provided strategy to fetch a secret. This function invokes a strategy provided to it to retrieve a secret from a resource, with version control. The secret can have multiple values, each stored under a different key. The secret returned by the strategy must be a string containing a JSON object, which can be indexed by the key to get a specific value. If the secret can’t be retrieved or doesn’t have the expected format, appropriate errors are returned.

Parameters

  • strategy : The strategy used to fetch the secret.
  • config : The configuration required by the strategy.
  • parsed_reference : A table containing the resource and version of the secret to be fetched, and optionally, a key to index a specific value.

Returns

  1. Value The value of the secret or subfield if retrieval is successful.

  2. nil If retrieval is successful, the second returned value will be nil.

  3. err A string describing an error if there was one, or ttl (time to live) of the fetched secret.

Usage

  1. local value, _, err = invoke_strategy(strategy, config, parsed_reference)