README
¶
Certify
Certify allows easy automatic certificate distribution and maintenance.
Certificates are requested as TLS connections
are made, courtesy of the GetCertificate and GetClientCertificate
tls.Config hooks. Certificates are optionally cached. Simultaneous requests
are deduplicated to minimize pressure on issuers.
Issuers
Certify exposes an Issuer interface which is used to allow switching
between issuer backends.
Currently implemented issuers:
- Vault PKI Secrets Engine
- Cloudflare CFSSL Certificate Authority
- AWS Certificate Manager Private Certificate Authority
Usage
Create an issuer:
issuer := &vault.Issuer{
URL: &url.URL{
Scheme: "https",
Host: "my-local-vault-instance.com",
},
Token: "myVaultToken",
Role: "myVaultRole",
}
Create a Certify:
c := &certify.Certify{
CommonName: "MyServer.com",
Issuer: issuer,
// It is recommended to use a cache.
Cache: certify.NewMemCache(),
// It is recommended to set RenewBefore.
// Refresh cached certificates when < 24H left before expiry.
RenewBefore: 24*time.Hour,
}
Use in your TLS Config:
tlsConfig := &tls.Config{
GetCertificate: c.GetCertificate,
}
That's it! Both server-side and client-side certificates can be generated:
tlsConfig := &tls.Config{
GetClientCertificate: c.GetClientCertificate,
}
For an end-to-end example using gRPC with mutual TLS authentication, see the Vault tests.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrCacheMiss = errors.New("no matching certificate found")
ErrCacheMiss should be returned by Cache implementations when a certificate could not be found.
Functions ¶
This section is empty.
Types ¶
type Cache ¶
type Cache interface {
// Get returns a certificate data for the specified key.
// If there's no such key, Get returns ErrCacheMiss.
Get(context.Context, string) (*tls.Certificate, error)
// Put stores the data in the cache under the specified key.
Put(context.Context, string, *tls.Certificate) 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.
Delete(context.Context, string) error
}
Cache describes the interface that certificate caches must implement. Cache implementations must be thread safe.
func NewMemCache ¶
func NewMemCache() Cache
NewMemCache creates an in-memory cache that implements the Cache interface.
type CertConfig ¶
CertConfig configures the specifics of the certificate requested from the Issuer.
func (*CertConfig) Clone ¶
func (cc *CertConfig) Clone() *CertConfig
Clone makes a deep copy of the CertConfig.
type Certify ¶
type Certify struct {
// CommonName is the Certificate Common Name
// that will be used when issuing certificates.
// This can be a DNS record or a regular name.
CommonName string
// Issuer is the certificate issuer to use.
Issuer Issuer
// RenewBefore configures how long before
// expiry a certificate should be considered too
// old to use when fetched from the cache.
RenewBefore time.Duration
// Cache is the Cache implementation to use.
Cache Cache
// CertConfig is the certificate configuration that
// should be used. It can be specified to set explicit
// requirements of certificates issued.
CertConfig *CertConfig
// IssueTimeout is the upper bound of time allowed
// per certificate call. Defaults to 1 minute.
IssueTimeout time.Duration
// contains filtered or unexported fields
}
Certify implements automatic certificate acquisition via the configured Issuer.
CommonName and Issuer are required. It is recommended that you specify a Cache to prevent requesting a new certificate for every incoming connection.
func (*Certify) GetCertificate ¶
func (c *Certify) GetCertificate(hello *tls.ClientHelloInfo) (*tls.Certificate, error)
GetCertificate implements the GetCertificate TLS config hook.
func (*Certify) GetClientCertificate ¶
func (c *Certify) GetClientCertificate(_ *tls.CertificateRequestInfo) (*tls.Certificate, error)
GetClientCertificate implements the GetClientCertificate TLS config hook.
type DirCache ¶
type DirCache string
DirCache implements Cache using a directory on the local filesystem. If the directory does not exist, it will be created with 0700 permissions.
It is strongly based on the acme/autocert DirCache type. https://github.com/golang/crypto/blob/88942b9c40a4c9d203b82b3731787b672d6e809b/acme/autocert/cache.go#L40
type Issuer ¶
type Issuer interface {
Issue(context.Context, string, *CertConfig) (*tls.Certificate, error)
}
Issuer is the interface that must be implemented by certificate issuers.
Source Files
Directories