hcpsecrets

README

Vault Plugin: HashiCorp Cloud Platform (HCP) Backend

Proof of Value

This Vault secrets plugin is not officially maintained or supported by HashiCorp. It exists as a proof of value for a Vault secrets engine that can dynamically generate HCP service principal keys.

TODO

• Locks
• Tests
• Static Roles

Important

• Organization level service principals are very powerful and should be used sparingly.
• Service Principals can only have two Service Principal Keys.
• Projects can only have five Service Principals.

Overview

This is a standalone backend plugin for use with Hashicorp Vault. This plugin generates revocable, time-limited service principals for HCP Projects.

Please note: We take Vault's security and our users' trust very seriously. If you believe you have found a security issue in Vault, please responsibly disclose by contacting us at security@hashicorp.com.

Quick Links

• Vault Website
• Vault Project GitHub

Getting Started

This is a Vault plugin and is meant to work with Vault. This guide assumes you have already installed Vault and have a basic understanding of how Vault works.

Otherwise, first read this guide on how to get started with Vault.

Usage

# mount
$ vault secrets enable hcp

# configure
$ vault write hcp/config \
   organization="..." \
   project="..." \
   client_id="..." \
   client_secret="..."

# read configuration
$ vault read hcp/config

# patch configuration
$ vault patch hcp/config organization="..."

# rotate initial credentials
$ vault write -f hcp/config/rotate

# configure a role
$ vault write hcp/roles/packer \
   role="contributor" \
   ttl="30m" \
   max_ttl="1h"

# list roles
$ vault list hcp/roles

# read role
$ vault read hcp/roles/packer

# generate credentials
$ vault read hcp/creds/packer

# delete role
$ vault delete hcp/roles/packer

# delete config
$ vault delete hcp/config

Developing

If you wish to work on this plugin, you'll first need Go installed on your machine.

If you're developing for the first time, run make bootstrap to install the necessary tools. Bootstrap will also update repository name references if that has not been performed ever before.

$ make bootstrap

To compile a development version of this plugin, run make or make dev. This will put the plugin binary in the bin and $GOPATH/bin folders. dev mode will only generate the binary for your platform and is faster:

$ make dev

Put the plugin binary into a location of your choice. This directory will be specified as the plugin_directory in the Vault config used to start the server.

# config.hcl
plugin_directory = "path/to/plugin/directory"
...

Start a Vault server with this config file:

$ vault server -dev -config=path/to/config.hcl ...
...

Once the server is started, register the plugin in the Vault server's plugin catalog:

$ SHA256=$(openssl dgst -sha256 ./bin/vault-plugin-secrets-hcp | cut -d ' ' -f2)
$ vault plugin register \
        -sha256=$SHA256 \
        -command="vault-plugin-secrets-hcp" \
        secret hcp
...
Success! Registered plugin: hcp

Enable the secrets engine to use this plugin:

$ vault secrets enable hcp
...

Success! Enabled the hcp secrets engine at: hcp/

Tests

To run the tests, invoke make test:

$ make test

You can also specify a TESTARGS variable to filter tests like so:

$ make test TESTARGS='-run=TestConfig'

Documentation

Index

• func Backend(c *logical.BackendConfig) *hcpBackend
• func Factory(ctx context.Context, c *logical.BackendConfig) (logical.Backend, error)

Functions

func Backend

func Backend(c *logical.BackendConfig) *hcpBackend

func Factory

func Factory(ctx context.Context, c *logical.BackendConfig) (logical.Backend, error)