certmagicgcs

README

Certmagic Storage Backend for Google Cloud Storage

This library allows you to use Google Cloud Storage as key/certificate storage backend for your Certmagic-enabled HTTPS server. To protect your keys from unwanted attention, client-side encryption is possible.

Usage

Caddy

In this section, we create a caddy config using our GCS storage.

Getting started

1. Create a Caddyfile

   {
     storage gcs {
       bucket-name some-bucket
     }
   }
   localhost
   acme_server
   respond "Hello Caddy Storage GCS!"
   

2. Start GCS emulator

   $ docker run -d \
       -p 9023:9023 \
       --name gcp-storage-emulator \
       oittaa/gcp-storage-emulator \
       start --default-bucket=some-bucket --port 9023 --in-memory
   $ export STORAGE_EMULATOR_HOST=http://localhost:9023
   

3. Start caddy

   $ xcaddy run
   

4. Check that it works

   $ open https://localhost
   

Client Side Encryption

This module supports client side encryption using google Tink, thus providing a simple way to customize the encryption algorithm and handle key rotation. To get started:

1. Install tinkey
2. Create a key set

   $ tinkey create-keyset --key-template AES128_GCM_RAW --out keyset.json
   

   Here is an example keyset.json:

   {
     "primaryKeyId": 1818673287,
     "key": [
       {
         "keyData": {
           "typeUrl": "type.googleapis.com/google.crypto.tink.AesGcmKey",
           "value": "GhDEQ/4v72esAv3rbwZyS+ls",
           "keyMaterialType": "SYMMETRIC"
         },
         "status": "ENABLED",
         "keyId": 1818673287,
         "outputPrefixType": "RAW"
       }
     ]
   }
   

3. Start caddy with the following config

   {
     storage gcs {
       bucket-name some-bucket
       encryption-key-set ./keyset.json
     }
   }
   localhost
   acme_server
   respond "Hello Caddy Storage GCS!"
   

4. restart the fake gcs backend to start with an empty bucket

   $ docker restart gcp-storage-emulator
   $ # start caddy
   $ xcaddy run
   $ # to rotate the key-set
   $ tinkey rotate-keyset --in keyset.json  --key-template AES128_GCM_RAW
   

CertMagic

1. Add the package:

go get github.com/grafana/certmagic-gcs

1. Create a certmagicgcs.NewStorage with a certmagicgcs.StorageConfig:

import certmagicgcs "github.com/grafana/certmagic-gcs/storage"

bucket := "my-example-bucket"

gcs, _ := certmagicgcs.NewStorage(
  context.Background(), 
  &certmagicgcs.StorageConfig{BucketName: bucket}
)

1. Optionally, register as default storage.

certmagic.Default.Storage = gcs

License

This module is distributed under AGPL-3.0-only.

Documentation

Index

• type CaddyStorageGCS
  • func (CaddyStorageGCS) CaddyModule() caddy.ModuleInfo
  • func (s *CaddyStorageGCS) CertMagicStorage() (certmagic.Storage, error)
  • func (s *CaddyStorageGCS) UnmarshalCaddyfile(d *caddyfile.Dispenser) error
  • func (s *CaddyStorageGCS) Validate() error

Types

type CaddyStorageGCS

type CaddyStorageGCS struct {
	// BucketName is the name of the storage bucket.
	BucketName string `json:"bucket-name"`
	// EncryptionKeySet is the path of a json tink encryption keyset
	EncryptionKeySet string `json:"encryption-key-set"`
}

CaddyStorageGCS implements a caddy storage backend for Google Cloud Storage.

func (CaddyStorageGCS) CaddyModule

func (CaddyStorageGCS) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*CaddyStorageGCS) CertMagicStorage

func (s *CaddyStorageGCS) CertMagicStorage() (certmagic.Storage, error)

CertMagicStorage returns a cert-magic storage.

func (*CaddyStorageGCS) UnmarshalCaddyfile

func (s *CaddyStorageGCS) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile unmarshall caddy file.

func (*CaddyStorageGCS) Validate

func (s *CaddyStorageGCS) Validate() error

Validate caddy gcs storage configuration.