vaultlib

README

vaultlib

This work forks Michael Champagne's vaultlib at https://github.com/mch1307/vaultlib

Lightweight, simple Go library for Vault secret reading (http API).

Connect to Vault through app role or token.

Reads kv secret values

Features

• Connect to Vault through app role
• Read Vault secret, kv type (v1 or v2 "versioned")
• Automatically renew token
• Execute any HTTP request on Vault (RawRequest)

Config

Configuration can be done through env variables or programmatically through the Config object The following env variables are supported:

VAULT_ADDR            # Vault server URL (default "http://localhost:8200")
VAULT_CACERT          # Path to CA file
VAULT_TOKEN           # Vault Token
VAULT_ROLEID          # Vault app role id
VAULT_SECRETID        # Vault app role secret id
VAULT_MOUNTPOINT      # Vault app role mountpoint (default "approle")
VAULT_CLIENT_TIMEOUT  # Client timeout
VAULT_SKIP_VERIFY     # Do not check SSL

If not set, vaultlib will fallback to safe default values.

vautlib will automatically use the http_proxy environment variable to connect to Vault

Tests

To test this library, run go1.11.13 test -vaultVersion 1.4.1 in the root of the repo.

Getting Started

For a simple, working example, check the sample folder.

package main

import (
    "fmt"
    "log"
    "os"

    vault "github.com/TrueTickets/vaultlib"
)

func main() {
    // Config can be set through ENV before invoking NewConfig
    os.Setenv("VAULT_ADDR", "http://localhost:8200")

    // Create a new config. Reads env variables, fallback to default value if needed
    vcConf := vault.NewConfig()

    // Config can also be done programmtically
    vcConf.Address = "http://localhost:8200"

    // set app role credentials (ie after reading from docker secret)
    // vcConf.AppRoleCredentials.RoleID = "myRoleID"
    // vcConf.AppRoleCredentials.SecretID = "mySecretID"
    // if you have set a different mountpoint from "approle" :
    // vcConf.AppRoleCredentials.MountPoint = "myCustomMountPoint"

    // Create new client
    vaultCli, err := vault.NewClient(vcConf)
    if err != nil {
        log.Fatal(err)
    }

    // Get the Vault secret data
    kv, err := vaultCli.GetSecret("my_kv/my_org/my_secret")
    if err != nil {
        fmt.Println(err)
    }
    for k, v := range kv {
        fmt.Printf("secret %v: %v\n", k, v)
    }
}

Documentation

Overview

Package vaultlib is a lightweight Go library for reading Vault KV secrets. Interacts with Vault server using HTTP API only.

First create a new *config object using NewConfig().

Then create you Vault client using NewClient(*config).

See Also

https://github.com/mch1307/vaultlib#vaultlib

Example

// Create a new config. Reads env variables, fallback to default value if needed
vcConf := NewConfig()

// Add the Vault approle secretid after having read it from docker secret
// vcConf.AppRoleCredentials.SecretID

// Create new client
vaultCli, err := NewClient(vcConf)
if err != nil {
	log.Fatal(err)
}
defer vaultCli.Shutdown()

// Get the Vault KV secret from kv_v1/path/my-secret
kvV1, err := vaultCli.GetSecret("kv_v1/path/my-secret")
if err != nil {
	fmt.Println(err)
}
for k, v := range kvV1.KV {
	fmt.Printf("Secret %v: %v\n", k, v)
}
// Get the Vault KVv2 secret kv_v2/path/my-secret
kvV2, err := vaultCli.GetSecret("kv_v2/path/my-secret")
if err != nil {
	fmt.Println(err)
}
for k, v := range kvV2.KV {
	fmt.Printf("Secret %v: %v\n", k, v)
}
jsonSecret, err := vaultCli.GetSecret("kv_v2/path/json-secret")
if err != nil {
	fmt.Println(err)
}
fmt.Printf("%v\n", jsonSecret.JSONSecret)

Index

• type AppRoleCredentials
• type Client
  • func NewClient(c *Config) (*Client, error)
  • func (c *Client) GetSecret(path string) (secret Secret, err error)
  • func (c *Client) GetStatus() string
  • func (c *Client) GetTokenInfo() *VaultTokenInfo
  • func (c *Client) IsAuthenticated() bool
  • func (c *Client) RawRequest(method, path string, payload interface{}) (result json.RawMessage, err error)
  • func (c *Client) Shutdown()
• type Config
  • func NewConfig() *Config
• type Metadata
• type Secret
• type VaultTokenInfo

Examples

• Package
• Client.IsAuthenticated
• NewClient
• NewConfig

Types

type AppRoleCredentials

type AppRoleCredentials struct {
	RoleID     string `json:"role_id"`
	SecretID   string `json:"secret_id"`
	MountPoint string `json:"-"`
}

AppRoleCredentials holds the app role secret and role ids

type Client

type Client struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

Client holds the vault client

func NewClient

func NewClient(c *Config) (*Client, error)

NewClient returns a new client based on the provided config.

If you are using the client and then disposing it, make sure you call defer client.Shutdown() once you are done with it. Failing to do so will result in an infinite goroutine running in the background.

Example

myConfig := NewConfig()
myVaultClient, err := NewClient(myConfig)
if err != nil {
	fmt.Println(err)
}
defer myVaultClient.Shutdown()

fmt.Println(myVaultClient.address)

func (*Client) GetSecret

func (c *Client) GetSecret(path string) (secret Secret, err error)

GetSecret returns the Vault secret object

KV: map[string]string if the secret is a KV

JSONSecret: json.RawMessage if the secret is a json

func (*Client) GetStatus

func (c *Client) GetStatus() string

GetStatus return the last action status/log

func (*Client) GetTokenInfo

func (c *Client) GetTokenInfo() *VaultTokenInfo

GetTokenInfo returns the current token information

func (*Client) IsAuthenticated

func (c *Client) IsAuthenticated() bool

IsAuthenticated returns bool if last call to vault was ok

Example

myConfig := NewConfig()
myVaultClient, err := NewClient(myConfig)
if err != nil {
	fmt.Println(err)
}
defer myVaultClient.Shutdown()

if myVaultClient.IsAuthenticated() {
	fmt.Println("myVaultClient's connection is ok")
}

func (*Client) RawRequest

func (c *Client) RawRequest(method, path string, payload interface{}) (result json.RawMessage, err error)

RawRequest create and execute http request against Vault HTTP API for client. Use the client's token for authentication.

Specify http method, Vault path (ie /v1/auth/token/lookup) and optional json payload. Return the Vault JSON response .

func (*Client) Shutdown

func (c *Client) Shutdown()

Shutdown stops the infinite renewToken loop and cleans up any associated resources for the client. You can call defer client.Shutdown() safely even if no renewToken loop is running.

type Config

type Config struct {
	Address            string
	MaxRetries         int
	Timeout            time.Duration
	CACert             string
	InsecureSSL        bool
	AppRoleCredentials *AppRoleCredentials
	Token              string
}

Config holds the vault client config

func NewConfig

func NewConfig() *Config

NewConfig returns a new configuration based on env vars or default value.

Reads ENV:

VAULT_ADDR            Vault server URL (default http://localhost:8200)
VAULT_ROLEID          Vault app role id
VAULT_SECRETID        Vault app role secret id
VAULT_MOUNTPOINT      Vault app role mountpoint (default "approle")
VAULT_TOKEN           Vault Token (in case approle is not used)
VAULT_CACERT          Path to CA pem file
VAULT_SKIP_VERIFY     Do not check SSL
VAULT_CLIENT_TIMEOUT  Client timeout

Modify the returned config object to adjust your configuration.

Example

myConfig := NewConfig()
myConfig.Address = "http://localhost:8200"

type Metadata

type Metadata struct {
	CreatedTime  time.Time `json:"created_time"`
	DeletionTime string    `json:"deletion_time"`
	Destroyed    bool      `json:"destroyed"`
	Version      int       `json:"version"`
}

Metadata holds additional information about Vault secrets (kv v2)

type Secret

type Secret struct {
	KV         map[string]string
	JSONSecret json.RawMessage
	Metadata   Metadata
}

Secret holds the secret.

KV contains data in case of KV secret.

JSONSecret contains data in case of JSON raw secret.

type VaultTokenInfo

type VaultTokenInfo struct {
	Accessor       string      `json:"accessor"`
	CreationTime   int         `json:"creation_time"`
	CreationTTL    int         `json:"creation_ttl"`
	DisplayName    string      `json:"display_name"`
	EntityID       string      `json:"entity_id"`
	ExpireTime     interface{} `json:"expire_time"`
	ExplicitMaxTTL int         `json:"explicit_max_ttl"`
	ID             string      `json:"id"`
	IssueTime      time.Time   `json:"issue_time"`
	Meta           interface{} `json:"meta"`
	NumUses        int         `json:"num_uses"`
	Orphan         bool        `json:"orphan"`
	Path           string      `json:"path"`
	Policies       []string    `json:"policies"`
	Renewable      bool        `json:"renewable"`
	TTL            int         `json:"ttl"`
	Type           string      `json:"type"`
}

VaultTokenInfo holds the Vault token information