SSL Teams DevOps Playbook
Audience: platform engineers, DevOps operators, service owners, and release engineers
Purpose: operate the SSL Teams service and its sslteam client safely and repeatably
Status: the canonical end-to-end operator workflow
This guide defines the end-to-end workflow for service owners, platform engineers, and operators running SSL Teams beyond an initial experiment. Use the CLI quick reference for familiar sequences and the CLI command reference for exact syntax.
What this guide is for
- Running SSL Teams in repeatable, production-style operator workflows.
- Executing CLI-first trust, authentication, issuance, and lifecycle tasks safely.
- Defining operational guardrails that keep backend authorization authoritative.
Operational control objectives
- Identity control: only authenticated and authorized identities can run protected actions.
- Trust integrity: origin trust and hostname identity checks remain explicit and fail-closed.
- Custody discipline: Root and private-key handling stays bounded to approved workflows.
- Auditability: certificate lifecycle decisions remain attributable and reviewable.
What this guide is not
- Not a first-time browser walkthrough (use the Operator Guide).
- Not a deployment-installation tutorial (use Deploy with Docker).
- Not a command encyclopedia (use the CLI command reference).
Security boundary: the CLI is an operator client, not an authority. The backend remains authoritative for authentication, authorization, scope, certificate policy, lifecycle state, and audit history. A local preference, trust profile, or private file never grants server permission.
1. Operating model
SSL Teams has three different certificate layers. Do not substitute one for another:
startup TLS certificate
protects HTTPS between the CLI or dashboard and the SSL Teams service
application Root CA
signs the application Intermediate CA
signs development leaf certificates
The CLI also has two different trust workflows:
- Transport trust (
sslteam tls ...) decides whether the CLI accepts the HTTPS service certificate for one normalized origin. - Platform CA trust (
sslteam ca trust ...) installs a public application-CA certificate into a local operating-system, Java, or Firefox trust store.
Trust and hostname identity are separate checks. A trusted certificate is still rejected when its SAN does not identify the hostname or IP literal in the URL. DNS identities require DNS SANs; IP literals require IP SANs. The CLI provides no trust-all or hostname-verification bypass.
Service deployment boundary
Before operating the CLI workflow, service owners must confirm the deployment boundary:
- the service has a deployment-specific HTTPS hostname and certificate identity;
- the startup TLS certificate is valid for the URL hostname or IP address used by clients;
- PostgreSQL storage and backups are owned by the deployment platform;
- protected JWT signing configuration is supplied outside source control and browser state;
- the initial administrator account has a controlled owner and follows the required password-change process;
- the loopback-only management readiness endpoint is restricted to the deployment host or approved monitoring network; and
- logs retain correlation identifiers while redacting credentials, private keys, certificate signing requests (CSRs), certificate bodies, and raw request data.
The default application port is 15080; an ingress may publish another external port, but it must preserve HTTPS identity verification and the service security boundary. The management readiness endpoint is on port 9000 and must not be published publicly. Production does not expose an OpenAPI endpoint; schemas are build artifacts and documentation, not an authorization boundary.
Release publication is separate from certificate issuance. Use Deploy with Docker for the runtime boundary; release engineering belongs to the product build pipeline rather than this operator workflow.
2. Before you begin
2.1 Required information
Have these values ready through an approved, protected channel:
| Value | Example | Handling |
|---|---|---|
| Service origin | Deployment-specific HTTPS origin | Must be the exact HTTPS origin operators will use. |
| Expected service fingerprint | SHA-256 fingerprint | Verify independently before TOFU (Trust On First Use) approval. |
| CLI home | ${HOME}/.sslteam-cli by default |
Override only for an isolated or special-purpose workflow; keep it out of source control and ordinary artifacts. |
| Root backup location | Offline protected directory | Keep the encrypted backup and passphrase separate. |
The examples below use non-production placeholder identities. Replace them with values assigned by the service owner.
2.2 Prepare a protected workspace
set -eu
umask 077
# Optional overrides. Omit both for the normal configured/default CLI behavior.
# export BACKEND_ORIGIN="https://service.example.test:15080"
# export SSLTEAM_CLI_HOME="$PWD/.sslteam-cli"
export PUBLIC_DIR="$PWD/public-material"
export PRIVATE_DIR="$PWD/private-material"
export LEAF_ARTIFACT_DIR="$PRIVATE_DIR/leaf-artifacts"
mkdir -p "$PUBLIC_DIR" "$PRIVATE_DIR" "$LEAF_ARTIFACT_DIR"
BACKEND_ORIGIN is only a shell convenience for a non-default service origin. SSLTEAM_CLI_HOME is only needed when an isolated or disposable local state directory is required. The CLI otherwise uses its saved connection profile and the configured application default (https://localhost:15080 when no other backend URL is supplied). Do not export either variable merely because it appears in an example.
Each CLI HTTP request has a 60-second default timeout. For slower operations such as RSA-4096 leaf
generation, set SSLTEAM_CLIENT_REQUEST_TIMEOUT before starting the command, for example
SSLTEAM_CLIENT_REQUEST_TIMEOUT=120s. Duration values below 10s are rejected; changing the
environment value requires a new CLI process. TLS discovery and connection-handshake limits are
separate from this application request timeout.
PUBLIC_DIR is for public certificate and chain downloads. PRIVATE_DIR is a protected workspace root for private material, and LEAF_ARTIFACT_DIR keeps generated or recovered leaf bundles under that protected root. A generated leaf bundle can contain leaf-key.pem, a PKCS#12 keystore, a password sidecar, and leaf-artifacts.zip, so do not write it to PUBLIC_DIR.
Do not put passwords, tokens, private keys, CSRs, Root backups, passphrases, or leaf artifact directories into CI logs, source control, browser storage, or ordinary build artifacts.
2.3 Confirm the CLI build
sslteam version
sslteam --help
version performs no network, filesystem, or credential operation. The installed build is the final authority for its version. The current command source registers the command families documented here.
3. End-to-end workflow
The safe operational sequence is:
- Configure the service origin and scope.
- Establish HTTPS transport trust.
- Authenticate the operator or automation identity.
- Confirm authenticated connectivity with
ping. - Inspect application-CA readiness.
- Complete the one-time application Root backup ceremony, if required.
- Inspect Root and Intermediate state.
- Create and activate an Intermediate, if required.
- Download and install the public application Root where client runtimes need it.
- Issue a leaf with explicit SAN identities.
- Inspect the issued leaf and distribute only the required public material.
- Rotate through a new issuance, then retire or revoke the old authority or leaf as appropriate.
Execution phases:
- Foundation: steps 1 through 4 establish origin, trust, and authenticated session state.
- CA readiness: steps 5 through 9 establish Root/Intermediate readiness for issuance.
- Issuance and lifecycle: steps 10 through 12 govern distribution, rotation, retirement, and revocation.
4. Configure origin and scope
For the normal deployment, do not run config set just to repeat the application default or an already-saved connection. Use config show to inspect the effective origin and scope:
sslteam config show
For a special case such as a non-default deployment origin, save an explicit connection preference:
export BACKEND_ORIGIN="https://service.example.test:15080"
sslteam config set --base-url "$BACKEND_ORIGIN"
sslteam config show
Configuration precedence is:
- command-specific option, when that command exposes it;
- saved CLI preference or origin-scoped connection profile;
- configured application default, normally
SSLTEAM_BACKEND_URLorhttps://localhost:15080.
For certificate and server-managed CA commands, the authorized scope resolves from saved preferences or the CLI’s configured default. Verify the effective values with config show before a privileged operation.
5. Establish HTTPS transport trust
Transport trust must be established before authenticated commands can run.
The TLS commands in this section require an explicit --origin. If the deployment origin is not already stored in BACKEND_ORIGIN, replace the variable with the exact HTTPS origin or export it for this shell. Exporting BACKEND_ORIGIN alone does not change the CLI's saved or application default.
5.1 Recommended unattended mode: reviewed PEM trust store
For unattended scripts, prefer a reviewed public PEM trust store over interactive TOFU. The automation process should be:
- obtain the public service CA PEM from the approved deployment artifact or secret-management workflow;
- review its subject, issuer, validity, and SHA-256 fingerprint outside the unattended job;
- provide the exact HTTPS origin and PEM path to the CLI;
- let the CLI validate trust and hostname identity before it persists the origin profile;
- run authentication, readiness, issuance, and publication only after that validation succeeds; and
- stop on any trust, hostname, validity, authorization, or optimistic-lock failure rather than retrying with weaker settings.
Use a public PEM file whose contents and fingerprint were reviewed through the deployment process:
sslteam tls trust-store \
--origin "$BACKEND_ORIGIN" \
--path /protected/trust/service-ca.pem
sslteam tls show --origin "$BACKEND_ORIGIN"
The CLI validates the PEM trust material and validates the service before saving the profile. Malformed, secret-bearing, untrusted, or hostname-incompatible material must not be persisted. The job may repeat this command idempotently for the same reviewed origin and PEM, but it must not approve a changed certificate or replace the trust profile automatically.
5.2 First-use enrollment: TOFU
Discovery is deliberately separate from approval:
sslteam tls tofu --origin "$BACKEND_ORIGIN"
This discovery phase sends no HTTP request, bearer token, password, CSR, or certificate operation. It displays public certificate metadata and a SHA-256 fingerprint. Verify that fingerprint through an independent trusted channel, then approve exactly that fingerprint:
sslteam tls tofu \
--origin "$BACKEND_ORIGIN" \
--fingerprint <verified-sha256-fingerprint>
sslteam tls show --origin "$BACKEND_ORIGIN"
Never approve a fingerprint based only on the output of an untrusted connection. For unattended use, prefer the reviewed PEM trust-store workflow.
5.3 Changed certificate
A changed TOFU certificate is a fail-closed security event. Stop and investigate the service identity, certificate rotation, hostname, and deployment channel. Do not retry with weaker trust.
Only after independent verification, replace the exact origin profile:
sslteam tls replace \
--origin "$BACKEND_ORIGIN" \
--fingerprint <new-verified-sha256-fingerprint>
Inspect or remove one persisted profile with:
sslteam tls show --origin "$BACKEND_ORIGIN"
sslteam tls forget --origin "$BACKEND_ORIGIN" --yes
tls forget removes only local transport trust for that origin. It does not revoke a certificate, change server state, or remove a platform trust anchor.
6. Authenticate and check connectivity
6.1 Browser-approved device authentication
Use device authentication when an operator should approve the CLI session in the dashboard:
sslteam auth device
The command prints a verification URL, a user code, an expiry, and a polling interval. Open the verification URL, approve the displayed code, and leave the CLI running. It polls until approval, denial, expiry, or timeout. On success it stores the session locally and synchronizes the server JWT verification key.
If the dashboard asks you to change a temporary password during approval, complete it there. The CLI keeps polling and finishes on its own, and it never saves a session that still requires a password change. The CLI prints the account it signed in as; confirm it is yours, and run sslteam auth logout if it is not. Starting and approving a second sslteam auth device for the same account supersedes the first one, which stops without saving a session. To change an initial password from the terminal instead, use sslteam auth password (section 6.2).
6.2 Direct password authentication
Interactive prompt, preferred for a human operator:
sslteam auth password --username <username>
Protected file, suitable for controlled automation:
sslteam auth password \
--username <username> \
--password-file /protected/secrets/sslteam-password
The file must be a protected regular file containing one non-empty password and at most one trailing line ending. --password exists but exposes a secret to shell history, process inspection, and job diagnostics; do not use it when a prompt or protected file is available.
If the server requires an initial password change, provide a protected replacement file:
sslteam auth password \
--username <username> \
--password-file /protected/secrets/current-password \
--new-password-file /protected/secrets/replacement-password
If sign-in fails after the change
If the password change succeeds but the following sign-in fails, the password has already changed and no session was saved. Run sslteam auth password again with the new password. If the temporary password has expired, the CLI says so; ask an administrator to reset the credential. Do not retry with the old password.
6.3 Confirm the session
sslteam me
sslteam ping
sslteam config show
me confirms the server-authoritative account UUID and effective roles before an operator continues. ping proves that the selected service accepted the stored access token. Neither command proves Root administration, Intermediate signing, leaf issuance, or revocation permission.
For temporary bounded JWT diagnostics, the authenticated commands support --diag:
sslteam ping --diag
The option is also available on sslteam auth device and sslteam auth password.
It enables bounded JWT parser and claim diagnostics for that command run, such
as issuer, subject, audience, and time-claim validation failures. Diagnostics
are disabled by default and do not print raw tokens, authorization headers,
passwords, private keys, CSRs, certificate bodies, or raw HTTP data. Remove
--diag after the investigation.
7. Inspect CA readiness
Use these commands as the read-only CA inspect:
sslteam ca status
sslteam ca root list
sslteam ca intermediate status
Review:
- application-CA family status and setup state;
applicationCaReadyandleafIssuanceReady;- server Root identity, fingerprint, validity, lifecycle status, and versions;
- local Root custody and whether its fingerprint matches the server Root;
- active Intermediate identity and validity;
- pending Intermediate requests, expiry, and lifecycle history.
For a complete server-authoritative CA view, run:
sslteam ca trust list
sslteam ca trust list --sslteam
This reads local platform trust stores and compares exact SHA-256 fingerprints
with GET /api/v1/cert/inventory for the configured PKI scope. Use
the server familyId, rootId, and intermediateId values to confirm that a
Root and Intermediate belong to the same PKI family. A local alias, filename,
subject, or nickname is not evidence of family membership. If the server
inventory is unavailable, treat every local result as Unverified.
Use --sslteam to filter the discovered macOS/Linux/Windows native stores,
Java cacerts, or Firefox NSS profile for certificates issued by SSL Teams.
SSL Teams adds the same non-critical private X.509 extension to every Root,
Intermediate, and leaf certificate: the UUID-derived OID
2.25.105082758692405847780781908373517615617 with the UTF-8 value SSLTeam.
The CLI checks that OID and value; it does not infer SSL Teams membership from
the subject, issuer, filename, or alias.
For a single exported certificate, inspect the file without network access or trust-store mutation:
sslteam cert inspect --certificate /protected/public-certificate.pem --sslteam
This extension only identifies the SSL Teams certificate family. It does not prove trust, hostname identity, authorization, family membership within the server inventory, or revocation status; continue to use the exact fingerprint and server inventory checks described above.
A local Root record is custody material only. It is not proof that the server uses that Root. A fingerprint mismatch means the local Root must not sign for the server family.
8. Create or set up the application Root
8.1 Server-managed setup or replacement
Use this ceremony when the server has no application Root family, or after the current Root family has been retired or revoked. The authenticated operator must be authorized to initialize or replace the family:
sslteam ca root setup \
--common-name "SSL Team Root CA" \
--organization "SSL Team" \
--organizational-unit "Certificate Authority" \
--out-dir /protected/offline/root-backup
ca root setup creates a new server-managed Root and initial Intermediate. It
then creates an encrypted OpenPGP Root backup and a temporary passphrase file.
After a Root retirement or revocation, the server archives the old family and
creates a new family; it does not reactivate the old Root. The operator must:
- copy the temporary passphrase into a separate protected offline location;
- protect the encrypted backup and passphrase separately;
- type
COPIEDonly after both protected copies exist; - retain the backup for the approved signing and recovery process.
The temporary passphrase file is deleted when the command exits. The server does not replay Root private-key material if the ceremony is interrupted. The command refuses to overwrite an existing backup file.
Do not run this command in an ordinary CI job or a shared download directory. Treat the backup and passphrase as Root signing authority.
8.2 Local offline Root custody
ca root create creates a local encrypted Root in the CLI’s local CA store. It does not create or replace the server-managed application Root:
The local Root commands do not contact the backend and do not accept --base-url. --name is required for create, import, show, and remove. Algorithm and passphrase settings are optional for create; passphrase is optional for import and show. Team, environment, and storage flags are optional local-custody overrides.
sslteam ca root create \
--name local-root \
--algo ecdsa-p256
Import existing local Root material only when the custody process explicitly permits it:
sslteam ca root import \
--name local-root \
--root-cert /protected/root/root-ca.pem \
--root-key /protected/root/root-key.pem
To inspect or remove local custody:
sslteam ca root show --name local-root
sslteam ca root remove --name local-root
sslteam ca root remove --name local-root --confirm <one-time-token>
The first remove invocation issues a one-time confirmation token. Removal is local and destructive; it does not revoke the server-managed Root.
Inspect local custody, including certificate identity and optional key/certificate matching verification:
sslteam ca root show \
--name local-root
Use --passphrase only with protected handling. The manual documents the option because it exists; an interactive prompt or protected secret input is safer than a command-line secret.
9. Create, sign, activate, and inspect an Intermediate
The server retains the Intermediate private key for server-side leaf issuance. The CLI never receives that private key. The offline Root backup signs the server-generated Intermediate CSR, and only the signed public certificate and issuer chain return to the server.
9.1 Guided setup
Use the guided workflow when one command should create the request, sign it from the encrypted Root backup, and activate it:
sslteam ca intermediate setup \
--name int-dev \
--subject-dn "CN=sslteam-int-dev" \
--algorithm ecdsa-p256 \
--backup /protected/offline/root-backup/ssl-teams-application-ca-backup.asc
The Intermediate name must contain 3–64 lowercase letters, digits, ., _, or -. --replace-active is required for an intentional replacement of the active Intermediate.
9.2 Separated reviewable workflow
Use separate commands when signing must occur on an offline or controlled host:
Create the server request and signing manifest:
sslteam ca intermediate create \
--name int-dev \
--subject-dn "CN=sslteam-int-dev" \
--algorithm ecdsa-p256 \
--csr-out /protected/transfer/int-dev.csr.pem \
--manifest-out /protected/transfer/int-dev-signing-manifest.json
Sign the exact manifest with the protected Root backup:
sslteam ca intermediate sign \
--backup /protected/offline/root-backup/ssl-teams-application-ca-backup.asc \
--manifest /protected/transfer/int-dev-signing-manifest.json
The command writes signed Intermediate and chain files. Review the displayed fingerprint and validity before activation. Add --upload only when the signed output is intentionally uploaded and activated as part of the same controlled step.
Activate signed public material:
sslteam ca intermediate activate \
--name int-dev \
--request-id <request-id> \
--intermediate-cert /protected/transfer/int-dev-signed.pem \
--chain /protected/transfer/int-dev-chain.pem
Activation verifies that the chain identifies the current server Root. Use --replace-active only for a reviewed replacement.
Inspect the result:
sslteam ca intermediate status
sslteam ca status
If a request is expired or the server state changed, stop and create a fresh request from current state. Do not bypass a conflict or sign an obsolete manifest.
10. Download and install the public Root certificate
Download public Root material without downloading a private key:
sslteam ca root download certificate \
--out-dir "$PUBLIC_DIR"
🚨 HUGE SECURITY WARNING — installing a Root CA changes the trust boundary.
application-root-ca.pemis public certificate material, but installing it in an operating-system trust store makes every certificate signed by that Root trusted by software using the store. Install it only on an intentionally controlled development or test system, and verify its SHA-256 fingerprint through an independent approved channel first. Never install a Root from an unverified source or without independently confirming its fingerprint.The Root private key is different from the public
.pemcertificate. Do not installroot-key.pem, an encrypted Root backup, or its passphrase in a trust store. Those are CA signing-authority material and must remain in protected offline custody. A trust store receives the public certificate only; it never needs the Root private key.
Inspect the public certificate and record its SHA-256 fingerprint:
openssl x509 \
-in "$PUBLIC_DIR/application-root-ca.pem" \
-noout -subject -issuer -fingerprint -sha256
The CLI requires the exact fingerprint as a confirmation before platform trust changes. Install into the current operating system's native trust store:
sslteam ca trust install \
--certificate "$PUBLIC_DIR/application-root-ca.pem" \
--confirm-fingerprint <exact-sha256-fingerprint>
Verify the installed anchor:
sslteam ca trust verify \
--certificate "$PUBLIC_DIR/application-root-ca.pem" \
--confirm-fingerprint <exact-sha256-fingerprint>
The default operation detects only the native macOS, Linux, or Windows store. It never modifies Java or separately managed browser profiles. To install into both the native store and Java cacerts, add --java:
sslteam ca trust install \
--certificate "$PUBLIC_DIR/application-root-ca.pem" \
--confirm-fingerprint <exact-sha256-fingerprint> \
--java
See Platform trust details for platform prerequisites and the Firefox boundary.
11. Platform trust details
11.1 macOS
The automatic native operation uses the current user's login Keychain and the macOS /usr/bin/security utility:
sslteam ca trust install \
--certificate "$PUBLIC_DIR/application-root-ca.pem" \
--confirm-fingerprint <exact-sha256-fingerprint>
sslteam ca trust verify \
--certificate "$PUBLIC_DIR/application-root-ca.pem" \
--confirm-fingerprint <exact-sha256-fingerprint>
The operator may be prompted by macOS for Keychain authorization. The CLI does not install into every user or system Keychain automatically.
11.2 Linux
The CLI detects supported distribution layouts and uses non-interactive sudo for the file operation and trust refresh after an interactive authorization check. Keep the distribution CA package installed.
Supported layouts include common Fedora/RHEL, Debian/Ubuntu, Arch, and openSUSE-style locations. The actual detected layout determines the refresh command. Run:
sslteam ca trust install \
--certificate "$PUBLIC_DIR/application-root-ca.pem" \
--confirm-fingerprint <exact-sha256-fingerprint>
sslteam ca trust verify \
--certificate "$PUBLIC_DIR/application-root-ca.pem" \
--confirm-fingerprint <exact-sha256-fingerprint>
If no supported layout is detected, stop and use the platform’s documented trust-store procedure; do not point the CLI at an arbitrary directory.
11.3 Windows
The automatic native operation uses the current user's ROOT store through the Windows system certificate utility:
sslteam ca trust install --certificate <root.pem> --confirm-fingerprint <exact-sha256-fingerprint>
sslteam ca trust verify --certificate <root.pem> --confirm-fingerprint <exact-sha256-fingerprint>
The command does not require administrator-wide machine-store access because it targets the current user store. If the Windows certificate utility is unavailable, follow the CLI’s reported prerequisite guidance.
11.4 Java cacerts
Java trust is separate from the operating-system trust store and therefore requires an explicit target. Set JAVA_HOME to the Java installation whose cacerts should change:
export JAVA_HOME="/path/to/jdk"
sslteam ca trust install \
--target java \
--certificate "$PUBLIC_DIR/application-root-ca.pem" \
--confirm-fingerprint <exact-sha256-fingerprint>
The CLI reads lib/security/cacerts below JAVA_HOME directly through the Java KeyStore API, prompts for the trust-store password, and verifies the matching certificate. It does not require keytool or guess which Java installation to modify.
Use --java with the default native operation when both native and Java trust are required. Do not combine --target java with --java; the explicit Java target already selects Java only.
11.5 Firefox prerequisite
Firefox operations require an explicit target and profile. They also require Mozilla NSS certutil on PATH; the CLI does not install or remove that prerequisite. If it is missing, install Mozilla NSS tools and then rerun the Firefox trust command:
| Platform | Installation prerequisite |
|---|---|
| macOS | brew install nss |
| Debian/Ubuntu | sudo apt-get install libnss3-tools |
| Fedora/RHEL | sudo dnf install nss-tools |
| Arch Linux | sudo pacman -S nss |
| Windows | Install Mozilla NSS tools and use their certutil; Windows system certutil.exe is not a Firefox substitute. |
sslteam ca trust install \
--target firefox \
--profile /path/to/firefox/profile \
--certificate "$PUBLIC_DIR/application-root-ca.pem" \
--confirm-fingerprint <exact-sha256-fingerprint>
sslteam ca trust verify \
--target firefox \
--profile /path/to/firefox/profile \
--certificate "$PUBLIC_DIR/application-root-ca.pem" \
--confirm-fingerprint <exact-sha256-fingerprint>
Close Firefox before changing the selected profile. The CLI locates certutil on PATH and invokes only the NSS add, delete, or list operation required by the selected trust command.
11.6 Remove platform trust
Removal is separate from server-side revocation:
sslteam ca trust remove \
--target java \
--certificate "$PUBLIC_DIR/application-root-ca.pem" \
--confirm-fingerprint <exact-sha256-fingerprint>
For Firefox include --target firefox and the same --profile used during installation. For Java-only removal use --target java and the same JAVA_HOME; for native-plus-Java removal omit --target and add --java. With neither selector, removal targets the automatically detected native store. Verify after removal. Removing local trust does not change the server’s CA lifecycle state.
12. Issue and inspect a leaf certificate
cert generate and cert artifact download complete leaf bundles, not public
certificates only. Keep their --out-dir under LEAF_ARTIFACT_DIR (or another
protected directory). Use cert download certificate and cert download chain
with PUBLIC_DIR when you need to distribute public material without a private
key.
The current build supports these leaf key algorithms:
| CLI value | Key type | Signature profile |
|---|---|---|
ecdsa-p256 |
ECDSA on secp256r1 (P-256) |
SHA-256 with ECDSA |
ecdsa-p384 |
ECDSA on secp384r1 (P-384) |
SHA-384 with ECDSA |
rsa-3072 |
3072-bit RSA | SHA-256 with RSA |
rsa-4096 |
4096-bit RSA | SHA-256 with RSA |
The default is ecdsa-p256. The backend still applies the active certificate
policy, so an algorithm accepted by the CLI can be rejected by server policy.
Use SANs for hostname validation
Modern TLS clients and browsers match DNS names and IP literals against the
certificate's Subject Alternative Name (SAN) extension; they do not rely on
the Common Name (CN) alone. SSL Teams still populates CN for compatibility
and requires it to be consistent with the request, but a CN without the
matching SAN is not sufficient for hostname validation. Use DNS=name for
DNS names and IP=address for IP literals.
12.1 DNS identity
Use a DNS SAN for every DNS name clients will use:
sslteam cert generate \
--name service-api \
--common-name service.example.test \
--san "DNS=service.example.test" \
--days 7 \
--algorithm ecdsa-p256 \
--output-profile PKCS12_ONLY \
--out-dir "$LEAF_ARTIFACT_DIR"
12.2 IPv4 identity
Use an IP SAN for an IP literal. Do not encode an IP address as a DNS SAN:
sslteam cert generate \
--name service-ip \
--common-name 192.0.2.10 \
--san "IP=192.0.2.10" \
--days 7 \
--algorithm ecdsa-p256 \
--output-profile PEM_ONLY \
--out-dir "$LEAF_ARTIFACT_DIR"
For DNS names only, repeat --san with one DNS= value for each name:
sslteam cert generate \
--name service-api-dns \
--common-name service.example.test \
--san "DNS=service.example.test" \
--san "DNS=service.internal.example.test" \
--days 7 \
--algorithm ecdsa-p256 \
--output-profile PEM_ONLY \
--out-dir "$LEAF_ARTIFACT_DIR"
For IP addresses only, repeat --san with one IP= value for each address:
sslteam cert generate \
--name service-ip-only \
--common-name 192.0.2.10 \
--san "IP=192.0.2.10" \
--san "IP=127.0.0.1" \
--days 7 \
--algorithm ecdsa-p256 \
--output-profile PEM_ONLY \
--out-dir "$LEAF_ARTIFACT_DIR"
The service validates SANs, validity, key algorithm, and issuance policy. Do not use a common name alone as a hostname policy.
For a service reached through more than one DNS name and IP address, repeat the option once for each identity:
sslteam cert generate \
--name service-api-multi \
--common-name service.example.test \
--san "DNS=service.example.test" \
--san "DNS=service.internal.example.test" \
--san "IP=192.0.2.10" \
--san "IP=127.0.0.1" \
--days 7 \
--algorithm ecdsa-p256 \
--output-profile PEM_ONLY \
--out-dir "$LEAF_ARTIFACT_DIR"
12.3 Choose the output profile deliberately
| Profile | Contents | Password |
|---|---|---|
BOTH |
PEM private key and PKCS#12 keystore | Required; PEM key remains unencrypted. |
PKCS12_ONLY |
PKCS#12 keystore without PEM private key | Required. |
PEM_ONLY |
Unencrypted PEM private key without PKCS#12 | Not used. |
BOTH is the default. For controlled automation, generate a local PKCS#12 password and store its protected sidecar file:
sslteam cert generate \
--name service-api \
--common-name service.example.test \
--san "DNS=service.example.test" \
--output-profile PKCS12_ONLY \
--generate-password \
--show-generated-password \
--out-dir "$LEAF_ARTIFACT_DIR"
--show-generated-password displays the generated password once. Protect the entire artifact directory; a password-protected PKCS#12 file does not make the directory public if it also contains other private material.
12.4 Inspect the issued leaf
The read-only CLI inspect is inventory plus detail:
sslteam cert list
sslteam cert show \
--issuance-id <issuance-id>
Confirm issuance ID, status, SANs, algorithm, issuer Intermediate, fingerprint, validity, scope, and version. A leaf marked active but past notAfter is displayed as expired by the CLI.
For public-only distribution, download certificate and chain separately:
sslteam cert download certificate \
--issuance-id <issuance-id> \
--out-dir "$PUBLIC_DIR"
sslteam cert download chain \
--issuance-id <issuance-id> \
--out-dir "$PUBLIC_DIR"
Inspect public material with a trusted local tool before distribution:
openssl x509 -in "$PUBLIC_DIR/leaf-<issuance-id>.crt.pem" -noout -subject -issuer -serial -dates -fingerprint -sha256
12.5 Recover a lost leaf bundle
🚨 Use
cert artifactwhen the issuance already exists. Use this flow if an old ZIP was deleted, lost, corrupted, or its PKCS#12 password was forgotten. Do not issue a replacement merely to recover files. A replacement changes the certificate identity and key material and must be a deliberate lifecycle decision.
1. Find and verify the issuance ID.
sslteam cert list
sslteam cert show \
--issuance-id <issuance-id>
Confirm the certificate name, SANs, fingerprint, validity, team, environment, version, and active status. Use the UUID returned by the inventory; do not guess an ID from an artifact filename. If the issuance is revoked or inactive, stop and follow the appropriate lifecycle process instead of blindly retrying.
2. Rebuild a new PKCS#12-only ZIP.
mkdir -p "$LEAF_ARTIFACT_DIR/recovered"
sslteam cert artifact \
--issuance-id <issuance-id> \
--output-profile PKCS12_ONLY \
--generate-password \
--out-dir "$LEAF_ARTIFACT_DIR/recovered"
The authenticated server rebuilds the ZIP from persisted issuance and
certificate-chain material. The CLI validates the ZIP, rejects unsafe or
duplicate paths, refuses an existing output directory, extracts it into a new
directory, and writes leaf-artifacts.zip beside the extracted files. The
directory has the form:
$LEAF_ARTIFACT_DIR/recovered/leaf-<issuance-id>/
The extracted files and leaf-artifacts.zip are two local representations of
the same server response. Keep the ZIP as a recovery/archive copy only when
needed; it can contain private key material.
3. Preserve the newly generated password.
With --generate-password, the CLI creates a new password and writes it to:
$LEAF_ARTIFACT_DIR/recovered/leaf-<issuance-id>/localhost.p12.password
The old password is not replayed. If --generate-password is omitted, the
CLI prompts for a password and does not create the .password sidecar file.
--show-generated-password displays a generated password once, but is only
appropriate for a direct protected operator handoff; prefer the protected
sidecar file in automation.
🚫 The password is never in the ZIP. It is not stored in
manifest.jsonor another ZIP member. The ZIP is an archive, not a password vault;localhost.p12is the password-protected object inside it. If a prompted or generated password is lost, rerun this recovery flow and create a new one. Never put passwords in logs, shell history, tickets, or CI output.
For a browser-downloaded ZIP, the dashboard similarly requires a newly entered password and does not save it. Extract it into a new protected directory; the ZIP itself is not password-encrypted:
umask 077
mkdir -p /protected/recovered-leaf
unzip -q /protected/downloads/leaf-<issuance-id>-artifact.zip \
-d /protected/recovered-leaf
cert artifact does not renew, replace, revoke, or reactivate a certificate.
Use cert generate for a genuinely new certificate or deliberate replacement,
with the new SANs and key material reviewed before deployment.
13. Renewal, retirement, and revocation
13.1 Renewal and rotation
Issued certificates are not edited in place. Treat a SAN, validity, algorithm, issuer, or key change as a new issuance:
read current inventory
→ issue replacement
→ deploy replacement
→ verify replacement
→ revoke old leaf when safe
→ retain issuance and correlation metadata
13.2 Planned Root retirement
Re-read the current Root ID from ca root list. Then confirm the exact UUID twice:
sslteam ca root retire \
--root-id <root-uuid> \
--confirm <same-root-uuid> \
--reason "planned Root rotation"
Retirement is a planned operational transition. The service reports that the
family status becomes RETIRED, stops issuing new certificates, and records
the Root retirement time and reason. Existing Intermediate and leaf
certificates remain unchanged and are not revoked. Run the same
sslteam ca root setup ceremony to create a replacement Root and initial
Intermediate family; it never reactivates the retired family. Then install the
new public Root, issue replacement leaves, deploy them, and remove the old
trust only after migration is complete.
13.3 Root revocation
Use only for a Root-level security event:
sslteam ca root revoke \
--root-id <root-uuid> \
--confirm <same-root-uuid> \
--reason "Root private key compromise"
The CLI warns that the Root is revoked, the family is closed with status
RETIRED, and new issuance stops. The service records revokedAt and the reason, revokes the issuing Intermediate,
and revokes and audits every non-deleted descendant leaf. Treat this as an
incident response action, not routine rotation. Run the same sslteam ca root
setup ceremony to create a replacement family, then install the new public
Root and issue replacement leaves immediately. The old Intermediate and
leaves remain historical evidence and are not reactivated.
13.4 Planned Intermediate retirement
sslteam ca intermediate retire \
--intermediate-id <intermediate-uuid> \
--confirm <same-intermediate-uuid> \
--reason "planned Intermediate rotation"
Retirement marks the Intermediate RETIRED, removes it from the active
signing path, changes the family to DEGRADED, and leaves existing leaf
certificates unchanged. The Intermediate and its lifecycle reason remain in
history. Create, sign, and activate a replacement Intermediate before
expecting issuance readiness to return.
13.5 Intermediate revocation
sslteam ca intermediate revoke \
--intermediate-id <intermediate-uuid> \
--confirm <same-intermediate-uuid> \
--reason "Intermediate private key compromise"
The CLI warns that the family becomes DEGRADED, new leaf issuance stops
until replacement activation, and every non-deleted descendant leaf is
revoked and individually audited with the Intermediate revocation reason. The
revoked Intermediate and leaves remain in history while the replacement CSR
workflow is completed.
13.6 Leaf revocation
The CLI does not provide a cert retire command. A leaf is revoked, not retired:
sslteam cert revoke \
--issuance-id <issuance-uuid> \
--confirm <same-issuance-uuid> \
--reason "service decommissioned"
Use --purge-local only after confirming that local artifact removal is intended:
sslteam cert revoke \
--issuance-id <issuance-uuid> \
--confirm <same-issuance-uuid> \
--reason "leaf key compromise" \
--purge-local \
--out-dir "$LEAF_ARTIFACT_DIR"
Server revocation occurs before local purge. If purge fails, the server revocation remains successful and the CLI reports that local files were not removed. Remove them through a separately controlled process.
13.7 Audit revocations
sslteam cert revocations \
--limit 50
The limit must be 1–100. Preserve the event type, resource identifier, reason code, result, and correlation ID as bounded operational metadata.
13.8 Concurrency conflicts
Lifecycle mutations are protected by server-side optimistic concurrency. A conflict means the state changed between inspection and mutation. The CLI must not claim success and must not retry with a guessed identifier or weaker validation.
Safe response:
- preserve the displayed correlation ID;
- rerun the relevant inventory/status command;
- review the current state and authorization;
- issue a new command with the current exact identifier and confirmation.
14. Automation boundary
Suitable automation includes:
- reviewed PEM trust-store configuration;
- password-file authentication with secret-manager input;
ping, CA readiness, Intermediate status, and leaf inventory checks;- approved leaf issuance with explicit SANs;
- public certificate and chain publication;
- expiry monitoring and controlled leaf revocation.
Keep human-gated:
- first-use fingerprint approval;
- application Root setup and Root backup custody;
- offline Root signing;
- changed TOFU fingerprint approval;
- Root or Intermediate retirement/revocation;
- private-key and passphrase handling.
Never make an unattended job approve a changed fingerprint, create a Root backup in a shared workspace, print a password, or publish a complete leaf artifact bundle.
15. Failure classification and response
| Failure | Classification | Safe response |
|---|---|---|
| Invalid or ambiguous origin | Configuration | Correct the exact HTTPS origin; do not guess a hostname or port. |
| TLS trust or hostname mismatch | Security policy | Stop. Verify the certificate and identity independently; never weaken TLS. |
| Changed TOFU fingerprint | Security event | Investigate, then use explicit tls replace only after verification. |
| Expired Intermediate request | Stale workflow | Create a fresh request and manifest. |
| 401 or expired session | Authentication | Authenticate again; do not copy or edit token files. |
| 403 or scope denial | Authorization | Use an authorized account/scope; do not change scope blindly. |
| CA not ready | Prerequisite | Complete the approved Root/Intermediate workflow. |
| Optimistic-lock conflict | Concurrent state change | Re-read inventory and retry only with current state. |
| Existing output file/directory | Safe write refusal | Choose a new protected destination or use --force only after review for public material. |
| Missing Java/Firefox prerequisite | Local integration | Set JAVA_HOME or install Mozilla NSS tools; do not substitute another tool. |
For unexpected failures, preserve the CLI’s correlation ID and inspect the local CLI log after redacting sensitive material. Never attach tokens, passphrases, private keys, CSRs, PEM bodies, raw requests, or raw responses to an issue.
16. Session cleanup
End the current session when work is complete:
sslteam auth logout
Revoke every server session associated with the CLI account only when that broader action is intended:
sslteam auth logout-all
Both commands clear local credentials. A server confirmation failure is reported separately from local cleanup; preserve its correlation ID.