Documentation
¶
Overview ¶
Package dcert contains types for dealing with x509 certificates in the context of dragon.
Index ¶
- Constants
- Variables
- type CACertHandle
- type Chain
- func (c Chain) All() iter.Seq[*x509.Certificate]
- func (c *Chain) BuildHandles()
- func (c *Chain) Decode(r io.Reader) error
- func (c Chain) Encode(w io.Writer) error
- func (c Chain) EncodedSize() int
- func (c Chain) Len() int
- func (c *Chain) Mutable() iter.Seq[MutableCert]
- func (c Chain) Validate() error
- type LeafCertHandle
- type MutableCert
- type Pool
Constants ¶
const MaxIntermediateLen = 7
A Chain may have up to 7 intermediate entries, in addition to its leaf and root certificates.
Seven was a mostly arbitrary choice. It seems generous enough for any practical chain, and seven can be represented in only 3 bits, if we need to pack that length with anything else.
Variables ¶
var ErrCertRemoved = errors.New("certificate removed from trusted set")
ErrCertRemoved is returned when a live connection to a peer is interrupted due to the peer's CA being removed from the trusted peers.
Functions ¶
This section is empty.
Types ¶
type CACertHandle ¶
CACertHandle is a handle representing a certificate. The handle can be used as map keys or for other trivial comparisons. This is a separate type from LeafCertHandle to reduce the likelihood of mistakenly swapping the two types.
func (CACertHandle) String ¶
func (h CACertHandle) String() string
type Chain ¶
type Chain struct {
Leaf *x509.Certificate
Intermediate []*x509.Certificate
Root *x509.Certificate
LeafHandle LeafCertHandle
RootHandle CACertHandle
}
Chain represents a certificate chain, with slightly stronger typing contextual to dragon compared to a simple slice of *x509.Certificate. It also contains a "handle" to the leaf and root certificates which are intended to be used as map keys, as many use cases involve retaining a map of connections keyed by certificate.
A Chain in dragon is required to have a non-nil leaf and root, but intermediate may have up to seven entries.
Since a Chain itself only contains reference values, a Chain is typically passed by value, not by reference.
Due to the handle fields, callers should use NewChainFromCerts or NewChainFromTLSConnectionState to create a Chain. Alternatively, set the Leaf and Root fields and optionally the Intermediate field and then call *Chain.BuildHandles before using the Chain.
func NewChainFromCerts ¶
func NewChainFromCerts(certs []*x509.Certificate) (Chain, error)
NewChainFromCerts returns a Chain from the given slice of certificates.
func NewChainFromTLSConnectionState ¶
func NewChainFromTLSConnectionState(s tls.ConnectionState) (Chain, error)
func (Chain) All ¶
func (c Chain) All() iter.Seq[*x509.Certificate]
All returns an iterator over every certificate in c, starting with the leaf and ending with the root.
func (*Chain) BuildHandles ¶
func (c *Chain) BuildHandles()
BuildHandles sets the LeafHandle and RootHandle fields. This is only required to call if manually creating a chain by setting the Leaf and Root fields; it happens automatically if using NewChainFromCerts or NewChainFromTLSConnectionState.
func (Chain) EncodedSize ¶
func (Chain) Len ¶
Len returns the total number of certificates in the chain. Due to the limit of 7 intermediate certificates, the returned value for a valid chain will be in range [2,9].
type LeafCertHandle ¶
LeafCertHandle is a handle representing a certificate. The handle can be used as map keys or for other trivial comparisons. This is a separate type from CACertHandle to reduce the likelihood of mistakenly swapping the two types.
func (LeafCertHandle) String ¶
func (h LeafCertHandle) String() string
type MutableCert ¶
type MutableCert struct {
// contains filtered or unexported fields
}
MutableCert is a mutable certificate within the chain.
func (MutableCert) Set ¶
func (mc MutableCert) Set(cert *x509.Certificate)
Set sets the mutable certificate to the given certificate.
type Pool ¶
type Pool struct {
// contains filtered or unexported fields
}
Pool is a collection of CA certificates.
func NewPool ¶
func NewPool() *Pool
NewPool returns a new pool that does not contain any trusted certificates yet.
func NewPoolFromCerts ¶
func NewPoolFromCerts(certs []*x509.Certificate) *Pool
NewPoolFromCerts returns a new pool trusting the given certificates.
func (*Pool) AddCA ¶
func (p *Pool) AddCA(cert *x509.Certificate)
AddCA adds a single CA certificate to the pool. Prefer to use [(*Pool).UpdateCAs].
func (*Pool) CertPool ¶
CertPool returns the underlying certificate pool. This pool is shared until p's CA set changes, so the returned value must not be modified.
func (*Pool) NotifyRemoval ¶
func (p *Pool) NotifyRemoval(cert *x509.Certificate) <-chan struct{}
NotifyRemoval returns a channel that is closed if and when the given CA is removed from the pool, either directly through a call to [(*Pool).RemoveCA] or indirectly by not being part of the new set in [(*Pool).UpdateCAs].
func (*Pool) RemoveCA ¶
func (p *Pool) RemoveCA(cert *x509.Certificate)
RemoveCA removes the given certificate from the pool. Prefer to use [(*Pool).UpdateCAs].
func (*Pool) UpdateCAs ¶
func (p *Pool) UpdateCAs(certs []*x509.Certificate)
UpdateCAs replaces the entire CA set with the given certs.
Source Files
Directories