certstore

package module
v0.0.13 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 13, 2025 License: MIT Imports: 23 Imported by: 0

README

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

GoDoc Build Coverage Go Report Card

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

Constants

This section is empty.

Variables

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

An ErrInvalidIssuer error indicates the given certificate is not suitable for the requested signing operation.

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

An ErrNoCertificate error indicates a missing certificate.

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

An ErrNoKey error indicates a missing key.

Functions

This section is empty.

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 MergeResult added in v0.0.11 

type MergeResult struct {
	Name                     string
	Status                   MergeStatus
	CertificateStatus        MergeStatus
	CertificateRequestStatus MergeStatus
	KeyStatus                MergeStatus
	RevocationListStatus     MergeStatus
}

type MergeStatus added in v0.0.11 

type MergeStatus int

A MergeStatus shows the result of a merge operation. 

const (
	// MergeStatusNone indicates nothing to merge.
	MergeStatusNone MergeStatus = -1
	// MergeStatusNew indicates the merged security object is not related to any store entry (and therefore part of new store entry).
	MergeStatusNew MergeStatus = 0
	// MergeStatusAdd indicates the merged security object is related a store entry, but not yet known (and therefor added during a merge).
	MergeStatusAdd MergeStatus = 1
	// MergeStatusExists indicates the merged security object already exists in the store.
	MergeStatusExists MergeStatus = 2
)

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)
  2. version_limit: The version limit (see strconv.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, commit bool) ([]MergeResult, 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, commit bool) (string, MergeStatus, error)

MergeCertificate merges a X.509 certificate into the store.

Whether the merge is made permanent or not, is controlled by the given commit flag. If a store entry related to submitted certfiicate is already in the store, the name of the existing store entry is returned. Otherwise a new entry is created using the the given name. The returned merge status shows the exact result of the merge. 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, commit bool) (string, MergeStatus, error)

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

Whether the merge is made permanent or not, is controlled by the given commit flag. If a store entry related to submitted certfiicate request is already in the store, the name of the existing store entry is returned. Otherwise a new entry is created using the the given name. The returned merge status shows the exact result of the merge. 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, commit bool) (string, MergeStatus, error)

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

Whether the merge is made permanent or not, is controlled by the given commit flag. If a store entry related to submitted certfiicate key is already in the store, the name of the existing store entry is returned. Otherwise a new entry is created using the the given name. The returned merge status shows the exact result of the merge. 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, commit bool) (string, MergeStatus, error)

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

Whether the merge is made permanent or not, is controlled by the given commit flag. If a store entry related to submitted certfiicate revocation list is already in the store, the name of the existing store entry is returned. Otherwise a new entry is created using the the given name. The returned merge status shows the exact result of the merge. 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.

Source Files

View all Source files

Directories

Path Synopsis
Package certs provides functions for X.509 certificate management.
 Package certs provides functions for X.509 certificate management.
acme
Package acme provides [LEGO] related utility functions.
 Package acme provides [LEGO] related utility functions.
Package keys implements a unified interface for key handling.
 Package keys implements a unified interface for key handling.
Package storage provides different backends for versioned data storage.
 Package storage provides different backends for versioned data storage.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.