| name | tls-cert-preflight |
| description | Use when validating TLS certs before deploying an endpoint. |
| version | 1.0.0 |
| category | devops |
| triggers | ["certs were handed over or dropped in and need verification","nginx -t fails with cannot load certificate / PEM_read_bio_PrivateKey","TLS clients reject a deployed endpoint","verifying Let's Encrypt or self-signed cert material before a restart"] |
TLS Cert Pair Preflight
"A cert file exists at the configured path" is NOT a working cert. Placeholder and broken drops are
common — hand-copied intermediates, headerless DER keys, mismatched key/cert. Validate the pair
BEFORE nginx -t / reload / restart: an endpoint that starts and silently rejects every TLS handshake
wastes a whole debug cycle.
Quick probe
bash ~/.hermes/skills/devops/tls-cert-preflight/scripts/verify-ssl-pair.sh <fullchain.pem> <privkey.pem>
Exit 0 = usable server pair; 1 = failures found, each named. Reproduce the checks by hand with:
- parse + metadata:
openssl x509 -in fullchain.pem -noout -subject -issuer -dates
- SAN present:
openssl x509 -in fullchain.pem -noout -ext subjectAltName
(empty or "No extensions" = dead — modern clients reject)
- NOT a CA cert:
openssl x509 -in fullchain.pem -noout -text | grep CA:TRUE
(a CA/intermediate cert can never serve a hostname)
- key parses:
openssl pkey -in privkey.pem -noout
(fails on headerless DER: a ~100-200-byte file with no -----BEGIN line)
- key matches cert: compare DER SHA256 of cert pubkey vs key pubkey (see script)
Fingerprints of a broken/placeholder cert drop (live-verified 2026-08-30)
| Symptom | Meaning |
|---|
Basic Constraints: CA:TRUE + no SAN | PEM is an intermediate/CA cert (e.g. CN=YE1 / "Root YE" test chain), not a server leaf |
| ~3-year validity | Real Let's Encrypt leaves = 90 days; multi-year = hand-made/copied placeholder |
nginx -t: cannot load certificate key ... PEM_read_bio_PrivateKey() failed | key is headerless DER (missing PEM armor) — re-armor or replace |
| key parses but different curve/size than cert (e.g. P-256 key beside P-384 cert) | mismatched pair — replace both files |
No /etc/letsencrypt/renewal/<domain>.conf, no archive/, live files owned by a user | certbot never issued it; cert is not managed or renewable |
When nginx is involved
- Run the probe BEFORE
nginx -t. A pair issue shows up as either cannot load certificate key
(unarmored/mismatched key) or as a config that tests clean but serves a broken handshake.
- The full nginx deployment flow (upstream config, single-listener rule, multi-layer testing, htpasswd)
lives in the
nginx-web-app-deployment skill.
Staging while real certs are pending
Keep the proxy layer testable via curl -k with a SAN-correct self-signed pair:
openssl req -x509 -newkey rsa:2048 -keyout privkey.pem -out fullchain.pem -days 90 -nodes \
-subj "/CN=DOMAIN" -addext "subjectAltName=DNS:DOMAIN,DNS:localhost"
Verify with the probe, swap into the live dir, restart. Real certs drop in later with just a reload.
Pitfalls
- DNS reality beats assumptions: before deciding which domain a cert must cover, resolve it. In the
2026-08-30 case both realgospelmessage.com AND .org resolved to the same public IP, and the service
.env pointed at .org while the user referenced .com certs — check the actual URL the client uses.
- certbot sudoers rules ≠ certbot installed: NOPASSWD rules can exist for a binary that isn't
there (
command not found). Policy presence is not binary presence.
- Ownership smell: live-dir files owned by an unprivileged user, no
cert.pem/chain.pem/
privkey.pem quartet → hand-placed, not certbot-managed.
- Check before asking: all of the above are observable with openssl/getent/ls — verify first,
then ask the user only for the real cert material or a root path to place it.
