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:
- Whether the presented certificate chains to a configured trust anchor, approved fingerprint, or PEM trust store.
- 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:
SYSTEMfor the normal JVM or platform trust configuration.TOFUfor one explicitly approved public certificate fingerprint.TRUST_STOREfor 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.