Skip to content
2023 API Summit Hackathon: Experiment with AI for APIs (August 28 - September 27) Learn More →
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
      Lightweight, fast, and flexible cloud-native API gateway
      Kong Konnect
      Single platform for SaaS end-to-end connectivity
      Kong Mesh
      Enterprise service mesh based on Kuma and Envoy
      decK
      Helps manage Kong’s configuration in a declarative fashion
      Kong Ingress Controller
      Works inside a Kubernetes cluster and configures Kong to proxy traffic
      Insomnia
      Collaborative API development platform
      Kuma
      Open-source distributed control plane with a bundled Envoy Proxy integration
      Docs Contribution Guidelines
      Want to help out, or found an issue in the docs and want to let us know?
  • API Specs
  • Plugin Hub
    • Explore the Plugin Hub
      View all plugins View all plugins View all plugins arrow image
    • Functionality View all View all arrow image
      View all plugins
      Authentication's icon
      Authentication
      Protect your services with an authentication layer
      Security's icon
      Security
      Protect your services with additional security layer
      Traffic Control's icon
      Traffic Control
      Manage, throttle and restrict inbound and outbound API traffic
      Serverless's icon
      Serverless
      Invoke serverless functions in combination with other plugins
      Analytics & Monitoring's icon
      Analytics & Monitoring
      Visualize, inspect and monitor APIs and microservices traffic
      Transformations's icon
      Transformations
      Transform request and responses on the fly on Kong
      Logging's icon
      Logging
      Log request and response data using the best transport for your infrastructure
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
Kong Gateway
3.4.x (latest)
  • Home icon
  • Kong Gateway
  • Plugin Development
  • PDK
  • kong.vault
github-edit-pageEdit this page
report-issueReport an issue
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kong Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 3.4.x (latest)
  • 3.3.x
  • 3.2.x
  • 3.1.x
  • 3.0.x
  • 2.8.x
  • 2.7.x
  • 2.6.x
  • Archive (pre-2.6)
enterprise-switcher-icon Switch to OSS
On this pageOn this page
  • get_subfield(value, key)
  • adjust_ttl(ttl, vault_config)
  • get_vault(prefix)
  • get_vault_strategy_and_schema_during_init(name)
  • parse_and_resolve_reference(reference)
  • get_from_vault(strategy, config, parsed_reference, cache_key, reference)
  • renew_from_vault(reference)
  • get(reference, cache_only)
  • get_from_cache(references)
  • update(config)
  • try(callback, options)
  • rotate_secrets()
  • kong.vault.flush()
  • kong.vault.is_reference(reference)
  • kong.vault.parse_reference(reference)
  • kong.vault.get(reference)
  • kong.vault.update(options)
  • kong.vault.try(callback, options)
  • invoke_strategy(strategy, config, parsed_reference)

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

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

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

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

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

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

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

local success = rotate_secrets()

kong.vault.flush()

Flushes vault config and the references LRU cache.

Usage

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

kong.vault.is_reference("{vault://env/key}") -- true
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:

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

This function will return following table:

 {
   name     = "env",  -- name of the Vault entity or Vault strategy
   resource = "cert", -- resource where secret is stored
   key      = "key",  -- key to lookup if the resource is secret object
   config   = {       -- if there are any config options specified
     prefix = "SSL_"
   },
   version  = 1       -- if the version is specified
 }

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

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

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

local options = kong.vault.update({
  cert = "-----BEGIN CERTIFICATE-----...",
  key = "-----BEGIN RSA PRIVATE KEY-----...",
  cert_alt = "-----BEGIN CERTIFICATE-----...",
  key_alt = "-----BEGIN EC PRIVATE KEY-----...",
  ["$refs"] = {
    cert = "{vault://aws/cert}",
    key = "{vault://aws/key}",
    cert_alt = "{vault://aws/cert-alt}",
    key_alt = "{vault://aws/key-alt}",
  }
})

-- or

local options = {
  cert = "-----BEGIN CERTIFICATE-----...",
  key = "-----BEGIN RSA PRIVATE KEY-----...",
  cert_alt = "-----BEGIN CERTIFICATE-----...",
  key_alt = "-----BEGIN EC PRIVATE KEY-----...",
  ["$refs"] = {
    cert = "{vault://aws/cert}",
    key = "{vault://aws/key}",
    cert_alt = "{vault://aws/cert-alt}",
    key_alt = "{vault://aws/key-alt}",
  }
}
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

local function connect(options)
  return database_connect(options)
end

local connection, err = kong.vault.try(connect, {
  username = "john",
  password = "doe",
  ["$refs"] = {
    username = "{vault://aws/database-username}",
    password = "{vault://aws/database-password}",
  }
})

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

local value, _, err = invoke_strategy(strategy, config, parsed_reference)
Thank you for your feedback.
Was this page useful?
Too much on your plate? close cta icon
More features, less infrastructure with Kong Konnect. 1M requests per month for free.
Try it for Free
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023