keyvault

README

Keyvault - the missing Azure Keyvault package for Go

BIG NOTE

This is not the official Go SDK Keyvault, as such, is not officially supported by Microsoft. It does not use any of the Keyvault SDK code.

Please keep this in mind.

Introduction

One of the most needed services in cloud development is a safe place to securely store secrets and certificates. In Azure that is Keyvault.

The Azure SDK for Go has an official Keyvault package. Like much of the SDK, a lot of it is autogenerated from REST, which does not yield a nice API surface.

The Go SDK suffers from a few problems:

• Does not support Go types such as time.Time, x509.Certificate, tls.Certificate, ...
• Certificate use require deep dives into Kevault Documenation to access
• Documentation is quite long and hard to look through
• Non-Idomatic

My team wanted something that did what 99% of Go users would want without spending time diving into documenation.

We currently support:

• Secret operations
• Certificate operations
• TLS specific operations

Not all operations are supported in the high level API, as many of them are mostly useful to Microsoft teams creating tooling. Most of those are available through a lower level API.

Usage

Creating a client

Accessing a sub-client

Fetch a secret

Fetch a TLS cetificate

Access lower level API

Documentation

Overview

Package keyvault provides access to Azure's Keyvault service.

For details on the keyvault service, see: https://azure.microsoft.com/en-us/services/key-vault/

For general information on the XML API: https://docs.microsoft.com/en-us/rest/api/keyvault/

Below are some examples of using common sub-packages. For more detailed information, options and examples, see the individual packages.

Creating a client with MSI authorizer

To begin using this package, create an Authorizer and a client targeting your keyvault endpoint:

msi, err := keyvault.MSIAuth(msiClientID, keyvault.PublicCloud)
if err != nil {
	// Do something
}

// This creates your client. The "vaultName" is a standin fo
// your unique vault name (not the FQDN).
client, err := keyvault.New("vaultName", keyvault.PublicCloud, msi)
if err != nil {
	// Do something
}

Accessing a text secret

You can access a secret by accessing the secret package and calling a method:

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

secret, _, err := client.Secrets().Get(ctx, "text-secret")
if err != nil {
	// Do something
}
fmt.Println(string(secret))

Accessing a binary secret

Some secrets represent binary data Base64 encoded. Retrieval is simple:

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

secret, _, err := client.Secrets().Get(ctx, "binary-secret", secrets.Base64Decode())
if err != nil {
	// Do something
}

Retrieve a TLS cert for Golang webserver

Getting a TLS cert to serve up for a Golang HTTP server is easy:

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

// We automatically deal with PKCS12 or PEM decoding.
cert, _, err := client.TLS().ServiceCert(ctx, "certname")
if err != nil {
	// Do something
}

cfg := &tls.Config{Certificates: []tls.Certificate{cert}}
srv := &http.Server{
	TLSConfig:    cfg,
	ReadTimeout:  time.Minute,
	WriteTimeout: time.Minute,
}
log.Fatal(srv.ListenAndServeTLS("", ""))

Index

• func MSIAuth(clientID string, endpoint CloudEndpoint) (auth.Authorization, error)
• type Client
  • func New(vault string, endpoint CloudEndpoint, auth auth.Authorization) (*Client, error)
  • func (c *Client) Ops() *ops.REST
  • func (c *Client) Secrets() secrets.Secrets
  • func (c *Client) TLS() tls.TLS
• type CloudEndpoint

Functions

func MSIAuth

func MSIAuth(clientID string, endpoint CloudEndpoint) (auth.Authorization, error)

MSIAuth provides authentication to Keyvault by an Azure's Managed Service Identity. Simply provide the MSI's clientID. This is the only secure method of accessing a Keyvault. An auth package is available for doing other authorization methods, but every other method (at this time) would require storing a secret or cert to access the Keyvault in another secret store. Note: If using Kubernetes, pods do not get access to MSI by default, it requires: https://github.com/Azure/aad-pod-identity .

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a client for interacting with KeyVault.

func New

func New(vault string, endpoint CloudEndpoint, auth auth.Authorization) (*Client, error)

New creates a new Keyvault Client. vault is the name of the Keyvault. endpoint is the CloudEndpoint (usually PublicCloud). auth can be created normally with MSIAuth().

func (*Client) Ops

func (c *Client) Ops() *ops.REST

Ops returns the underlying REST client that this package uses underneath to access KeyVault. Use this only when this client does not support an operation you require, as the REST client is not normally meant to be interacted with.

func (*Client) Secrets

func (c *Client) Secrets() secrets.Secrets

Secrets returns an object for doing Secrets operations.

func (*Client) TLS

func (c *Client) TLS() tls.TLS

TLS returns an object for doing common TLS operations.

type CloudEndpoint

type CloudEndpoint string

CloudEndpoint is an endpoint address to use when doing authenication with MSI.

const (
	// PublicCloud is Azure's public cloud endpoint.
	PublicCloud CloudEndpoint = "https://vault.azure.net/"
)