github.com/caddyserver/caddy/v2/modules/caddypki

No package summary is available.

Package

Files: 7. Third party imports: 7. Imports from organisation: 1. Tests: 0. Benchmarks: 0.

Constants

Vars

Types

AuthorityConfig

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

Field name	Field type	Comment
SignWithRoot	`bool`	No comment on field.
DB	`*db.AuthDB`	TODO: should we just embed the underlying authority.Config struct type?
AuthConfig	`*authority.AuthConfig`	No comment on field.

CA

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

Field name	Field type	Comment
Name	`string`	The user-facing name of the certificate authority.
RootCommonName	`string`	The name to put in the CommonName field of the root certificate.
IntermediateCommonName	`string`	The name to put in the CommonName field of the intermediate certificates.
IntermediateLifetime	`caddy.Duration`	The lifetime for the intermediate certificates
InstallTrust	`*bool`	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.
Root	`*KeyPair`	The root certificate to use; if null, one will be generated.
Intermediate	`*KeyPair`	The intermediate (signing) certificate; if null, one will be generated.
StorageRaw	`json.RawMessage`	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.
ID	`string`	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.
storage	`certmagic.Storage`	No comment on field.
root	`*x509.Certificate`	No comment on field.
interKey	`any`	No comment on field.
mu	`*sync.RWMutex`	No comment on field.
rootCertPath	`string`	No comment on field.
log	`*zap.Logger`	No comment on field.
ctx	`caddy.Context`	No comment on field.

KeyPair

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

Field name	Field type	Comment
Certificate	`string`	The certificate. By default, this should be the path to a PEM file unless format is something else.
PrivateKey	`string`	The private key. By default, this should be the path to a PEM file unless format is something else.
Format	`string`	The format in which the certificate and private key are provided. Default: pem_file

PKI

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.

Field name	Field type	Comment
CAs	`map[string]*CA`	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".
ctx	`caddy.Context`	No comment on field.
log	`*zap.Logger`	No comment on field.

adminAPI

adminAPI is a module that serves PKI endpoints to retrieve information about the CAs being managed by Caddy.

Field name	Field type	Comment
ctx	`caddy.Context`	No comment on field.
log	`*zap.Logger`	No comment on field.
pkiApp	`*PKI`	No comment on field.

caInfo

caInfo is the response structure for the CA info API endpoint.

Field name	Field type	Comment
ID	`string`	No comment on field.
Name	`string`	No comment on field.
RootCN	`string`	No comment on field.
IntermediateCN	`string`	No comment on field.
RootCert	`string`	No comment on field.
IntermediateCert	`string`	No comment on field.

Functions

func (*CA) NewAuthority

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.

Uses: authority.Config, authority.NewEmbedded, authority.Option, authority.WithConfig, authority.WithDatabase, authority.WithX509RootCerts, authority.WithX509Signer, authority.WithX509SignerFunc, crypto.Signer, fmt.Errorf, x509.Certificate, zap.String.

func (*CA) Provision

Provision sets up the CA.

Uses: crypto.Signer, fmt.Errorf, sync.RWMutex, time.Duration, x509.Certificate.

func (*PKI) GetCA

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.

Uses: fmt.Errorf.

func (*PKI) Provision

Provision sets up the configuration for the PKI app.

Uses: fmt.Errorf.

func (*PKI) ProvisionDefaultCA

ProvisionDefaultCA sets up the default CA.

func (*PKI) Start

Start starts the PKI app.

Uses: zap.Error, zap.String.

func (*PKI) Stop

Stop stops the PKI app.

func (*adminAPI) Provision

Provision sets up the adminAPI module.

func (*adminAPI) Routes

Routes returns the admin routes for the PKI app.

func (CA) IntermediateCertificate

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

func (CA) IntermediateKey

IntermediateKey returns the CA's intermediate private key.

func (CA) RootCertificate

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

func (CA) RootKey

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.

func (KeyPair) Load

Load loads the certificate and key.

Uses: certmagic.PEMDecodePrivateKey, crypto.Signer, fmt.Errorf, os.ReadFile.

func (PKI) CaddyModule

CaddyModule returns the Caddy module information.

func (adminAPI) CaddyModule

CaddyModule returns the Caddy module information.

Private functions

func cmdTrust

References: caddycmd.DetermineAdminAPIAddress, fmt.Errorf, path.Join.

func cmdUntrust

References: caddycmd.DetermineAdminAPIAddress, fmt.Errorf, os.Stat, truststore.Uninstall, truststore.UninstallFile, truststore.WithDebug, truststore.WithFirefox, truststore.WithJava.

func generateIntermediate

References: x509util.CreateCertificate, x509util.DefaultIntermediateTemplate.

func generateRoot

References: x509util.CreateCertificate, x509util.DefaultRootTemplate.

func init

func needsRenewal

References: time.Duration, time.Now.

func newCert

References: keyutil.GenerateDefaultSigner, time.Now, time.Second, x509util.CreateCertificateRequest, x509util.CreateTemplateData, x509util.NewCertificate, x509util.WithTemplate.

func pemDecodeSingleCert

References: fmt.Errorf, pem.Decode, x509.ParseCertificate.

func pemEncode

References: bytes.Buffer, pem.Block, pem.Encode.

func pemEncodeCert

func rootAndIntermediatePEM

func rootCertFromAdmin

rootCertFromAdmin makes the API request to fetch the root certificate for the named CA via admin API.

References: caddycmd.AdminAPIRequest, fmt.Errorf, http.Header, http.MethodGet, json.NewDecoder, path.Join, pem.Decode, x509.ParseCertificate.

func trusted

References: x509.VerifyOptions.

func maintenance

References: debug.Stack, log.Printf, time.Minute, time.NewTicker.

func renewCerts

References: zap.Error, zap.String.

func renewCertsForCA

References: fmt.Errorf, time.Until, zap.Duration, zap.String, zap.Time.

func getCAFromAPIRequestPath

References: fmt.Errorf, http.StatusBadRequest, http.StatusInternalServerError, http.StatusNotFound, strings.Split.

func handleAPIEndpoints

handleAPIEndpoints routes API requests within adminPKIEndpointBase.

References: fmt.Errorf, http.StatusNotFound, strings.Split, strings.TrimPrefix.

func handleCACerts

handleCACerts returns the certificate chain for a particular CA by its ID. If the CA ID is the default, then the CA will be provisioned if it has not already been. Other CA IDs will return an error if they have not been previously provisioned.

References: fmt.Errorf, http.MethodGet, http.StatusInternalServerError, http.StatusMethodNotAllowed.

func handleCAInfo

handleCAInfo returns information about a particular CA by its ID. If the CA ID is the default, then the CA will be provisioned if it has not already been. Other CA IDs will return an error if they have not been previously provisioned.

References: fmt.Errorf, http.MethodGet, http.StatusInternalServerError, http.StatusMethodNotAllowed, json.Marshal.

func genIntermediate

References: certmagic.PEMEncodePrivateKey, fmt.Errorf, time.Duration.

func genRoot

References: certmagic.PEMEncodePrivateKey, fmt.Errorf.

func installRoot

installRoot installs this CA's root certificate into the local trust store(s) if it is not already trusted. The CA must already be provisioned.

References: truststore.Install, truststore.WithDebug, truststore.WithFirefox, truststore.WithJava, zap.String.

func loadOrGenIntermediate

References: certmagic.PEMDecodePrivateKey, errors.Is, fmt.Errorf, fs.ErrNotExist.

func loadOrGenRoot

References: certmagic.PEMDecodePrivateKey, errors.Is, fmt.Errorf, fs.ErrNotExist.

func newReplacer

func storageKeyCAPrefix

References: certmagic.StorageKeys, path.Join.

func storageKeyIntermediateCert

References: path.Join.

func storageKeyIntermediateKey

References: path.Join.

func storageKeyRootCert

References: path.Join.

func storageKeyRootKey

References: path.Join.