Does Couchbase SDK hostname verification fail when the node certificate SAN omits the bootstrap hostname?

Does Hostname Verification Fail Without the Bootstrap Hostname?

Yes. If you use couchbases://, the Couchbase SDK performs standard TLS hostname verification. If the hostname provided in the connection string (the bootstrap host) is not present in the server certificate's Subject Alternative Names (SAN), the TLS handshake will fail with a hostname mismatch error before the SDK can even begin the bootstrap process.

Verification Logic: Bootstrap vs. Topology Refresh

The SDK performs hostname verification at two distinct stages of the connection lifecycle:

• Bootstrap Phase: The SDK validates the certificate of the node it first contacts against the bootstrap hostname used in the connection string. If this is a DNS alias or a load balancer address, that specific name must be in the SAN.
• Topology Refresh Phase: After bootstrapping, the cluster provides a map of all nodes in the cluster. The SDK then establishes connections to these nodes using the advertised addresses. Each of these connections is validated against the specific address the cluster advertised for that node.

Required SAN Entries for Success

To ensure verification succeeds across all phases, the cluster certificates must contain the following in their SAN entries:

Connection Stage	Required SAN Entry
Bootstrap	The bootstrap hostname/alias used in the connection string.
DNS SRV	Any aliases returned by SRV records used for discovery.
Topology Refresh	The actual hostnames or IP addresses each node uses to identify itself.

Practical Verification

To diagnose a mismatch, use OpenSSL to check the certificate presented by the bootstrap host:

openssl s_client -connect bootstrap-host:11207 -servername bootstrap-host | openssl x509 -text -noout

Search the output for the Subject Alternative Name section. If the bootstrap-host is missing, the SDK will reject the connection.

Assumptions and Constraints

This behavior is consistent across major SDK versions (Java, .NET, Node.js), though the specific exception thrown may vary by language. This analysis assumes standard TLS verification; if you have disabled hostname verification in your SDK configuration (not recommended for production), these checks are bypassed.

Missing Diagnostic Detail: Are you using a single global certificate for the cluster or unique certificates per node? If using per-node certificates, the bootstrap alias must be added to every node's certificate to ensure the SDK can bootstrap via any available node.