TLS Configuration (Client)

Chronicle .NET clients communicate with Chronicle Server over TLS. The server always serves its single port over TLS — in development it generates a self-signed certificate automatically — so the client connects over TLS by default.

For server-side TLS configuration, see TLS Configuration (Server).

appsettings.json

{
  "Cratis": {
    "Chronicle": {
      "ConnectionString": "chronicle://localhost:35000",
      "Tls": {
        "CertificatePath": "/path/to/certificate.pfx",
        "CertificatePassword": "your-password"
      }
    }
  }
}

Client options

C#

public static class TlsClientOptions
{
    public static ChronicleClient Create()
    {
        var options = new ChronicleOptions
        {
            ConnectionString = "chronicle://localhost:35000",
            Tls = new Tls
            {
                CertificatePath = "/path/to/certificate.pfx",
                CertificatePassword = "your-password"
            }
        };

        return new ChronicleClient(options);
    }
}

Kotlin

Kotlin does not support this workflow yet.

Java

Java does not support this workflow yet.

Elixir

defmodule MyApp.TlsClientOptions do
  @moduledoc false

  def start_link do
    children = [
      {Chronicle.Client,
       connection_string:
         "chronicle://localhost:35000?certificatePath=/path/to/certificate.pfx&certificatePassword=your-password"}
    ]

    Supervisor.start_link(children, strategy: :one_for_one)
  end
end

TypeScript

TypeScript does not support this workflow yet.

Properties

Property	Type	Default	Description
CertificatePath	string	null	Path to the client certificate (PFX format) if mutual TLS is used
CertificatePassword	string	null	Password for the certificate file
SkipCertificateValidation	boolean	true	When true, the client connects over TLS but does not validate the server’s certificate

Certificate validation

The client always connects over TLS, but by default it does not validate the server’s certificate — any certificate, including a self-signed one, is accepted. That default is deliberate: Chronicle Server generates a self-signed certificate on every start when none is configured, and it is never written to disk or added to a trust store, so there is nothing a client could validate it against. Skipping validation is what lets a development server and client talk to each other with no certificate setup on either side.

Once you run against a server whose certificate is verifiable, turn validation on with skipTlsValidation=false in the connection string:

C#

public static class ConfigurationTlsValidationEnabled
{
    public static ChronicleOptions Create() =>
        ChronicleOptions.FromConnectionString(
            "chronicle://my-server:35000?skipTlsValidation=false");
}

Kotlin

import io.cratis.chronicle.ChronicleOptions

fun optionsWithTlsValidationEnabled(): ChronicleOptions =
    ChronicleOptions.fromConnectionString("chronicle://my-server:35000?skipTlsValidation=false")

Java

import io.cratis.chronicle.ChronicleOptions;

class ConfigurationTlsValidationEnabled {
    ChronicleOptions create() {
        return ChronicleOptions.fromConnectionString("chronicle://my-server:35000?skipTlsValidation=false");
    }
}

Elixir

defmodule MyApp.TlsValidationEnabled do
  @moduledoc false

  def connection_string do
    Chronicle.Connections.ConnectionString.parse(
      "chronicle://my-server:35000?skipTlsValidation=false"
    )
  end
end

TypeScript

import { ChronicleOptions } from '@cratis/chronicle';

function createConfigurationTlsValidationEnabled(): ChronicleOptions {
    return ChronicleOptions.fromConnectionString('chronicle://my-server:35000?skipTlsValidation=false');
}

You can also set it on the client’s TLS options as SkipCertificateValidation = false. Either setting alone is enough — the two combine so that whichever one asks for validation wins, and an omitted second setting can never silently turn validation back off.

To go the other way and skip explicitly:

C#

public static class TlsConnectionStringSkipValidation
{
    public static ChronicleOptions Create() =>
        ChronicleOptions.FromConnectionString("chronicle://localhost:35000?skipTlsValidation=true");
}

Kotlin

import io.cratis.chronicle.ChronicleOptions

fun optionsSkippingTlsValidation(): ChronicleOptions =
    ChronicleOptions.fromConnectionString("chronicle://localhost:35000?skipTlsValidation=true")

Java

import io.cratis.chronicle.ChronicleOptions;

class TlsConnectionStringSkipValidation {
    ChronicleOptions create() {
        return ChronicleOptions.fromConnectionString("chronicle://localhost:35000?skipTlsValidation=true");
    }
}

Elixir

defmodule MyApp.TlsConnectionStringSkipValidation do
  @moduledoc false

  def connection_string do
    Chronicle.Connections.ConnectionString.parse(
      "chronicle://localhost:35000?skipTlsValidation=true"
    )
  end
end

TypeScript

import { ChronicleOptions } from '@cratis/chronicle';

function createTlsConnectionStringSkipValidation(): ChronicleOptions {
    return ChronicleOptions.fromConnectionString('chronicle://localhost:35000?skipTlsValidation=true');
}

Caution

The default accepts any server certificate, which removes protection against man-in-the-middle attacks. Set skipTlsValidation=false for anything reachable beyond a trusted network — and always over the public internet.

Development vs production

• Development: the server serves TLS with an auto-generated self-signed certificate and the client skips validation by default, so a development client connects out of the box — no certificate setup is needed on either side.
• Production: give the server a real certificate and set skipTlsValidation=false so the client validates it with the standard TLS rules.

With validation enabled, the standard TLS rules apply: valid certificates are accepted without extra configuration, and a certificate that fails validation — including a self-signed one — is rejected unless you configure a matching client certificate.

Troubleshooting

Client connection errors

Error: “The remote certificate is invalid”

You only see this once you have opted into validation with skipTlsValidation=false.

Solutions:

1. Ensure the server certificate is valid, not expired, and trusted by the client.
2. If the server uses a self-signed certificate on a trusted network, drop skipTlsValidation=false from the connection string to fall back to the default of accepting it.
3. In development no configuration is needed — the client skips validation by default, so the server’s auto-generated certificate is accepted as-is.