TLS handshake fails after certificate renewal

When TLS handshake fails after certificate renewal, remember: with AT-TLS the application never sees certificates — the PAGENT policy and the key ring do all the work, so that is where you look.

What it means

• A handshake failure is almost never random: it is an expired certificate, a missing chain certificate, or a label the policy does not expect.
• Certificates are per-LPAR objects — a certificate installed on one LPAR does not exist on another until it is replicated.
• The side that reports the handshake error is where diagnosis starts; check that side first.

Common causes

• Server certificate expired — check the dates with RACDCERT LIST.
• Key ring missing an intermediate CA certificate, so the peer cannot build the trust chain.
• Certificate label in the AT-TLS policy does not match the actual RACDCERT label (common after renewals).
• AT-TLS rule matches the wrong connection (port or IP range) and applies the wrong policy.
• TLS version or cipher mismatch after a renewal hardened the settings on one side only.

How to diagnose

• RACDCERT ID(userid) LIST — shows the key ring, certificate labels, and expiry dates.
• RACDCERT CHECKCERT('label') — validates the dates and signature of one certificate.
• RACDCERT LISTRING(ringname) ID(userid) — confirms which certificates are actually connected to the ring.
• Check the PAGENT policy TTLSRule and TTLSKeyRingParms for the port in question.
• Compare the certificate on this LPAR with the working LPAR when it works on one system only.

How to fix it

• Renew with RACDCERT, reconnect the new certificate to the key ring, then refresh PAGENT.
• Add the missing intermediate CA to the ring with RACDCERT CONNECT.
• Correct the label in the AT-TLS policy to match RACDCERT, then refresh the policy.

Example: Certificate checks

PAGENT must be refreshed after any AT-TLS policy change, or the old policy keeps running.

Interview tip

• Q: TLS worked for a year, then broke the morning after a certificate renewal — like TLS handshake fails after certificate renewal. Your first three checks?
• A: First, RACDCERT LIST to confirm the new certificate dates and that it is connected to the right key ring. Second, compare the label with the AT-TLS policy — renewals often create a new label while the policy still names the old one. Third, verify the CA chain is complete on the ring.

Prevention checklist

• Monitor certificate expiry dates and alert 60 days before expiry.
• Keep the AT-TLS policy label and the RACDCERT label in the same change record.
• Replicate certificates to every LPAR in the sysplex, not just the one you tested.