certmagicoss

Certmagic Storage Backend for Alibaba Cloud OSS

This library allows you to use Alibaba Cloud OSS 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 OSS storage.

Getting started with Caddyfile

1. Create a Caddyfile

   {
     storage oss {
       bucket-name your-bucket-name
       region your-oss-region
       endpoint your-oss-endpoint
       access-key-id your-access-key-id
       access-key-secret your-access-key-secret
     }
   }
   localhost
   acme_server
   respond "Hello Caddy Storage OSS!"
   

   NOTE: See https://www.alibabacloud.com/help/zh/oss/regions-and-endpoints for OSS Region & Endpoint parameters.
2. Start caddy

   $ xcaddy run
   

3. Check that it works

   $ open https://localhost
   

Getting started with JSON config

Create a JSON config file with the following content:

{
  …
  "storage": {
    "module": "oss",
    "bucket-name": "your-bucket-name",
    "region": "your-oss-region",
    "endpoint": "your-oss-endpoint",
    "access-key-id": "your-access-key-id",
    "access-key-secret": "your-access-key-secret"
  },
  …
}

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 Caddyfile config

   {
     storage oss {
       bucket-name your-bucket-name
       region your-oss-region
       endpoint your-oss-endpoint
       access-key-id your-access-key-id
       access-key-secret your-access-key-secret
       encryption-key-set ./keyset.json
     }
   }
   localhost
   acme_server
   respond "Hello Caddy Storage OSS!"
   

4. Start caddy

   $ xcaddy run
   $ # to rotate the key-set
   $ tinkey rotate-keyset --in keyset.json  --key-template AES128_GCM_RAW
   

Client Side Encryption with JSON config

1. Follow steps 1-2 from above to install tinkey and create a keyset.json file
2. Create a JSON config file with the following content:

   {
     …
     "storage": {
       "module": "oss",
       "bucket-name": "your-bucket-name",
       "region": "your-oss-region",
       "endpoint": "your-oss-endpoint",
       "access-key-id": "your-access-key-id",
       "access-key-secret": "your-access-key-secret",
       "encryption-key-set": "./keyset.json"
     },
     …
   }
   

3. Start caddy

   $ xcaddy run
   

4. 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/aUsernameWoW/certmagic-oss

1. Create a certmagicoss.NewStorage with a certmagicoss.Config:

import certmagicoss "github.com/aUsernameWoW/certmagic-oss/storage"

bucket := "my-example-bucket"
region := "your-oss-region"
endpoint := "your-oss-endpoint"
accessKeyID := "your-access-key-id"
accessKeySecret := "your-access-key-secret"

oss, _ := certmagicoss.NewStorage(
  context.Background(), 
  certmagicoss.Config{
    BucketName: bucket,
    Region: region,
    Endpoint: endpoint,
    AccessKeyID: accessKeyID,
    AccessKeySecret: accessKeySecret,
  }
)

1. Optionally, register as default storage.

certmagic.Default.Storage = oss

Building Caddy with this module

To build Caddy with this module, you can use xcaddy:

1. Install xcaddy if you haven't already:

   go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest
   

2. Build Caddy with the certmagic-oss module:

   xcaddy build --with github.com/aUsernameWoW/certmagic-oss
   

3. If you want to specify a specific version or commit:

   xcaddy build --with github.com/aUsernameWoW/certmagic-oss@v1.0.0
   # or
   xcaddy build --with github.com/aUsernameWoW/certmagic-oss@main
   

4. You can also build with other modules:

   xcaddy build \
     --with github.com/aUsernameWoW/certmagic-oss \
     --with github.com/caddyserver/nginx-adapter
   

Credits

This project was written entirely by Qwen Coder. During the coding process, Qwen Coder was inspired by the project certmagic-gcs. We would like to thank them for their high-quality code and Qwen Coder for their dedication.

License

This module is distributed under Apache-2.0.