tls

package
v0.17.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 7, 2026 License: MIT Imports: 20 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
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

func CACertLocation() (string, error)

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

func CACertPath() (string, error)

CACertPath is the path to the local CA certificate (PEM).

func CAKeyPath

func CAKeyPath() (string, error)

CAKeyPath is the path to the local CA private key (PEM).

func CertPath

func CertPath() (string, error)

CertPath is the path to the wildcard leaf 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 Dir

func Dir() (string, error)

Dir returns (creating if needed) the directory holding the CA and certificate material.

func EnsureCA

func EnsureCA() (certPath, keyPath string, err error)

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

func InstallIntermediate(intPEM []byte) error

InstallIntermediate stores a validated intermediate beside the machine key.

func InstallNSSTrust

func InstallNSSTrust(r platform.Runner) error

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

func InstallSystemTrust(r platform.Runner) error

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

func InstallTeamRootTrust(r platform.Runner, path string) error

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

func IntermediateFor(machine, suffix string) (subtree string, ok bool)

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 KeyPath

func KeyPath() (string, error)

KeyPath is the path to the wildcard leaf private key (PEM).

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

func MachineCSR(machine, suffix string) ([]byte, error)

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

func MachineSubtree(machine, suffix string) string

MachineSubtree is the peer subtree one machine answers and its intermediate is constrained to: <machine>.<suffix>.

func NSSTrusted added in v0.13.0

func NSSTrusted(ctx context.Context) (found, total int, err error)

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

func NewTeamRoot(suffix string) (certPEM, keyPEM []byte, err error)

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 Purge

func Purge() error

Purge deletes the local CA and certificate material from disk.

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

func RemoveNSSTrust(r platform.Runner) error

RemoveNSSTrust removes the local CA from all discovered NSS databases.

func RemoveSystemTrust

func RemoveSystemTrust(r platform.Runner) error

RemoveSystemTrust removes the local CA from the OS system trust store.

func RemoveTeamRootTrust added in v0.16.0

func RemoveTeamRootTrust(r platform.Runner, fingerprint string) error

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

func SignIntermediate(rootPEM, rootKeyPEM, csrPEM []byte, machine, suffix string) ([]byte, error)

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

func SystemTrusted(ctx context.Context) (bool, error)

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

func TeamRootFingerprint(path string) (string, error)

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

func ValidateIntermediate(intPEM, rootPEM []byte, machine, suffix string) error

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

func ValidateTeamRoot(pemBytes []byte, suffix string) error

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL