vaultpki

README

go-vault-pki

This Go library works as a gateway for any Go service that wants to use Vault PKI for issuing certificates. This is especially useful for services that would like to use HTTP/2 in full with end-to-end encryption and by utilizing a pre-existing PKI.

Library exposes the following two methods:

• RefreshTLSConfig(): issues a new TLS certificate and returns a tls.Config instance from net/http with the certificate chain. This can then be used in any HTTP router, like go-chi.
• IssueNewCertificate(): issues a new TLS certificate and returns an api.Secret instance described by the Vault API. Certificate data can be accessed through api.Secret.Data map.

Prequisites for using the library

Make sure you have a Vault PKI properly configured. If not, read the documentation. You must set up a root CA or an intermediate CA (signed by another CA) in your Vault. You'll then have to set up a Vault PKI role, which can issue certificates under that CA with specific Common Names (CN). You'll need to configure a Vault policy, so tokens with specific Vault policies can issue new certificates. In any case you probably end up in a situation where you have a service called foo which would like to issue a certificate for foo.datacenter.whatever or foo.company.tld or whatever.

Using the library

Make sure you expose the following environment variables for your service:

• VAULT_TOKEN: A Vault token, which has necessary rights to a PKI role for issuing certificates.
• VAULT_ADDR: Vault address, for example https//vault.service.consul:8200

A job scheduler such as Nomad or Kubernetes does this for you automatically.

Then, while setting up HTTP router in your service you should call RefreshTLSConfig(). For example like this (but with proper error handling):

// Set up VaultPKI instance and get a new TLSConfig
v, err := vaultpki.NewWithConfig(pkiMount, pkiRole, serviceCN, certTTL)
tlsCfg, err := v.RefreshTLSConfig()

// Set up our HTTP router
r := chi.NewRouter()
r.Get("/", func(w http.ResponseWriter, r *http.Request) {
	w.Write([]byte("welcome"))
})

// Set up HTTP server
srv := http.Server{
    Addr:      "127.0.0.1:18080",
	Handler:   r,
	TLSConfig: tlsCfg,
}
err = srv.ListenAndServeTLS("", "")

For a complete example see the demo-app under examples directory or main_test.go.

Documentation

Index

• Variables
• type VaultPKI
  • func New(path, role, cn, certTTL string) (*VaultPKI, error)
  • func NewWithConfig(path, role, cn, certTTL string, cfg *api.Config) (*VaultPKI, error)
  • func (v *VaultPKI) IssueNewCertificate() (*api.Secret, error)
  • func (v *VaultPKI) RefreshTLSConfig() (*tls.Config, error)

Variables

var (
	ErrCertIssueFailed = errors.New("failed to issue new certificate from vault")
)

Types

type VaultPKI

type VaultPKI struct {
	Client *api.Client
	// contains filtered or unexported fields
}

VaultPKI represents a Vault PKI role for issuing certificates

func New

func New(path, role, cn, certTTL string) (*VaultPKI, error)

New returns a new VaultPKI instance by using default Vault API configuration

func NewWithConfig

func NewWithConfig(path, role, cn, certTTL string, cfg *api.Config) (*VaultPKI, error)

NewWithConfig returns a new VaultPKI instance by allowing Vault API config customization through 'cfg' parameter

func (*VaultPKI) IssueNewCertificate

func (v *VaultPKI) IssueNewCertificate() (*api.Secret, error)

IssueNewCertificate issues a new certificate through Vault API call and returns the API secret response as is.

func (*VaultPKI) RefreshTLSConfig

func (v *VaultPKI) RefreshTLSConfig() (*tls.Config, error)

RefreshTLSConfig issues a new certificate and returns a corresponding net/http tls.Config instance which can be used in various HTTP routers