crypto

Documentation

Overview

Package crypto implements cryptography for secrets.

Under the hood, it leverages AWS KMS for master key management and key wrapping, and nacl/secretbox for encryption and authentication.

Secret encryption

For each `Encrypt` operation, a new 256 bits data key is requested from KMS. which returns both the key in plaintext and in encrypted form.

This key is then fed to nacl/secretbox, along with a 192 bits random nonce, generated from go's default CSPRNG (see the crypto/rand package). secretbox uses XSalsa20 and Poly1305 to encrypt and authenticate messages.

The secret ciphertext consists of the random nonce and the encrypted secret.

The encrypted data key and the secret ciphertext are then base64-encoded and returned as a string, along with a versioning field.

Secret decryption

The encrypted data key and encrypted secret are extracted from the input

A request is made to AWS KMS to decypt the data key. AWS returns the data key plaintext.

The nonce and encrypted secret are extracted from the secret ciphertext, and fed to nacl/secretbox for authentication and decryption.

Encoding format

The encrypted secrets are encoded in the following format:

"EJK1;abcdef...;foobar..."
 ^-- versionning field allowing algorithm changes in the future
       ^-- base64 encoded encrypted data key
                 ^-- base64 encoded [random nonce, encrypted secret]

Index

• Constants
• type Cipher
  • func NewCipher(client kms.Client, kmsKeyID string) *Cipher
  • func (c *Cipher) Decrypt(encoded string, context map[string]*string) (string, error)
  • func (c *Cipher) Encrypt(plaintext string, context map[string]*string) (string, error)

Constants

const MagicPrefix = "EJK1"

MagicPrefix is a string prepended to all ciphertexts in the JSON representation. It will allow versioning the algorithm in the future.

Types

type Cipher

type Cipher struct {

	// Client is the AWS KMS client
	Client kms.Client

	// KMSKeyID is the ID of the master key to use for key wrapping
	KMSKeyID string
	// contains filtered or unexported fields
}

Cipher is a struct containing the configuration for crypto operations on a single secrets file.

func NewCipher

func NewCipher(client kms.Client, kmsKeyID string) *Cipher

NewCipher returns an initialized Cipher.

func (*Cipher) Decrypt

func (c *Cipher) Decrypt(encoded string, context map[string]*string) (string, error)

Decrypt is the main entrypoint for encrypting secrets.

It takes the string-encoded ciphertext and returns the decoded and decrypted plaintext.

func (*Cipher) Encrypt

func (c *Cipher) Encrypt(plaintext string, context map[string]*string) (string, error)

Encrypt is the main entrypoint for encrypting secrets.

It takes the plaintext to encrypt, and returns the encrypted and string-encoded ciphertext.