TLS and Certificates in Clockspring

TLS issues are one of the most common causes of Clockspring startup failures and connectivity problems. The root cause is usually not configuration syntax. It is misunderstanding what the certificate is being used for.

This article explains the basics and focuses on the failure modes people actually hit.

What TLS Is Used For in Clockspring

Clockspring uses TLS for multiple purposes, including:

• Secure communication between cluster nodes

• Secure communication with the Registry

• Secure outbound HTTPS calls to external systems

• Optional inbound HTTPS connections

Because of this, certificates are not optional in Clockspring.

Keystore vs Truststore (Plain English)

Keystore

A keystore proves who Clockspring is.

Used when:

• Clockspring accepts TLS connections

• Clockspring participates in mutual TLS

• Internal cluster communication occurs

If Clockspring is acting as a TLS endpoint, it needs a keystore.

Truststore

A truststore defines who Clockspring trusts.

Used when:

• Clockspring connects to other cluster nodes

• Clockspring connects to the Registry

• Clockspring calls external HTTPS endpoints

• Clockspring validates client certificates in mTLS

If Clockspring talks to something over TLS, it must trust the certificate authority.

The Most Common Certificate Failures

1. Certificate is valid, but not trusted

Symptoms:

• SSL handshake failures

• PKIX path building errors

• Strict SSL Validation failures

Cause:

• The issuing CA is missing from the truststore

Fix:

• Import the CA, not just the leaf certificate

2. Certificate hostname does not match

Symptoms:

• TLS errors even though the cert looks correct

Cause:

• Certificate CN or SAN does not match the hostname being used

Fix:

• Use the correct hostname

• Reissue the cert with proper SAN entries

3. Wrong certificate in the wrong place

Symptoms:

• Internal communication works but outbound HTTPS fails

• Or outbound works but cluster communication fails

Cause:

• Mixing up keystore and truststore purposes

Rule:

• Identity goes in the keystore

• Trust goes in the truststore

4. Expired certificates

Symptoms:

• Everything worked yesterday

• Nothing changed

• TLS suddenly fails

Cause:

• Certificates expired

Fix:

• Renew and redeploy

• Restart services that cache certificates

Self-Signed vs Internal CA Certificates

Self-signed certificates:

• Are fine for testing

• Must be explicitly trusted

• Do not scale well

Internal CA certificates:

• Are common in enterprise environments

• Require CA chain import into truststores

• Are preferred for long-term deployments

Clockspring does not care who issued the cert. It only cares whether it trusts it.

How to Debug TLS Issues Quickly

1. Identify which connection is failing

   • internal cluster

   • Registry

   • outbound API

2. Confirm which truststore is being used

3. Check the certificate chain, not just the leaf cert

4. Verify hostnames and expiration

5. Restart after changes

TLS failures are deterministic. Once you know which trust decision failed, the fix is usually obvious.

Summary

TLS issues in Clockspring usually come down to trust and identity, not configuration syntax.

• Keystores prove who Clockspring is

• Truststores define who Clockspring trusts

• Most failures are missing CA chains or hostname mismatches

Understand those basics, and TLS stops being mysterious.