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);
    }
}

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	false	When true, the client connects over TLS but does not validate the server’s certificate

Skipping certificate validation

The client always connects over TLS. By default it validates the server’s certificate using the standard TLS rules, so a self-signed certificate is rejected. To accept a self-signed (or otherwise untrusted) certificate — for example a Chronicle server on a trusted internal network — skip validation through the connection string:

C#

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

You can also set it on the client’s TLS options as SkipCertificateValidation = true.

Caution

Skipping validation accepts any server certificate, which removes protection against man-in-the-middle attacks. Only use it for a trusted server on a trusted network — never over the public internet. Prefer configuring a proper certificate the client can validate.

Development vs production

• Development: the server serves TLS with an auto-generated self-signed certificate. The built-in Development connection string sets skipTlsValidation=true, so a development client accepts that certificate out of the box — no certificate setup is needed on either side.
• Production: the server uses a real certificate you supply, and the client validates it with the standard TLS rules. Skipping validation is opt-in and off by default.

Certificate validation

The client validates server certificates using the standard TLS rules:

• Valid certificates are accepted without extra configuration.
• A certificate that fails validation — including a self-signed one — is rejected, unless you configure a matching client certificate or set skipTlsValidation.

Troubleshooting

Client connection errors

Error: “The remote certificate is invalid”

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, set skipTlsValidation=true in the connection string (or SkipCertificateValidation on the client’s TLS options).
3. In development, use the built-in Development connection string, which already skips validation for the server’s auto-generated certificate.