README

SSL Certificates Storage

Go Report Card Documentation GitHub issues license

Go tools for managing SSL certificates from acme/autocert

The autocert package provides automatic access to certificates from Let's Encrypt and any other ACME-based CA. This repository contains a collection of tools to simplify the task of managing certificates acquired through this method.

Want to have SSL and don't know where to start => Check out the sslmgr package

Tools:

  • LayeredCache - chain autocert.Cache implementations
  • Functional - define an autocert.Cache by using anonymous functions

Cache Implementations:

  • Firestore - if you are looking for quick and easy
  • MongoDB - when flexibility and robustness are important
  • DynamoDB - if your infra lives in AWS
  • S3 - throw those certs in a bucket

Why should I use this? Is this for me?

The default storage mechanism used by autocert is the file system. Containerized and virtual workloads often don't have a persistent file system. Furthermore, file system storage is not suitable for servers spanning multiple machines or distributed systems.

See that the autocert.Cache interface is what controlls where/how certificates are stored/fetched from:

m := autocert.Manager{
	Prompt:     autocert.AcceptTOS, // To always accept the terms, the callers can use AcceptTOS
	HostPolicy: autocert.HostWhitelist(hostnames...), // Specifies which hostnames the Manager is allowed to respond to
	Cache:      cache, // Cache is used by Manager to store and retrieve previously obtained certificates and other account data as opaque blobs
}

I have implemented the autocert.Cache interface with popular data stores on major cloud providers; so that you dont have to!

But wait, why can't I just get a new certificate every time I deploy?

Unless you have a corporate deal with Lets Encrypt, you are limited to 5 duplicate certificates (certificates for the same set of names) per week on a rolling basis. This means that if your deployments don't have persistent storage, you can only deploy 5 different times (or even less if your deployments span multiple machines) within a week!

Documentation

Index

Constants

View Source
const (
	// PolicyWriteDeepFirst will write to caches starting from the last layer
	// provided. This is the default behavior, as the more common use case
	// will be for the last layer to be the most persistent e.g. DB call
	PolicyWriteDeepFirst = WritePolicy("DEEP_FIRST")
	// PolicyWriteShallowFirst will write to caches starting from the top,
	// often least persistent, layer e.g. a struct in process heap
	PolicyWriteShallowFirst = WritePolicy("SHALLOW_FIRST")
)

Variables

This section is empty.

Functions

This section is empty.

Types

type DynamoDB

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

    DynamoDB represents a DynamoDB implementation of autocert.Cache

    func NewDynamoDB

    func NewDynamoDB(credentials *credentials.Credentials, region, table string) *DynamoDB

      NewDynamoDB returns a DynamoDB certificate cache

      func (*DynamoDB) Delete

      func (ddb *DynamoDB) Delete(ctx context.Context, key string) error

        Delete removes a certificate data from the cache under the specified key. If there's no such key in the cache, Delete returns nil.

        func (*DynamoDB) Get

        func (ddb *DynamoDB) Get(ctx context.Context, key string) ([]byte, error)

          Get returns a certificate data for the specified key. If there's no such key, Get returns ErrCacheMiss.

          func (*DynamoDB) Put

          func (ddb *DynamoDB) Put(ctx context.Context, key string, data []byte) error

            Put stores the data in the cache under the specified key. Underlying implementations may use any data storage format, as long as the reverse operation, Get, results in the original data.

            type Firestore

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

              Firestore is a Google Firestore implementation of autocert.Cache

              func NewFirestore

              func NewFirestore(credsPath, projectID string) *Firestore

                NewFirestore is the default constructor for a Firestore CertCache

                func NewFirestoreWithCollection

                func NewFirestoreWithCollection(credsPath, projectID, certsCollectionName string) *Firestore

                  NewFirestoreWithCollection is a constructor for a FirestoreCertCache with a custom Firestore Collection name

                  func (*Firestore) Delete

                  func (fcc *Firestore) Delete(ctx context.Context, key string) error

                    Delete removes a certificate data from the cache under the specified key. If there's no such key in the cache, Delete returns nil.

                    func (*Firestore) Get

                    func (fcc *Firestore) Get(ctx context.Context, key string) ([]byte, error)

                      Get returns a certificate data for the specified key. If there's no such key, Get returns ErrCacheMiss.

                      func (*Firestore) Put

                      func (fcc *Firestore) Put(ctx context.Context, key string, data []byte) error

                        Put stores the data in the cache under the specified key. Underlying implementations may use any data storage format, as long as the reverse operation, Get, results in the original data.

                        type Functional

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

                          Functional allows the user to use functions to define a cert cache. If we have the get function always return an autocert.ErrCacheMiss error, we can use this cert cache for testing next cache layer's preconditions, or simply logging events (see Newlogger() function)

                          func NewFunctional

                          func NewFunctional(
                          	get func(context.Context, string) ([]byte, error),
                          	put func(context.Context, string, []byte) error,
                          	del func(context.Context, string) error,
                          ) *Functional

                            NewFunctional is the constructor for a functional Cert Cache

                            func NewLogger

                            func NewLogger() *Functional

                              NewLogger is the constructor for a Functional cert cache implementation which does nothing other than log events

                              func (*Functional) Delete

                              func (f *Functional) Delete(ctx context.Context, key string) error

                                Delete removes a certificate data from the cache under the specified key. If there's no such key in the cache, Delete returns nil.

                                func (*Functional) Get

                                func (f *Functional) Get(ctx context.Context, key string) ([]byte, error)

                                  Get returns a certificate data for the specified key. If there's no such key, Get returns ErrCacheMiss.

                                  func (*Functional) Put

                                  func (f *Functional) Put(ctx context.Context, key string, data []byte) error

                                    Put stores the data in the cache under the specified key. Underlying implementations may use any data storage format, as long as the reverse operation, Get, results in the original data.

                                    type LayeredCache

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

                                      LayeredCache is an implementation of the autocert.Cache interface. The behavior of the cache consists in checking itself for hits, and having a fall back storage layer to search in the event of a cache miss

                                      func NewLayered

                                      func NewLayered(layers ...autocert.Cache) *LayeredCache

                                        NewLayered returns a new layered cache given autocert.Cache implementations

                                        func NewLayeredWithPolicy

                                        func NewLayeredWithPolicy(wp WritePolicy, layers ...autocert.Cache) *LayeredCache

                                          NewLayeredWithPolicy returns a new layered cache and allows the user to specify the write policy

                                          func (*LayeredCache) Delete

                                          func (c *LayeredCache) Delete(ctx context.Context, key string) error

                                            Delete removes a certificate data from the cache under the specified key. If there's no such key in the cache, Delete returns nil.

                                            func (*LayeredCache) Get

                                            func (c *LayeredCache) Get(ctx context.Context, key string) ([]byte, error)

                                              Get returns a certificate data for the specified key. If there's no such key, Get returns ErrCacheMiss.

                                              func (*LayeredCache) Put

                                              func (c *LayeredCache) Put(ctx context.Context, key string, data []byte) error

                                                Put stores the data in the cache under the specified key. Underlying implementations may use any data storage format, as long as the reverse operation, Get, results in the original data.

                                                type MongoDB

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

                                                  MongoDB represents a MongoDB implementation of autocert.Cache

                                                  func NewMongoDB

                                                  func NewMongoDB(uri string) *MongoDB

                                                    NewMongoDB returns a Mongo cache given a mongodb connection string e.g. fmt.Sprintf("mongodb://%s:%s@%s/%s", username, password, host, db)

                                                    func (*MongoDB) Delete

                                                    func (mgo *MongoDB) Delete(ctx context.Context, key string) error

                                                      Delete removes a certificate data from the cache under the specified key. If there's no such key in the cache, Delete returns nil.

                                                      func (*MongoDB) Get

                                                      func (mgo *MongoDB) Get(ctx context.Context, key string) ([]byte, error)

                                                        Get returns a certificate data for the specified key. If there's no such key, Get returns ErrCacheMiss.

                                                        func (*MongoDB) Put

                                                        func (mgo *MongoDB) Put(ctx context.Context, key string, data []byte) error

                                                          Put stores the data in the cache under the specified key. Underlying implementations may use any data storage format, as long as the reverse operation, Get, results in the original data.

                                                          type S3

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

                                                            S3 represents an AWS S3 implementation of autocert.Cache

                                                            func NewS3

                                                            func NewS3(credentials *credentials.Credentials, bucket, region string) *S3

                                                              NewS3 returns an S3 certificate cache

                                                              func (*S3) Delete

                                                              func (s *S3) Delete(ctx context.Context, key string) error

                                                                Delete removes a certificate data from the cache under the specified key. If there's no such key in the cache, Delete returns nil.

                                                                func (*S3) Get

                                                                func (s *S3) Get(ctx context.Context, key string) ([]byte, error)

                                                                  Get returns a certificate data for the specified key. If there's no such key, Get returns ErrCacheMiss.

                                                                  func (*S3) Put

                                                                  func (s *S3) Put(ctx context.Context, key string, data []byte) error

                                                                    Put stores the data in the cache under the specified key. Underlying implementations may use any data storage format, as long as the reverse operation, Get, results in the original data.

                                                                    type WritePolicy

                                                                    type WritePolicy string

                                                                      WritePolicy determines the order in which the layered cache executes Put

                                                                      Directories

                                                                      Path Synopsis