tlsfs

README

TLSFS

Filesystem-like manager to provide TLS/SSL certificate creation, renewal and retrieval.

Install

go get -u github.com/wirekit/tlsfs

Examples

Below are examples of creating a tlsfs Filesystem based on using Let's Encrypt as the desired CA authority.

In-Memory Lets Encrypt CA

import (
	"os"

	"github.com/wirekit/tlsfs/fs/memfs"
	"github.com/wirekit/tlsfs/tlsp/acme"
)

var config acme.Config
config.HTTPChallengePort = 3550
config.TLSSNIChallengePort = 4433
config.EnableHTTP01Challenge = true
config.UsersFileSystem = memfs.NewMemFS()
config.CertificatesFileSystem = memfs.NewMemFS()
config.CAURL = "https://acme-v01.api.letsencrypt.org/directory"

service := acme.NewAcmeFS(config)
service.Create("bob@gmail.com", "*.westros.com")

FileSystem Lets Encrypt CA

import (
	"os"

	"github.com/wirekit/tlsfs/fs/sysfs"
	"github.com/wirekit/tlsfs/tlsp/acme"
)

var config acme.Config
config.HTTPChallengePort = 3550
config.TLSSNIChallengePort = 4433
config.EnableHTTP01Challenge = true
config.UsersFileSystem = sysfs.NewSystemZapFS("acme/users")
config.CertificatesFileSystem = sysfs.NewSystemZapFS("acme/certs")
config.CAURL = "https://acme-v01.api.letsencrypt.org/directory"

service := acme.NewAcmeFS(config)
service.Create("bob@gmail.com", "*.westros.com")

Vendoring

Vendoring was done with Dep.

Documentation

Index

• Constants
• Variables
• type Account
• type CertCache
• type CertStore
• type CertificateFunc
• type DomainAccount
• type DomainAccounts
  • func (acd DomainAccounts) Len() int
  • func (acd DomainAccounts) Less(i, j int) bool
  • func (acd DomainAccounts) Swap(i, j int)
• type KeyType
• type NewDomain
• type NotExists
• type Status
  • func WithStatus(flag StatusFlag, reason error) Status
• type StatusFlag
  • func (s StatusFlag) String() string
• type TLSDomainCertificate
• type TLSFS
• type TOSAction
• type ZapFS
• type ZapFile
  • func (zt *ZapFile) Add(name string, data []byte)
  • func (zt *ZapFile) AddTrack(track ZapTrack)
  • func (zt *ZapFile) Find(name string) (ZapTrack, error)
  • func (zt *ZapFile) UnmarshalReader(r io.Reader) error
  • func (zt ZapFile) WriteFlatTo(w io.Writer) (int64, error)
  • func (zt ZapFile) WriteGzippedTo(w io.Writer) (int64, error)
• type ZapTrack
  • func (zt *ZapTrack) UnmarshalBytes(b []byte) error
  • func (zt ZapTrack) WriteTo(w io.Writer) (int64, error)
• type ZapWriter

Constants

const (
	// Live40Weeks sets the duration representing the number of hours in a 40 days period.
	Live40Days = time.Hour * 960

	// Live30Weeks sets the duration representing the number of hours in a 30 days period.
	Live30Days = time.Hour * 720

	// Live2Weeks sets the duration representing the number of hours in all the days in a 2 week period.
	Live2Weeks = time.Hour * 366

	// OneYear sets the duration representing the number of hours in all the days in a year.
	OneYear = time.Hour * 8766

	// ThreeMonths sets the duration of representing the number of hours in a 3 months period.
	ThreeMonths = time.Hour * 2190
)

constants of certificate life-times.

const (
	RSA2048  = KeyType("RSA-2048")
	RSA4096  = KeyType("RSA-4096")
	RSA8192  = KeyType("RSA-8192")
	ECKey256 = KeyType("EC-P256")
	ECKey384 = KeyType("EC-P384")
	ECKey512 = KeyType("EC-P512")
)

constants of key-types

Variables

var (

	// ErrInvalidZapTrackBytes is returned when byte slices differes from zaptrack layout.
	ErrInvalidZapTrackBytes = errors.New("[]byte content is not a valid ZapTrack data")

	// ErrInvalidRead is returned when expected read size is not met by readers .Read() call.
	ErrInvalidRead = errors.New("read failed to match expected header size")

	// ErrNotFound is returned when a giving key has no related value.
	ErrNotFound = errors.New("not found")

	// ErrNotSupported is returned when a feature is not supported by an implementer of
	// an interface.
	ErrNotSupported = errors.New("not supported")

	// ErrExpired is returned when certificate has expired.
	ErrExpired = errors.New("not found")

	// ErrNoEmailProvided is returned when the domain desired provides no valid email.
	ErrNoEmailProvided = errors.New("request has no email")

	// ErrNoCommonName is returned when the domain CommonName is not provided.
	ErrNoCommonName = errors.New("no valid common name provided")

	// ErrInvalidDomain is returned when the domain desired is invalid
	ErrInvalidDomain = errors.New("domain value is invalid")

	// ErrCertificateHasNoBundle is returned when the domain desired is invalid
	ErrErrCertificateHasNoBundle = errors.New("domain certificate has no bundled data")
)

Types

type Account

type Account interface {
	GetEmail() string
	GetPrivateKey() crypto.PrivateKey
}

Account defines a type which represents a given registered user from a acme.

type CertCache

type CertCache interface {
	Delete(domain string) error
	Get(domain string) (tls.Certificate, error)
	Save(domain string, cert tls.Certificate) error
}

CertCache defines an interface which exposes a method to cache certificates through given domain name.

type CertStore

type CertStore interface {
	RemoveUser(string) error
	AddUser(account Account) error
	RemoveDomain(string, string) error
	GetUser(string) (DomainAccount, error)
	AddDomain(string, TLSDomainCertificate, bool) error
	GetCertificate(string, string) (TLSDomainCertificate, error)
}

CertStore defines an interface which exposes methods to save and retrieve certificates based on Accounts and domain.

type CertificateFunc

type CertificateFunc func(*tls.ClientHelloInfo) (*tls.Certificate, error)

CertificateFunc defines a function type which returns a certificate for a giving tls.ClientHelloInfo.

type DomainAccount

type DomainAccount struct {
	Acct    Account
	Domains []TLSDomainCertificate
}

DomainAccount defines a struct which relates a set of registered domain certificates to an existing user account.

type DomainAccounts

type DomainAccounts []DomainAccount

DomainAccounts defines a slice type of DomainAccount objects and implements the sort.Sort interface.

func (DomainAccounts) Len

func (acd DomainAccounts) Len() int

func (DomainAccounts) Less

func (acd DomainAccounts) Less(i, j int) bool

func (DomainAccounts) Swap

func (acd DomainAccounts) Swap(i, j int)

type KeyType

type KeyType string

KeyType defines the custom key-type acceptable for user private key generation.

type NewDomain

type NewDomain struct {
	Email      string  `json:"email" description:"email for certificate user"`
	KeyType    KeyType `json:"type" description:"key type for private key"`
	Domain     string  `json:"domain" description:"domain for certificate creation"`
	CommonName string  `json:"common_name" description:"common name for certificate must not be empty else put '*'"`

	// Optional fields providing extra meta-data, most CA implementers especially like
	// LetsEncrypt, who will not necessarily use these in its process.
	Version  int      `json:"version" description:"version to be used for generated certificate"`
	Country  string   `json:"country" description:"country of owner of certificate"`
	Province string   `json:"province" description:"province of owner of certificate"`
	Local    string   `json:"local" description:"locality of owner of certificate"`
	Address  string   `json:"address" description:"address of owner of certificate"`
	Postal   string   `json:"postal" description:"postal address for certificate"`
	DNSNames []string `json:"dns_names" description:"SNI-compliant names to be added to certificate request"`
}

NewDomain defines the data which is supplied for the creation of certificates for a given user identified by it's email.

type NotExists

type NotExists interface {
	error
	NotExists()
}

NotExists is define to provide a clear distinct means of identify a given error has one that relates to the non-existence of a desired find. It provides a more robust approach to dealing with existence/non-existence errors instead of evaluating the equality of a declared error to another.

type Status

type Status interface {
	// Reason returns an error if such occured about the non-critical
	// failure of a creation/renewal of a certificate requests.
	Reason() error

	// Flag returns the status flag representing the status of
	// a certificate creation/renewal.
	Flag() StatusFlag
}

Status defines a interface type that exposes a method to return the status flag of a giving certificate.

func WithStatus

func WithStatus(flag StatusFlag, reason error) Status

WithStatus returns a StatusFlag with provided flag.

type StatusFlag

type StatusFlag int8

StatusFlag defines a int type indicating the status of a flag creation/renewal/removal state.

const (
	// OPFailed represents the critical state of a request for the creation/renewal or removal of
	// a existing certificate either with CA or underline file system.
	OPFailed StatusFlag = iota + 1

	// CACExpired represents the state where a certificate is totally expired.
	CACExpired

	// CARenewalCriticalExpiration states the certificate to have failed renewal
	// and lies below two weeks expiration limit and requires user actions due to an
	// unexpected error.
	CARenewalCriticalExpiration

	// CARenewalEarlyExpiration states the certificate to have fallen into the
	// 30-days expiration limit and renewal had failed due to unknown CA reasons
	// that require manual user action.
	CARenewalEarlyExpiration

	// CACriticalRenewedRequired states the given certificates requires immediate renewal
	// from it's CA on a critical level where it is below or around 2 weeks to expiration.
	CACriticalRenewedRequired

	// CARenewedRequired states the given certificates requires immediate renewal
	// from it's CA.
	CARenewedRequired

	// Renewed is the state returned when a renewed operation succeeded for a
	// existing certificate.
	Renewed

	// Created is the state returned when the new certificate request succeeded.
	Created

	// Live is returned when a giving certificate is still in good shape for use.
	Live
)

func (StatusFlag) String

func (s StatusFlag) String() string

String returns the a short phrase suitable for the giving status flag number.

type TLSDomainCertificate

type TLSDomainCertificate struct {
	IsSubCA           bool                     `json:"is_ca" description:"is_ca indicates if certificate is a sub CA."`
	User              string                   `json:"acct" description:"acct email related to the domain user"`
	Domain            string                   `json:"domain" description:"domain generated certificate"`
	Certificate       *x509.Certificate        `json:"certificate" description:"certificate generate for request and account"`
	IssuerCertificate *x509.Certificate        `json:"issuer_certificate" description:"issuer/CA certificate bundled with generate certificate"`
	Request           *x509.CertificateRequest `json:"req" description:"certificate request to build certificate"`
	Bundle            interface{}              `json:"bundle" description:"certificate bundle received from issuer/CA"`
}

TLSDomainCertificate defines a giving structure which holds generated certificates with associated tls.Certificates received from

type TLSFS

type TLSFS interface {
	All() ([]DomainAccount, error)
	GetUser(email string) (Account, error)
	Revoke(email string, domain string) error
	GetCertificate(email string) CertificateFunc
	Get(email string, domain string) (TLSDomainCertificate, Status, error)
	Renew(email string, domain string) (TLSDomainCertificate, Status, error)
	Create(account NewDomain, action TOSAction) (TLSDomainCertificate, Status, error)
	CreateCA(account NewDomain, action TOSAction) (TLSDomainCertificate, Status, error)
	CreateWithCSR(req x509.CertificateRequest, action TOSAction) (TLSDomainCertificate, Status, error)
}

TLSFS defines an interface which exposes methods to create tls certificates from a given root CA and have the underline certificates be stored within a underline ZapFS.

type TOSAction

type TOSAction func(tosURL string) bool

TOSAction defines a function called to receive user response towards the need to agree to a CA Terms of service.

var AgreeToTOS TOSAction = func(_ string) bool { return true }

AgreeToTOS defines a variable which implements the TOSAction interface. It always returns true to agree to a TOS action request.

type ZapFS

type ZapFS interface {
	Remove(string) error
	WriteFile(ZapFile) error
	ReadAll() ([]ZapFile, error)
	Read(string) (ZapFile, error)
	Write(string) (ZapWriter, error)
}

ZapFS defines an interface that exposes a filesystem to power the storage/retrieval of tls certificates with ease.

type ZapFile

type ZapFile struct {
	Name   string
	Tracks []ZapTrack
	// contains filtered or unexported fields
}

ZapFile defines a internal file format that stores all internal tracks as a single, gzipped compressed file format.

func (*ZapFile) Add

func (zt *ZapFile) Add(name string, data []byte)

Add adds giving name and data as a ZapTrack for the giving ZapFile.

func (*ZapFile) AddTrack

func (zt *ZapFile) AddTrack(track ZapTrack)

AddTrack adds provided track into the giving ZapFile tracks.

func (*ZapFile) Find

func (zt *ZapFile) Find(name string) (ZapTrack, error)

Find attempts to find giving ZapTrack with associated name.

func (*ZapFile) UnmarshalReader

func (zt *ZapFile) UnmarshalReader(r io.Reader) error

UnmarshalReader takes a giving reader and attempts to decode it's content has a ZapFile either compressed or uncompressed.

func (ZapFile) WriteFlatTo

func (zt ZapFile) WriteFlatTo(w io.Writer) (int64, error)

WriteFlatTo writes the data of a ZapFile without any compression into provided writer.

func (ZapFile) WriteGzippedTo

func (zt ZapFile) WriteGzippedTo(w io.Writer) (int64, error)

WriteGzippedTo writes the data of a ZapFile with gzip compression into provided writer.

type ZapTrack

type ZapTrack struct {
	Name string
	Data []byte
}

ZapTrack defines a structure which defines a giving data track of a continuous-single-lined file data track. It represent a single data entity which is represented as a single file by the ZapFile format.

func (*ZapTrack) UnmarshalBytes

func (zt *ZapTrack) UnmarshalBytes(b []byte) error

UnmarshalBytes takes giving bytes validating its's content to match the ZapTrack layout format, then setting it's Fields to appropriate contents of the data.

func (ZapTrack) WriteTo

func (zt ZapTrack) WriteTo(w io.Writer) (int64, error)

WriteTo implements the io.WriterTo taht writes the contents of a ZapTrack as a uncompressed data stream with appropriate header information regarding the data.

type ZapWriter

type ZapWriter interface {
	Flush() error
	Add(string, []byte) error
}

ZapWriter defines an interface which returns a set of methods to add a series of byte slice with associated names to a underline zap filesystem.