caddypki

Documentation

Index

• Constants
• type AuthorityConfig
• type CA
  • func (ca CA) IntermediateCertificate() *x509.Certificate
  • func (ca CA) IntermediateKey() any
  • func (ca *CA) NewAuthority(authorityConfig AuthorityConfig) (*authority.Authority, error)
  • func (ca *CA) Provision(ctx caddy.Context, id string, log *zap.Logger) error
  • func (ca CA) RootCertificate() *x509.Certificate
  • func (ca CA) RootKey() (any, error)
• type KeyPair
  • func (kp KeyPair) Load() (*x509.Certificate, crypto.Signer, error)
• type PKI
  • func (PKI) CaddyModule() caddy.ModuleInfo
  • func (p *PKI) GetCA(ctx caddy.Context, id string) (*CA, error)
  • func (p *PKI) Provision(ctx caddy.Context) error
  • func (p *PKI) ProvisionDefaultCA(ctx caddy.Context) error
  • func (p *PKI) Start() error
  • func (p *PKI) Stop() error

Constants

const (
	// DefaultCAID is the default CA ID.
	DefaultCAID = "local"
)

Types

type AuthorityConfig

type AuthorityConfig struct {
	SignWithRoot bool

	// TODO: should we just embed the underlying authority.Config struct type?
	DB         *db.AuthDB
	AuthConfig *authority.AuthConfig
}

AuthorityConfig is used to help a CA configure the underlying signing authority.

type CA

type CA struct {
	// The user-facing name of the certificate authority.
	Name string `json:"name,omitempty"`

	// The name to put in the CommonName field of the
	// root certificate.
	RootCommonName string `json:"root_common_name,omitempty"`

	// The name to put in the CommonName field of the
	// intermediate certificates.
	IntermediateCommonName string `json:"intermediate_common_name,omitempty"`

	// The lifetime for the intermediate certificates
	IntermediateLifetime caddy.Duration `json:"intermediate_lifetime,omitempty"`

	// Whether Caddy will attempt to install the CA's root
	// into the system trust store, as well as into Java
	// and Mozilla Firefox trust stores. Default: true.
	InstallTrust *bool `json:"install_trust,omitempty"`

	// The root certificate to use; if null, one will be generated.
	Root *KeyPair `json:"root,omitempty"`

	// The intermediate (signing) certificate; if null, one will be generated.
	Intermediate *KeyPair `json:"intermediate,omitempty"`

	// Optionally configure a separate storage module associated with this
	// issuer, instead of using Caddy's global/default-configured storage.
	// This can be useful if you want to keep your signing keys in a
	// separate location from your leaf certificates.
	StorageRaw json.RawMessage `json:"storage,omitempty" caddy:"namespace=caddy.storage inline_key=module"`

	// The unique config-facing ID of the certificate authority.
	// Since the ID is set in JSON config via object key, this
	// field is exported only for purposes of config generation
	// and module provisioning.
	ID string `json:"-"`
	// contains filtered or unexported fields
}

CA describes a certificate authority, which consists of root/signing certificates and various settings pertaining to the issuance of certificates and trusting them.

func (CA) IntermediateCertificate

func (ca CA) IntermediateCertificate() *x509.Certificate

IntermediateCertificate returns the CA's intermediate certificate (public key).

func (CA) IntermediateKey

func (ca CA) IntermediateKey() any

IntermediateKey returns the CA's intermediate private key.

func (*CA) NewAuthority

func (ca *CA) NewAuthority(authorityConfig AuthorityConfig) (*authority.Authority, error)

NewAuthority returns a new Smallstep-powered signing authority for this CA. Note that we receive *CA (a pointer) in this method to ensure the closure within it, which executes at a later time, always has the only copy of the CA so it can access the latest, renewed certificates since NewAuthority was called. See #4517 and #4669.

func (*CA) Provision

func (ca *CA) Provision(ctx caddy.Context, id string, log *zap.Logger) error

Provision sets up the CA.

func (CA) RootCertificate

func (ca CA) RootCertificate() *x509.Certificate

RootCertificate returns the CA's root certificate (public key).

func (CA) RootKey

func (ca CA) RootKey() (any, error)

RootKey returns the CA's root private key. Since the root key is not cached in memory long-term, it needs to be loaded from storage, which could yield an error.

type KeyPair

type KeyPair struct {
	// The certificate. By default, this should be the path to
	// a PEM file unless format is something else.
	Certificate string `json:"certificate,omitempty"`

	// The private key. By default, this should be the path to
	// a PEM file unless format is something else.
	PrivateKey string `json:"private_key,omitempty"`

	// The format in which the certificate and private
	// key are provided. Default: pem_file
	Format string `json:"format,omitempty"`
}

KeyPair represents a public-private key pair, where the public key is also called a certificate.

func (KeyPair) Load

func (kp KeyPair) Load() (*x509.Certificate, crypto.Signer, error)

Load loads the certificate and key.

type PKI

type PKI struct {
	// The certificate authorities to manage. Each CA is keyed by an
	// ID that is used to uniquely identify it from other CAs.
	// At runtime, the GetCA() method should be used instead to ensure
	// the default CA is provisioned if it hadn't already been.
	// The default CA ID is "local".
	CAs map[string]*CA `json:"certificate_authorities,omitempty"`
	// contains filtered or unexported fields
}

PKI provides Public Key Infrastructure facilities for Caddy.

This app can define certificate authorities (CAs) which are capable of signing certificates. Other modules can be configured to use the CAs defined by this app for issuing certificates or getting key information needed for establishing trust.

func (PKI) CaddyModule

func (PKI) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*PKI) GetCA

func (p *PKI) GetCA(ctx caddy.Context, id string) (*CA, error)

GetCA retrieves a CA by ID. If the ID is the default CA ID, and it hasn't been provisioned yet, it will be provisioned.

func (*PKI) Provision

func (p *PKI) Provision(ctx caddy.Context) error

Provision sets up the configuration for the PKI app.

func (*PKI) ProvisionDefaultCA

func (p *PKI) ProvisionDefaultCA(ctx caddy.Context) error

ProvisionDefaultCA sets up the default CA.

func (*PKI) Start

func (p *PKI) Start() error

Start starts the PKI app.

func (*PKI) Stop

func (p *PKI) Stop() error

Stop stops the PKI app.