TLS¶

Verified TLS¶

Use a trusted CA bundle and hostname verification:

cluster := gocql.NewCluster("db.example.com")
cluster.SslOpts = &gocql.SslOptions{
	CaPath:                 "/etc/scylla/ca.crt",
	EnableHostVerification: true,
	Config: &tls.Config{
		MinVersion: tls.VersionTLS12,
		ServerName: "db.example.com",
	},
}

Set tls.Config.ServerName to a DNS name or IP address in the server certificate. Contact-point DNS names are resolved before the driver dials, so without an explicit server name the driver verifies the certificate against the resolved IP address. Configure a private CA in CaPath; do not disable verification to work around an untrusted or mismatched certificate.

Applications can construct the CA pool themselves when they need complete control over Go’s standard TLS configuration:

roots := x509.NewCertPool()
caPEM, err := os.ReadFile("/etc/scylla/ca.crt")
if err != nil {
	return err
}
if !roots.AppendCertsFromPEM(caPEM) {
	return errors.New("no CA certificates found")
}

cluster.SslOpts = &gocql.SslOptions{
	Config: &tls.Config{
		MinVersion: tls.VersionTLS12,
		RootCAs:    roots,
		ServerName: "db.example.com",
	},
}

Leave tls.Config.InsecureSkipVerify as false. Setting EnableHostVerification also forces verification on if the supplied tls.Config requested otherwise.

Mutual TLS¶

When the server requires a client certificate, provide both certificate and private-key files:

cluster.SslOpts = &gocql.SslOptions{
	CaPath:                 "/etc/scylla/ca.crt",
	CertPath:               "/etc/scylla/client.crt",
	KeyPath:                "/etc/scylla/client.key",
	EnableHostVerification: true,
	Config: &tls.Config{
		MinVersion: tls.VersionTLS12,
		ServerName: "db.example.com",
	},
}

CertPath and KeyPath must be supplied together. Protect the private key with restrictive filesystem permissions.

Custom dialers¶

ClusterConfig.Dialer handles TCP establishment; the driver still performs TLS configured by SslOpts.

ClusterConfig.HostDialer handles the entire connection, including TLS. SslOpts does not configure TLS on a custom HostDialer, so its implementation must perform certificate and hostname verification itself.

Troubleshooting¶

• x509: certificate signed by unknown authority: configure the self-signed root CA in CaPath or tls.Config.RootCAs, and ensure that the server sends any intermediate CA certificates needed to complete the chain.

• x509: certificate is valid for ...: set tls.Config.ServerName to a DNS name or IP address covered by the certificate, or issue a corrected certificate.

• Client certificate errors: verify that CertPath and KeyPath form a pair trusted by the server.