TLS and certificates

TLS and mTLS problems between clients and APISIX, between APISIX and etcd, and between APISIX and upstreams can manifest as handshake failures, certificate warnings, or connection resets.

TLS handshake failure

Symptoms

The client receives 525 SSL handshake failed, 400, or connection reset.
Downstream or upstream TLS negotiation fails.

Likely causes

Certificate is expired or self-signed and untrusted.
SNI does not match the certificate.
Protocol or cipher mismatch.
Intermediate certificate is missing.

Checks

[TODO] Add commands to inspect certificate validity, SNI, and supported protocols/ciphers.

Resolution

[TODO] Add steps to replace or trust the certificate, configure SNI, and set compatible cipher suites.

Verification

[TODO] Add an openssl s_client test command.

Escalation data

Certificate chain and expiration dates
APISIX SSL object configuration
Client TLS version and SNI

mTLS between client and APISIX

Symptoms

Clients with valid certificates are rejected.
400 or 403 with client-certificate verification enabled.

Likely causes

Client certificate is not signed by the configured CA.
ssl_trusted_certificate is missing or incorrect.
ssl_verify_client is enabled but not required.

Checks

[TODO] Add commands to verify the CA file and client certificate.

Resolution

[TODO] Add steps to trust the correct CA, enable ssl_verify_client as needed, and reload the SSL configuration.

Verification

[TODO] Add a test request with a valid client certificate.

Escalation data

CA bundle
Client certificate subject and issuer
ssl configuration in config.yaml

mTLS between APISIX and etcd

Escalation data

etcd and APISIX certificate files
config.yaml TLS settings
etcd and APISIX startup logs