ScyllaDB University Live | Free Virtual Training Event
Learn more
ScyllaDB Documentation Logo Documentation
  • Server
  • Cloud
  • Tools
    • ScyllaDB Manager
    • ScyllaDB Monitoring Stack
    • ScyllaDB Operator
  • Drivers
    • CQL Drivers
    • DynamoDB Drivers
  • Resources
    • ScyllaDB University
    • Community Forum
    • Tutorials
Download
ScyllaDB Docs ScyllaDB C# driver Features TLS/SSL

TLS/SSL¶

You can secure traffic between the driver and Apache Cassandra with TLS/SSL. There are two aspects to that:

  • Client-to-node encryption, where the traffic is encrypted and the client verifies the identity of the nodes it connects to.

  • Optional client certificate authentication, where server nodes also verify the identity of the client.

This section describes the driver-side configuration, it assumes that you’ve already configured SSL encryption in the server. If you’re using Apache Cassandra, you can checkout the documentation that covers the setup with Apache Cassandra.

You can find SSL examples on how to configure the driver for both server and client auth in the driver’s Github repository.

Driver configuration¶

Use Builder.WithSSL() method to enable client TLS/SSL encryption:

var cluster = Cluster.Builder()
    .AddContactPoints(...)
    .WithSSL()
    .Build();

Builder.WithSSL() and Builder.WithSSL(new SSLOptions()) enable TLS/SSL with the default configuration. The default configuration includes a RemoteCertificateValidationCallback that logs any errors returned by .NET’s SSL API.

To customize this configuration check out the several SSL options available on the SSLOptions class:

var cluster = Cluster.Builder()
    .AddContactPoints(...)
    .WithSSL(new SSLOptions().SetCertificateRevocationCheck(true))
    .Build();

The .NET SSL API will return a RemoteCertificateNameMismatch error when the HostName does not match the name on the server certificate. By default the driver performs reverse DNS resolution to obtain the HostName from the server node’s IP address. You can change this by providing a custom hostname resolver in the SSLOptions.SetHostNameResolver(...) method:

var cluster = Cluster.Builder()
    .AddContactPoints(...)
    .WithSSL(new SSLOptions().SetHostNameResolver(...))
    .Build();

Alternatively, you can provide your own RemoteCertificateValidationCallback to handle the SSL errors and perform your own validation logic (see below for an example of this). Note that you can introduce security vulnerabilities with this so you should avoid it if you can.

Enabling server authentication with a custom root certificate¶

If you have a custom (untrusted) root certificate, then there are two ways to provide it: using the system/user store or loading it manually in code.

Certificate store¶

On Windows, you can add this certificate to the Trusted Root Certification Authorities logical store. This can be done with certmgr.msc for example, which is a MMC (Microsoft Management Console) snap-in tool to manage certificates on Windows systems. On non Windows platforms, support for system/user certificate stores is limited and the location of this store depends on which SSL library is used so you might prefer loading the certificate manually in code.

Loading the certificate in code¶

An alternative to the certificate store is to load the certificate in code and provide a custom certificate validator using SSLOptions.SetRemoteCertValidationCallback(RemoteCertificateValidationCallback) that compares the root certificate of the chain returned by the server with your previously loaded root certificate.

Here is an example (CustomValidator here is a class that you would have to implement):

// custom validator
var certificateValidator = new CustomValidator(new X509Certificate2(@"C:\path\to\ca.crt"));

var cluster = Cluster.Builder()
    .AddContactPoints("...")
    .WithSSL(new SSLOptions().SetRemoteCertValidationCallback(
        (sender, certificate, chain, errors) => certificateValidator.Validate(sender, certificate, chain, errors)))
    .Build();

The examples on the driver’s repository have a basic custom certificate validator which can be used as a starting point.

Enabling client authentication¶

To enable client authentication, you need to provide the driver with the client certificate(s):

var cluster = Cluster.Builder()
    .AddContactPoints("...")
    .WithSSL(new SSLOptions()
        // set client certificate collection
        .SetCertificateCollection(new X509Certificate2Collection
        {
            // use the following constructor if the certificate is password protected
            new X509Certificate2(@"C:\path\to\client_cert.pfx", "cert_password"),

            // use the following constructor if the certificate is not password protected
            //new X509Certificate2(@"C:\path\to\client_cert.pfx")
        )
    )
    .Build();

If you prefer to use the certificate store you can use X509Store to obtain a collection of all installed certificates (optionally you can filter this collection before providing it to the driver so that it only contains the relevant certificate). On Windows, the following example works if you add the client certificate to the Personal logical store (using certmgr.msc for example as described previously).

X509Certificate2Collection collection;
using (var store = new X509Store(StoreLocation.LocalMachine))
{
    store.Open(OpenFlags.ReadOnly);
    collection = store.Certificates;
}

var cluster = Cluster.Builder()
    .AddContactPoints("...")
    .WithSSL(new SSLOptions().SetCertificateCollection(collection))
    .Build();

Was this page helpful?

PREVIOUS
Speculative query execution
NEXT
Tuning policies
  • Create an issue
  • Edit this page

On this page

  • TLS/SSL
    • Driver configuration
      • Enabling server authentication with a custom root certificate
        • Certificate store
        • Loading the certificate in code
      • Enabling client authentication
ScyllaDB C# driver
  • master
    • master
  • Features
    • Address resolution
    • Authentication and Authorization
    • Automatic failover
    • Column Encryption
    • Driver components
      • ADO.NET
      • Core component
        • Statements
          • Batch statements
          • Per-query keyspace
          • Prepared statements
          • Simple statements
      • Linq component
        • Batch statements with LINQ
      • Mapper component
        • Batch statements with the Mapper
    • Connection heartbeat
    • Connection pooling
    • CQL data types to C# types
      • Date and time representation
      • Nulls and unset
    • Execution Profiles
    • Graph support
    • Cluster and schema metadata
    • Metrics
      • App.Metrics Provider
      • List of metrics
    • Native protocol
    • OpenTelemetry
    • Result paging
    • Parameterized queries
    • Query timestamps
    • Query warnings
    • Request Tracker
    • Routing queries
    • Speculative query execution
    • TLS/SSL
    • Tuning policies
    • User-defined functions and aggregates
    • User-defined types
    • Vector support
  • FAQ
  • Upgrade Guide
  • Examples
  • API Reference
Docs Tutorials University Contact Us About Us
© 2025 ScyllaDB | Terms of Service | Privacy Policy | ScyllaDB, and ScyllaDB Cloud, are registered trademarks of ScyllaDB, Inc.
Last updated on 01 Aug 2025.
Powered by Sphinx 7.4.7 & ScyllaDB Theme 1.8.7
Ask AI