certstore

README

Go library for creation and maintenance of X.509 certificate stores

License

This project is subject to the the MIT License. See LICENSE information for details.

Documentation

Overview

Package certstore provides functionality for creation and mantainenace of X.509 certificate stores.

Index

• Variables
• type ExportFormat
• type ExportOption
• type Registry
  • func NewStore(backend storage.Backend, cacheTTL time.Duration) (*Registry, error)
  • func NewStoreFromURI(uri string, basePath string) (*Registry, error)
  • func (registry *Registry) CertPools() (*x509.CertPool, *x509.CertPool, error)
  • func (registry *Registry) CreateCertificate(name string, factory certs.CertificateFactory, user string) (string, error)
  • func (registry *Registry) CreateCertificateRequest(name string, factory certs.CertificateRequestFactory, user string) (string, error)
  • func (registry *Registry) Delete(name string, user string) error
  • func (registry *Registry) Entries() (*RegistryEntries, error)
  • func (registry *Registry) Entry(name string) (*RegistryEntry, error)
  • func (registry *Registry) Merge(other *Registry, user string) error
  • func (registry *Registry) MergeCertificate(name string, certificate *x509.Certificate, user string) (string, bool, error)
  • func (registry *Registry) MergeCertificateRequest(name string, certificateRequest *x509.CertificateRequest, user string) (string, bool, error)
  • func (registry *Registry) MergeKey(name string, key crypto.PrivateKey, user string) (string, bool, error)
  • func (registry *Registry) MergeRevocationList(name string, revocationList *x509.RevocationList, user string) (string, bool, error)
  • func (registry *Registry) Name() string
• type RegistryEntries
  • func (entries *RegistryEntries) Find(match func(entry *RegistryEntry) bool) (*RegistryEntry, error)
  • func (entries *RegistryEntries) Next() (*RegistryEntry, error)
• type RegistryEntry
  • func (entry *RegistryEntry) Attributes() map[string]string
  • func (entry *RegistryEntry) CanIssue(keyUsage x509.KeyUsage) bool
  • func (entry *RegistryEntry) Certificate() *x509.Certificate
  • func (entry *RegistryEntry) CertificateRequest() *x509.CertificateRequest
  • func (entry *RegistryEntry) Export(out io.Writer, format ExportFormat, option ExportOption, password string, ...) error
  • func (entry *RegistryEntry) HasCertificate() bool
  • func (entry *RegistryEntry) HasCertificateRequest() bool
  • func (entry *RegistryEntry) HasKey() bool
  • func (entry *RegistryEntry) HasRevocationList() bool
  • func (entry *RegistryEntry) IsCA() bool
  • func (entry *RegistryEntry) IsRoot() bool
  • func (entry *RegistryEntry) Key(user string) crypto.PrivateKey
  • func (entry *RegistryEntry) Name() string
  • func (entry *RegistryEntry) ResetRevocationList(factory certs.RevocationListFactory, user string) (*x509.RevocationList, error)
  • func (entry *RegistryEntry) RevocationList() *x509.RevocationList
  • func (entry *RegistryEntry) SetAttributes(attributes map[string]string) error

Variables

var ErrInvalidIssuer = errors.New("invalid issuer certificate")

var ErrNoCertificate = errors.New("no certificate")

var ErrNoKey = errors.New("no key")

Types

type ExportFormat

type ExportFormat interface {
	Name() string
	ContentType() string
	CanExport(certificate *x509.Certificate, chain []*x509.Certificate, key crypto.PrivateKey) error
	Export(out io.Writer, certificate *x509.Certificate, chain []*x509.Certificate, key crypto.PrivateKey, password string) error
}

var ExportFormatDER ExportFormat = &exportFormatDER{}

var ExportFormatPEM ExportFormat = &exportFormatPEM{}

var ExportFormatPKCS12 ExportFormat = &exportFormatPKCS12{}

type ExportOption

type ExportOption int

const (
	ExportOptionKey       ExportOption = 1 << 0
	ExportOptionChain     ExportOption = 1 << 1
	ExportOptionFullChain ExportOption = ExportOptionChain | (1 << 2)
	ExportOptionDefault   ExportOption = ExportOptionKey | ExportOptionChain
)

type Registry

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

A Registry represents a X.509 certificate store.

func NewStore

func NewStore(backend storage.Backend, cacheTTL time.Duration) (*Registry, error)

NewStore creates a certificate store using the submitted storage backend and parameters.

If the submitted storage location is used for the first time, a new certificate store is setup. Using the same storage location again, opens the previously created certificate store.

func NewStoreFromURI

func NewStoreFromURI(uri string, basePath string) (*Registry, error)

NewStoreFromURI creates a certificate store based upon the submitted uri and base path.

Supported uri formats are:

1. memory://<?parameters> (e.g. memory://?cache_ttl=60s&version_limit=10)
2. fs://<path><?parameters> (e.g. fs://./certs?cache_ttl=60s&version_limit=10)

Relative paths are evaluated using the submitted base path.

Known uri parameters are:

1. cache_ttl: The cache ttl (see time.ParseDuration)
1. cache_ttl: The version limit (see time.ParseUint)

See NewStore for further details.

func (*Registry) CertPools

func (registry *Registry) CertPools() (*x509.CertPool, *x509.CertPool, error)

CertPools wraps this store's entries into a x509.CertPool.

The first returned pool contains the root certificates. The second on the intermediate certificates.

func (*Registry) CreateCertificate

func (registry *Registry) CreateCertificate(name string, factory certs.CertificateFactory, user string) (string, error)

CreateCertificate creates a new X.509 certificate using the provided certs.CertificateFactory.

The name of the created store entry is returned. The returned name is derived from the submitted name, by making it unique. Means, if the submitted name is not already in use, it is returned as is. Otherwise it is made unique by appending a suffix.

Invoking this function is recorded in the audit log using the the submitted user name.

func (*Registry) CreateCertificateRequest

func (registry *Registry) CreateCertificateRequest(name string, factory certs.CertificateRequestFactory, user string) (string, error)

CreateCertificateRequest creates a new X.509 certificate request using the provided certs.CertificateRequestFactory.

The name of the created store entry is returned. The returned name is derived from the submitted name, by making it unique. Means, if the submitted name is not already in use, it is returned as is. Otherwise it is made unique by appending a suffix.

Invoking this function is recorded in the audit log using the the submitted user name.

func (*Registry) Delete

func (registry *Registry) Delete(name string, user string) error

Delete deletes the entry with the submitted name from the store.

If the submitted name does not exist, storage.ErrNotExist is returned.

func (*Registry) Entries

func (registry *Registry) Entries() (*RegistryEntries, error)

Entries lists all entries of the store.

The returned RegistryEntries collection is sorted in lexical order and backed up by the store. Deleting a store entry after querying the RegistryEntries collection will cause a storage.ErrNotExist whenever the deleted entry is traversed.

func (*Registry) Entry

func (registry *Registry) Entry(name string) (*RegistryEntry, error)

Entry looks up the entry with the submitted name in the store.

If the submitted name does not exist, storage.ErrNotExist is returned.

func (*Registry) Merge

func (registry *Registry) Merge(other *Registry, user string) error

Merge merges another X.509 certificate store into the store.

The submitted store is merged by merging each of its entries individually.

Invoking this function is recorded in the audit log using the the submitted user name.

func (*Registry) MergeCertificate

func (registry *Registry) MergeCertificate(name string, certificate *x509.Certificate, user string) (string, bool, error)

MergeCertificate merges a X.509 certificate into the store.

If the certfiicate is already in the store, the name of the existing store entry as well as false is returned. If the certificate is not yet in the store, it is added and name of the added store entry as well as true is returned. Like for [CreateCertificate] the submitted name is used to derive the name of the added store entry.

Invoking this function is recorded in the audit log using the the submitted user name.

func (*Registry) MergeCertificateRequest

func (registry *Registry) MergeCertificateRequest(name string, certificateRequest *x509.CertificateRequest, user string) (string, bool, error)

MergeCertificateRequest merges a X.509 certificate request into the store.

If the certfiicate request is already in the store, the name of the existing store entry as well as false is returned. If the certificate request is not yet in the store, it is added and name of the added store entry as well as true is returned. Like for [CreateCertificateRequest] the submitted name is used to derive the name of the added store entry.

Invoking this function is recorded in the audit log using the the submitted user name.

func (*Registry) MergeKey

func (registry *Registry) MergeKey(name string, key crypto.PrivateKey, user string) (string, bool, error)

MergeKey merges a X.509 certificate key into the store.

If the certfiicate key is already in the store, the name of the existing store entry as well as false is returned. If the certificate key is not yet in the store, it is added and name of the added store entry as well as true is returned. Like for [CreateCertificate] the submitted name is used to derive the name of the added store entry.

Invoking this function is recorded in the audit log using the the submitted user name.

func (*Registry) MergeRevocationList

func (registry *Registry) MergeRevocationList(name string, revocationList *x509.RevocationList, user string) (string, bool, error)

MergeRevocationList merges a X.509 certificate revocation list into the store.

If the revocation list is already in the store, the name of the existing store entry as well as false is returned. If the revocation list is not yet in the store, it is added and name of the added store entry as well as true is returned. Like for [CreateCertificate] the submitted name is used to derive the name of the added store entry.

Invoking this function is recorded in the audit log using the the submitted user name.

func (*Registry) Name

func (registry *Registry) Name() string

Name gets the registry name which is derived from the registry's storage location.

type RegistryEntries

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

RegistryEntries represents a traversable collection of store entries.

func (*RegistryEntries) Find

func (entries *RegistryEntries) Find(match func(entry *RegistryEntry) bool) (*RegistryEntry, error)

Find looks up the next store entry in the collection matching the submitted match function.

nil is returned if the none of the remaining store entries matches.

func (*RegistryEntries) Next

func (entries *RegistryEntries) Next() (*RegistryEntry, error)

Next gets the next store entry in the collection.

nil is returned if the collection is exausted.

type RegistryEntry

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

RegistryEntry represents a single store entry.

func (*RegistryEntry) Attributes

func (entry *RegistryEntry) Attributes() map[string]string

Attributes gets the attributes (key value pairs) associated with the store entry.

func (*RegistryEntry) CanIssue

func (entry *RegistryEntry) CanIssue(keyUsage x509.KeyUsage) bool

CanIssue determines if this store entry can be used to issue new certificates for the submitted key usage.

I order to be able to issue new certificates a store entry must match the following prerequisites:

1. entry contains certificate ([HasCertificate]) and key ([HasKey])
2. the contained certificate must have a valid BasicConstraints extension (x509.Certificate.BasicConstraintsValid)
3. the contained certificate must be marked as a CA ([IsCA])
4. the contained certificate's key usage matches the submitted one.

func (*RegistryEntry) Certificate

func (entry *RegistryEntry) Certificate() *x509.Certificate

Certificate gets the store entry's certificate.

nil is returned if the store entry does not contain a certificate.

func (*RegistryEntry) CertificateRequest

func (entry *RegistryEntry) CertificateRequest() *x509.CertificateRequest

CertificateRequest gets the store entry's certificate request.

nil is returned if the store entry does not contain a certificate request.

func (*RegistryEntry) Export

func (entry *RegistryEntry) Export(out io.Writer, format ExportFormat, option ExportOption, password string, user string) error

func (*RegistryEntry) HasCertificate

func (entry *RegistryEntry) HasCertificate() bool

HasCertificate reports whether this store entry contains a certificate.

func (*RegistryEntry) HasCertificateRequest

func (entry *RegistryEntry) HasCertificateRequest() bool

HasCertificateRequest reports whether this store entry contains a certificate request.

func (*RegistryEntry) HasKey

func (entry *RegistryEntry) HasKey() bool

HasKey reports whether this store entry contains a key.

func (*RegistryEntry) HasRevocationList

func (entry *RegistryEntry) HasRevocationList() bool

HasRevocationList reports whether this store entry contains a revocation list.

func (*RegistryEntry) IsCA

func (entry *RegistryEntry) IsCA() bool

IsCA reports whether this store entry represents a certificate authority.

A store entry represents a certificate authoritiy if it contains a certificate and the latter is entitled to sign certifictes.

func (*RegistryEntry) IsRoot

func (entry *RegistryEntry) IsRoot() bool

IsRoot reports whether this store entry represents a root certificate.

A store entry represents a root certificate if it contains a certificate and the latter is self-signed.

func (*RegistryEntry) Key

func (entry *RegistryEntry) Key(user string) crypto.PrivateKey

Key gets the store entry's key.

nil is returned if the store entry does not contain a key.

Invoking this function is recorded in the audit log using the the submitted user name.

func (*RegistryEntry) Name

func (entry *RegistryEntry) Name() string

Name gets the name of the store entry.

func (*RegistryEntry) ResetRevocationList

func (entry *RegistryEntry) ResetRevocationList(factory certs.RevocationListFactory, user string) (*x509.RevocationList, error)

ResetRevocationList resets the store entry's revocation list using the submitted certs.RevocationListFactory.

The newly created x509.RevocationList is returned. If the store entry is not suitable for signing a revocation list, ErrInvalidIssuer is returned.

Invoking this function is recorded in the audit log using the the submitted user name.

func (*RegistryEntry) RevocationList

func (entry *RegistryEntry) RevocationList() *x509.RevocationList

RevocationList gets the store entry's revocation list.

nil is returned if the store entry does not contain a revocation list.

func (*RegistryEntry) SetAttributes

func (entry *RegistryEntry) SetAttributes(attributes map[string]string) error

SetAttributes sets the attributes (key value pairs) associated with the store entry.

Any previously set attributes are overwritten or removed if no longer defined.