Ballerina HTTP Client Rejects Self-Signed Certificates by Default: Trust Store or CA-Signed Cert?

The short answer

Pin the self-signed certificate in a per-client trust store when you have one or two stable endpoints and control both sides. Move the endpoint to a certificate signed by an internal CA as soon as the endpoint count grows, certificates rotate on a schedule, or clients you don't control need to connect. Either way, hostname verification still applies: connecting by IP address fails unless the certificate carries that IP in its Subject Alternative Name (SAN) extension.

1. Does a per-client trust store replace or extend JVM defaults?

Confirmed: a trust store configured through the client's secure socket configuration is scoped to that client instance. It does not touch the global cacerts file and does not affect other clients in the same process.

What is version-sensitive is whether your custom trust store replaces the JVM default trust material for that client or merges with it. The safe working assumption is replacement: if the client also calls public CA-signed endpoints, include the relevant CA certificates in the same store, or verify merge behavior against the API docs of your installed Swan Lake distribution. Field names on the secure socket record have shifted across releases, so check bal doc or the distribution's API docs rather than copying an older example.

Avoid the alternative of importing the self-signed certificate into the JVM-wide trust store: it widens trust for every TLS client in that JVM, which is broader than the problem requires.

2. Does hostname verification still reject IP-based access?

Yes. Trusting the certificate and passing hostname verification are independent checks inside the handshake. If you connect to https://10.0.0.5/... but the certificate's SAN lists only api.internal.example, the handshake fails even with the certificate pinned. The fix is one of:

• connect using the DNS name that matches the SAN, or
• re-issue the certificate with the IP address added as an IP-type SAN entry.

Note the diagnostic trap: DNS resolution is delegated to the JVM/OS resolver and completes before TLS starts, so a SAN mismatch surfaces as a generic SSL handshake error, not a name-resolution error. Inspect the certificate before assuming DNS is broken:

openssl s_client -connect api.internal.example:443 -servername api.internal.example \
  | openssl x509 -noout -text | grep -A1 "Subject Alternative Name"

3. When does pinning cost more than an internal CA?

Pinning is cheaper until rotation enters the picture. Compare the two operational loops:

The crossover arrives quickly: with rotation every 90 days (common for automated issuance) and more than a handful of clients, the coordinated redistribution of pins becomes the dominant cost and the dominant outage risk — a client holding the old pin fails the moment the server swaps. An internal CA converts rotation into a server-side-only operation.

Recommendation and one caveat

For a single caller integrating with one such endpoint, pin per client now and connect by the SAN's DNS name. If the endpoint's certificate will rotate, or more consumers are coming, invest in the internal CA instead. The documented validation-bypass mode disables TLS's security guarantees; keep it confined to isolated local testing. One detail worth confirming before you commit: whether your installed release's secure socket configuration replaces default trust material, since that determines whether mixed traffic (self-signed plus public endpoints) needs a combined store.