Skip to content

grafana/certmagic-gcs

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.