Documentation
¶
Overview ¶
Package tls generates the local CA and wildcard certificate (via crypto/x509) and installs/removes trust in the system and NSS stores.
Index ¶
- Variables
- func CACertLocation() (string, error)
- func CACertPath() (string, error)
- func CAKeyPath() (string, error)
- func CertPath() (string, error)
- func CertutilInstallable() bool
- func CertutilRemedy() string
- func Dir() (string, error)
- func EnsureCA() (certPath, keyPath string, err error)
- func InstallIntermediate(intPEM []byte) error
- func InstallNSSTrust(r platform.Runner) error
- func InstallSystemTrust(r platform.Runner) error
- func InstallTeamRootTrust(r platform.Runner, path string) error
- func Intermediate() (*x509.Certificate, error)
- func IntermediateFor(machine, suffix string) (subtree string, ok bool)
- func IntermediateSubtree(c *x509.Certificate) string
- func IssueDefaultCert(caCert *x509.Certificate, caKey *ecdsa.PrivateKey) (certPEM, keyPEM []byte, err error)
- func IssueHostCert(caCert *x509.Certificate, caKey *ecdsa.PrivateKey, hosts []string) (certPEM, keyPEM []byte, err error)
- func KeyPath() (string, error)
- func LoadCA(certPath, keyPath string) (*x509.Certificate, *ecdsa.PrivateKey, error)
- func MachineCSR(machine, suffix string) ([]byte, error)
- func MachineSubtree(machine, suffix string) string
- func NSSTrusted(ctx context.Context) (found, total int, err error)
- func NewTeamRoot(suffix string) (certPEM, keyPEM []byte, err error)
- func Purge() error
- func RemoveIntermediate() error
- func RemoveNSSTrust(r platform.Runner) error
- func RemoveSystemTrust(r platform.Runner) error
- func RemoveTeamRootTrust(r platform.Runner, fingerprint string) error
- func SignIntermediate(rootPEM, rootKeyPEM, csrPEM []byte, machine, suffix string) ([]byte, error)
- func SystemTrusted(ctx context.Context) (bool, error)
- func TeamRootFingerprint(path string) (string, error)
- func ValidateIntermediate(intPEM, rootPEM []byte, machine, suffix string) error
- func ValidateTeamRoot(pemBytes []byte, suffix string) error
Constants ¶
This section is empty.
Variables ¶
var ErrNoCertutil = errors.New("certutil is not installed")
ErrNoCertutil reports that the NSS tooling is absent, so the browser trust stores cannot be read at all.
Functions ¶
func CACertLocation ¶ added in v0.4.0
CACertLocation resolves the CA certificate path without creating any directories, so query-only callers (`proximo config ca-path`) leave a host without proximo state untouched. The file may not exist yet (proximo not installed); callers that care must check.
func CACertPath ¶
CACertPath is the path to the local CA certificate (PEM).
func CertutilInstallable ¶ added in v0.13.0
func CertutilInstallable() bool
CertutilInstallable reports whether browser trust can be installed at all: the tooling is already here, or a package manager proximo supports can fetch it. Reading it before `install` mutates anything is what keeps a host that can never finish the trust step from being changed at all.
func CertutilRemedy ¶ added in v0.13.0
func CertutilRemedy() string
CertutilRemedy is the command that installs the NSS tooling, so a host that cannot even be asked about browser trust has a first step.
It answers per OS rather than per detected package manager: the host that needs this remedy is precisely the one where no package manager was found, and that host must not be told to run Homebrew because it is not a Mac.
func EnsureCA ¶
EnsureCA generates a local CA on first use and reuses an existing one on subsequent runs. It returns the CA certificate and key file paths.
func InstallIntermediate ¶ added in v0.16.0
InstallIntermediate stores a validated intermediate beside the machine key.
func InstallNSSTrust ¶
InstallNSSTrust adds the local CA to the NSS trust databases used by Firefox and Chrome-on-Linux. When certutil is missing it installs nss-tools first. certutil invocations go through the injected Runner; certutil discovery and bootstrap stay on the package helpers.
func InstallSystemTrust ¶
InstallSystemTrust adds the local CA to the OS system trust store using built-in OS tooling. Privileged operations go through the injected Runner so the install step is testable.
func InstallTeamRootTrust ¶ added in v0.16.0
InstallTeamRootTrust adds the team root at path to the system and NSS stores, beside the local CA.
func Intermediate ¶ added in v0.16.0
func Intermediate() (*x509.Certificate, error)
Intermediate returns the installed intermediate, or nil when there is none.
func IntermediateFor ¶ added in v0.16.0
IntermediateFor reports the subtree the installed intermediate is constrained to, and whether that is this machine's MachineSubtree. With no intermediate installed it returns "", false.
func IntermediateSubtree ¶ added in v0.16.0
func IntermediateSubtree(c *x509.Certificate) string
IntermediateSubtree is the single DNS subtree an intermediate is constrained to, or "" when it is not constrained to exactly one.
func IssueDefaultCert ¶ added in v0.16.0
func IssueDefaultCert(caCert *x509.Certificate, caKey *ecdsa.PrivateKey) (certPEM, keyPEM []byte, err error)
IssueDefaultCert generates the certificate Traefik serves when no leaf matches the SNI: signed by the CA, with no SAN at all. Naming nothing, it is the same certificate for an unserved name and an invented one, and it names none of the machine's routes. The CommonName is not a DNS name, so no client that still falls back to it can match it either.
func IssueHostCert ¶
func IssueHostCert(caCert *x509.Certificate, caKey *ecdsa.PrivateKey, hosts []string) (certPEM, keyPEM []byte, err error)
IssueHostCert generates a leaf certificate covering the exact hosts, signed by the CA, and returns it PEM-encoded. Validity stays under 398 days to satisfy the Apple/Chrome TLS policy (which rejects longer-lived leaf certs, and also rejects TLD-level wildcards like *.test — hence exact SANs, no wildcard).
func LoadCA ¶
func LoadCA(certPath, keyPath string) (*x509.Certificate, *ecdsa.PrivateKey, error)
LoadCA loads the CA certificate and private key from PEM files.
func MachineCSR ¶ added in v0.16.0
MachineCSR returns the certificate signing request for this machine's intermediate, for its MachineSubtree. The machine key is created only if none exists, and never replaced. The CSR is kept, so a second run prints the same bytes; a new label or suffix is a new request for the same key.
func MachineSubtree ¶ added in v0.16.0
MachineSubtree is the peer subtree one machine answers and its intermediate is constrained to: <machine>.<suffix>.
func NSSTrusted ¶ added in v0.13.0
NSSTrusted reports how many of the NSS databases on this host hold the local CA, out of how many were found. Zero databases is not a failure: a machine with no Firefox or Chrome profile has nothing to answer with.
func NewTeamRoot ¶ added in v0.16.0
NewTeamRoot mints a team root for suffix: ten years, name-constrained critically to the suffix, excluding every IP, email address and URI — the shape ValidateTeamRoot accepts, in the encoding the ADR 0010 proof verified on every platform. The key is returned unencrypted for the custodian to encrypt; nothing here stores it.
func RemoveIntermediate ¶ added in v0.16.0
func RemoveIntermediate() error
RemoveIntermediate removes the installed intermediate, keeping the machine key a new one must match. Removing none is not an error.
func RemoveNSSTrust ¶
RemoveNSSTrust removes the local CA from all discovered NSS databases.
func RemoveSystemTrust ¶
RemoveSystemTrust removes the local CA from the OS system trust store.
func RemoveTeamRootTrust ¶ added in v0.16.0
RemoveTeamRootTrust removes the team root that was installed with the given fingerprint from the system and NSS stores. It needs no file: the one configured now may have been replaced or deleted since it was trusted.
func SignIntermediate ¶ added in v0.16.0
SignIntermediate is the custodian's half of the ceremony: it signs the machine's CSR with the team root into an intermediate for <machine>.<suffix> — five years, MaxPathLen 0, constrained like the root.
func SystemTrusted ¶ added in v0.13.0
SystemTrusted reports whether the local CA is in the OS system trust store. It only reads — no elevation, no repair — because a diagnosis that asks for a password is one nobody runs at the moment they need it most.
func TeamRootFingerprint ¶ added in v0.16.0
TeamRootFingerprint is the SHA-1 of the team root's DER, the selector `security delete-certificate -Z` takes: it names exactly one certificate, where -c matches a substring of a common name the team chose.
func ValidateIntermediate ¶ added in v0.16.0
ValidateIntermediate refuses an intermediate this machine must not sign with: one that does not chain to the team root, whose permitted subtree is not exactly <machine>.<suffix>, whose MaxPathLen is not 0, whose name constraints leave a name type open, or that is not for the machine key.
func ValidateTeamRoot ¶ added in v0.16.0
ValidateTeamRoot refuses a team root that could sign outside the Peer suffix. It is the one peer value whose rule is checked completely, and the one with the largest consequence: proximo installs this certificate into a trust store that serves a colleague's real browsing (ADR 0010).
Constraining dNSName alone is not enough — under RFC 5280 a name type absent from the permitted subtrees is unrestricted — so every IP range, every email address and every URI must be excluded too.
Types ¶
This section is empty.