kmskey

README

Go KMS Certificate Signer

This library will allow you to use AWS KMS keys to sign X509 certificates.

Install

go get -u github.com/webdestroya/go-kmskey@latest

Features

• Sign X509 Certificates using KMS Keys
• Decrypt data using a KMS key
• Use KMS to generate secure random data

Usage

Certificate Signing

package myapp

import (
  "context"
	"crypto/rand"
	"crypto/x509"
	"crypto/x509/pkix"
	"math/big"
	"time"

	"github.com/aws/aws-sdk-go-v2/config"
	"github.com/webdestroya/go-kmskey"
)

func main() {
  ctx := context.Background()

	cfg, err := config.LoadDefaultConfig(ctx, config.WithRegion("us-east-1"))
	if err != nil {
		panic(err)
	}

  key, err := kmskey.NewKey(ctx, "alias/my-signing-key", kmskey.WithAwsConfig(cfg))
  if err != nil {
    panic(err)
  }

  subject := pkix.Name{
		CommonName: `My Custom Certificate Authority`,
	}

	certTemplate := &x509.Certificate{
		SerialNumber:          big.NewInt(1),
		Subject:               subject,
		Issuer:                subject,
		NotBefore:             time.Now().Add(-10 * time.Minute),
		NotAfter:              time.Now().Add(2 * 365 * 24 * time.Hour),
		BasicConstraintsValid: true,
    IsCA:                  true,
    MaxPathLenZero:        true,
		KeyUsage:              x509.KeyUsageCertSign,
	}

  certBytes, err := x509.CreateCertificate(rand.Reader, certTemplate, certTemplate, key.Public(), key)
  if err != nil {
    panic(err)
  }

  certificate, err := x509.ParseCertificate(certBytes)
  if err != nil {
    panic(err)
  }

  // You can do something with the certificate now, like sign other leaf certificates

}

Secure Random Data

package myapp

import (
	"context"
	"crypto/rsa"

	"github.com/aws/aws-sdk-go-v2/config"
	"github.com/webdestroya/go-kmskey"
)

func Example() {

	ctx := context.Background()

	cfg, err := config.LoadDefaultConfig(ctx, config.WithRegion("us-east-1"))
	if err != nil {
		panic(err)
	}

	kmsrand, err := kmskey.NewRandom(ctx, kmskey.WithAwsConfig(cfg))
  if err != nil {
    panic(err)
  }

	// Key Generation:
	rsaKey, err := rsa.GenerateKey(kmsrand, 3072)
	if err != nil {
		panic(err)
	}

	// do something with the new key
	_ = rsaKey

}

License

Licensed under the MIT License. See LICENSE for more info.

Documentation

Index

• Variables
• func NewRandom(ctx context.Context, optFns ...OptionFunc) (io.Reader, error)
• type Key
  • func NewKey(ctx context.Context, keyArn string, opts ...OptionFunc) (*Key, error)
  • func (k *Key) Decrypt(_ io.Reader, msg []byte, opts crypto.DecrypterOpts) ([]byte, error)
  • func (k *Key) Encrypt(hsh hash.Hash, rand io.Reader, msg []byte) ([]byte, error)
  • func (k *Key) Equal(x crypto.PrivateKey) bool
  • func (k *Key) KeyARN() string
  • func (k *Key) KeySpec() kmsTypes.KeySpec
  • func (k *Key) Public() crypto.PublicKey
  • func (k *Key) Sign(_ io.Reader, digest []byte, opts crypto.SignerOpts) ([]byte, error)
  • func (k *Key) SubjectPublicKeyInfo() []byte
• type OptionFunc
  • func WithAwsClient(client kmsClienter) OptionFunc
  • func WithAwsConfig(cfg aws.Config, fns ...func(*kms.Options)) OptionFunc
  • func WithCustomKeyStoreId(v string) OptionFunc
  • func WithGrantTokens(tokens []string) OptionFunc
  • func WithMaxConcurrency(conc int) OptionFunc
  • func WithSigningAlgorithm(alg kmsTypes.SigningAlgorithmSpec) OptionFunc

Examples

• NewRandom

Variables

var (
	ErrKeyNotSignVerifyError        = errors.New("key usage is not SIGN_VERIFY")
	ErrKeyNotEncryptDecryptError    = errors.New("key usage is not ENCRYPT_DECRYPT")
	ErrNoAwsClientError             = errors.New("no aws client initialized, use WithAwsConfig or WithAwsClient")
	ErrInvalidSigningAlgorithmError = errors.New("invalid signing algorithm choice")
	ErrUnsupportedDecryptionError   = errors.New("unsupported decryption options")
)

Functions

func NewRandom

func NewRandom(ctx context.Context, optFns ...OptionFunc) (io.Reader, error)

Example

package main

import (
	"context"
	"crypto/rsa"

	"github.com/aws/aws-sdk-go-v2/config"
	"github.com/webdestroya/go-kmskey"
)

func main() {

	ctx := context.Background()

	cfg, err := config.LoadDefaultConfig(ctx, config.WithRegion("us-fake-1"))
	if err != nil {
		panic(err)
	}

	kmsrand, err := kmskey.NewRandom(ctx, kmskey.WithAwsConfig(cfg))
	if err != nil {
		panic(err)
	}

	// Key Generation:
	rsaKey, err := rsa.GenerateKey(kmsrand, 3072)
	if err != nil {
		panic(err)
	}

	// do something with the new key
	_ = rsaKey

}

Types

type Key

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

func NewKey

func NewKey(ctx context.Context, keyArn string, opts ...OptionFunc) (*Key, error)

func (*Key) Decrypt

func (k *Key) Decrypt(_ io.Reader, msg []byte, opts crypto.DecrypterOpts) ([]byte, error)

func (*Key) Encrypt

func (k *Key) Encrypt(hsh hash.Hash, rand io.Reader, msg []byte) ([]byte, error)

func (*Key) Equal

func (k *Key) Equal(x crypto.PrivateKey) bool

func (*Key) KeyARN

func (k *Key) KeyARN() string

The resolved ARN of the key being used

func (*Key) KeySpec

func (k *Key) KeySpec() kmsTypes.KeySpec

func (*Key) Public

func (k *Key) Public() crypto.PublicKey

func (*Key) Sign

func (k *Key) Sign(_ io.Reader, digest []byte, opts crypto.SignerOpts) ([]byte, error)

func (*Key) SubjectPublicKeyInfo

func (k *Key) SubjectPublicKeyInfo() []byte

The value is a DER-encoded X.509 public key, also known as SubjectPublicKeyInfo (SPKI), as defined in RFC 5280

type OptionFunc

type OptionFunc = func(*kcsOption) error

func WithAwsClient

func WithAwsClient(client kmsClienter) OptionFunc

Used with NewKey and NewRandom

func WithAwsConfig

func WithAwsConfig(cfg aws.Config, fns ...func(*kms.Options)) OptionFunc

Used with NewKey and NewRandom

func WithCustomKeyStoreId

func WithCustomKeyStoreId(v string) OptionFunc

Specifies a Custom KeyStore to use to generate random data.

Only used with NewRandom

func WithGrantTokens

func WithGrantTokens(tokens []string) OptionFunc

If you need to provide KMS grant tokens for your requests to GetPublicKey, Sign, Decrypt

func WithMaxConcurrency

func WithMaxConcurrency(conc int) OptionFunc

Sets the maximum parallel requests that will be made to get random data.

Only used with NewRandom

func WithSigningAlgorithm

func WithSigningAlgorithm(alg kmsTypes.SigningAlgorithmSpec) OptionFunc

Force the signing algorithm to use. You probably should not set this.