Skip to content

Certificates and Trust

SSL Teams separates transport trust, application-CA trust, and certificate identity. Keeping those decisions separate prevents a trusted certificate from being mistaken for an authorized or correctly named certificate.

The certificate hierarchy

startup TLS certificate
    HTTPS service identity

application Root CA
    signs an application Intermediate CA
        signs development leaf certificates

The startup certificate protects the dashboard and API connection. The application Root and Intermediate issue the development certificates used by applications and internal services.

Trust is not identity

An HTTPS client checks both:

  1. Whether the presented certificate chains to a configured trust anchor, approved fingerprint, or PEM trust store.
  2. Whether the certificate identifies the hostname or IP address in the URL.
URL identity Required SAN type
localhost DNS SAN
service.example.test DNS SAN
127.0.0.1 IP SAN
192.0.2.10 IP SAN

SSL Teams does not provide a trust-all or hostname-verification bypass. TOFU (Trust On First Use) records one explicitly verified certificate fingerprint for an origin. A changed TOFU certificate must be investigated before it is replaced.

Transport trust profiles

The CLI scopes transport profiles to the complete normalized origin: scheme, hostname, and effective port. It supports:

  • SYSTEM for the normal JVM or platform trust configuration.
  • TOFU for one explicitly approved public certificate fingerprint.
  • TRUST_STORE for a reviewed PEM file containing public X.509 certificates.

Inspect or remove one local profile with:

sslteam tls show --origin https://localhost:15080
sslteam tls forget --origin https://localhost:15080 --yes

For automation, prefer a reviewed PEM trust store. Use TOFU only after verifying the fingerprint through an independent channel.

Application Root custody

The application Root setup is a one-time protected ceremony. The encrypted Root backup and passphrase must be stored separately and offline. The Root private key is not a normal download and must never be installed into a platform trust store.

Installing the public Root certificate expands the trust boundary for software using that store. Verify its fingerprint first and install it only on controlled development or test machines.

Intermediate and leaf custody

The server retains the Intermediate private key used for leaf issuance. The signing authority must remain behind server authorization, audit, lifecycle, and revocation controls.

Leaf artifacts may contain private keys and password-protected PKCS#12 files. Publish certificate and chain files separately when consumers need only public material. Treat a complete artifact bundle as sensitive even when one file inside it is public.

Lifecycle terms

Action Meaning
Retire Planned operational transition that preserves history and stops normal use according to server policy.
Revoke Security response for compromise or unauthorized use. Descendant impact follows server policy.
Forget Removes one CLI-local TLS profile; it does not change server certificate state.
Remove Removes one CLI-local Root; it does not revoke a server-managed Root.

Every server-managed certificate remains associated with its original PKI family. A replacement Root creates a new family rather than reactivating a retired or revoked authority.

Local Root custody commands operate only on the encrypted CLI store. They do not contact the backend and do not accept --base-url; use optional local scope and storage overrides only when needed. The first sslteam ca root remove --name <local-root-name> invocation issues a one-time confirmation token, and removal does not revoke a server-managed Root.