kong.vault

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

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

table|nil: a table containing each component of the reference, or nil on error
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

string|nil: resolved value of the reference
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

string|nil: return value of the callback function
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}",
  }
})