Documentation
¶
Overview ¶
Package localca implements a CA whose state can be stored in a local file or Kubernetes secret.
In substrate's default setup, the CA pool state is kept in a Kubernetes secret, and administered with admin CLI commands.
If you are writing an online signing component, use a projected volume to put the secret's content into your container's filesystem, and then point a RefreshingPool at the file. Even if an administrator rotates the pool, your component will continue to work correctly with no restarts.
If you are writing an admin command, read the secret from the Kubernetes API, use Unmarshal to parse it to a Pool, manipulate the Pool, and then use Marshal to serialize the state and write it back to the secret.
For tests, generate an ephemeral ConcretePool.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Marshal ¶
func Marshal(pool *ConcretePool) ([]byte, error)
Types ¶
type CA ¶
type CA struct {
ID string
// The private key to use for signing certificates. Corresponds to
// RootCertificate.
SigningKey crypto.PrivateKey
// The root certificate for this CA pool.
RootCertificate *x509.Certificate
}
CA is a concrete certificate authority signing from a single root certificate.
In most uses, you want to use a pool of CAs, in order to seamlessly handle CA rotation.
func GenerateCA ¶ added in v0.1.0
GenerateCA creates a self-signed CA with its own freshly generated key.
func (*CA) TLSCertificateChainPEM ¶ added in v0.1.0
TLSCertificateChainPEM returns the CA certificate in the PEM encoding used by TLS servers.
func (*CA) TLSPrivateKeyPEM ¶ added in v0.1.0
TLSPrivateKeyPEM returns the CA signing key in the PKCS#8 PEM encoding used by TLS servers.
type ConcretePool ¶ added in v0.1.0
type ConcretePool struct {
CAs []*CA
// Which CA is active for signing operations?
ActiveForSigning string
}
func Unmarshal ¶
func Unmarshal(wireBytes []byte) (*ConcretePool, error)
func (*ConcretePool) CreateCertificate ¶ added in v0.1.0
func (p *ConcretePool) CreateCertificate(template *x509.Certificate, subjectPublicKey crypto.PublicKey) ([][]byte, error)
func (*ConcretePool) TrustAnchors ¶ added in v0.1.0
func (p *ConcretePool) TrustAnchors() ([]*x509.Certificate, error)
type Pool ¶
type Pool interface {
// CreateCertificate signs the given template certificate using one of the
// Pool's currently-active CAs.
CreateCertificate(template *x509.Certificate, subjectPublicKey crypto.PublicKey) ([][]byte, error)
// TrustAnchors returns the root certificates for all of the pool's CAs.
TrustAnchors() ([]*x509.Certificate, error)
}
Pool is the interface for a CA pool.
Logically, a Pool is a collection of multiple CAs. One or more are designated as active for signing. The rest are inactive, but are still trusted for verifying certificates.
The active/inactive designation allows a Pool to be seamlessly rotated.
- (Steady State) The Pool has one CA, active for signing.
- (Publish New Root) Add a new CA, inactive.
- (Age In) Wait for trust in the new root to propagate throughout the system.
- (Switch) Switch the new CA to be active, and the old CA to be inactive.
- (Age Out) Wait for all certificates issued by the old CA to expire.
- (Cleanup) Remove the old CA from the Pool.
Normally, we let callers define their own compatibility interfaces. But in most cases you'll want to either use a RefreshingPool (for controllers and servers), or a ConcretePool (for CLIs and tests).
type RefreshingPool ¶ added in v0.1.0
type RefreshingPool struct {
// contains filtered or unexported fields
}
RefreshingPool is a wrapper around Pool that periodically reloads the CA state from disk. This allows our various pieces that sign certificates (Actor identity broker, egress gateway) to properly continue signing even as an administrator rotates one of the CA pools, without requiring any components to restart.
func NewRefreshingPool ¶ added in v0.1.0
func NewRefreshingPool(stateFile string) (*RefreshingPool, error)
func (*RefreshingPool) CreateCertificate ¶ added in v0.1.0
func (p *RefreshingPool) CreateCertificate(template *x509.Certificate, subjectPublicKey crypto.PublicKey) ([][]byte, error)
func (*RefreshingPool) TrustAnchors ¶ added in v0.1.0
func (p *RefreshingPool) TrustAnchors() ([]*x509.Certificate, error)
Source Files