awskms

README

AWS KMS

AWS KMS using envelope encryption with 256-bit AES in Galois/Counter Mode (GCM).

Quick Start

Sample Terraform code is available in testing/terraform/awskms to try this provider with AWS KMS.

Example

package main

import (
	"context"

	"github.com/aws/aws-sdk-go-v2/config"
	"github.com/aws/aws-sdk-go-v2/service/kms"

	"github.com/bincyber/go-sqlcrypter"
	"github.com/bincyber/go-sqlcrypter/providers/awskms"
)

func main() {
	cfg, err := config.LoadDefaultConfig(context.Background())
	if err != nil {
		// handle error
	}

	client := kms.NewFromConfig(cfg)

	kmsCrypter, err := awskms.New(context.Background(), client, "alias/sqlcrypter")
	if err != nil {
		//handle error
	}

	sqlcrypter.Init(kmsCrypter)
}

Envelope Encryption

KMSCrypter uses envelope encryption. When awskms.New() is called, a request is made to the the KMS GenerateDataKey API to retrieve a 256-bit symmetric data encryption key (DEK). This DEK is used to encrypt data using AES GCM instead of calling the KMS Encrypt and Decrypt APIs every time. The encrypted DEK is stored alongside the ciphertext. To decrypt previous DEKs stored alongside ciphertext, a request is made to the KMS Decrypt API. The decrypted DEK is then cached in memory to avoid repetitive API calls to KMS.

Testing

nsmith/local-kms is used to help with testing. The seed file used is located in testing/seed.yaml.

Documentation

Index

• func New(ctx context.Context, client *kms.Client, keyID string) (sqlcrypter.Crypterer, error)
• type KMSCrypter
  • func (k *KMSCrypter) Decrypt(w io.Writer, r io.Reader) error
  • func (k *KMSCrypter) Encrypt(w io.Writer, r io.Reader) error

Functions

func New

func New(ctx context.Context, client *kms.Client, keyID string) (sqlcrypter.Crypterer, error)

New creates a new AWS KMS crypter given a KMS client and the ID/Alias/ARN of a KMS key. A new data encryption key (DEK) is obtained from KMS which will be stored alongside the ciphertext. 256-bit AES GCM is used to perform the encryption.

Types

type KMSCrypter

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

KMSCrypter is an implementation of the Crypterer interface using AWS KMS with envelope encryption.

func (*KMSCrypter) Decrypt

func (k *KMSCrypter) Decrypt(w io.Writer, r io.Reader) error

Decrypt decrypts ciphertext to plaintext. It first attempts to decrypt using the current DEK if it matches the encrypted key stored alongside the ciphertext. Otherwise, a request is made to KMS to decrypt the encrypted key and then the DEK is used to decrypt the ciphertext.

func (*KMSCrypter) Encrypt

func (k *KMSCrypter) Encrypt(w io.Writer, r io.Reader) error

Encrypt encrypts plaintext to ciphertext using the current DEK. The encrypted DEK is stored alongside the ciphertext.