TLS Connection Policies

Connection policies govern the establishment of TLS connections. They control cipher suites, protocol versions, client authentication, and other handshake parameters.

Connection Policy

Connection policies are evaluated in order; the first matching policy will be used to configure the TLS connection.

An empty policy is valid. Safe and sensible defaults will be used.

Policy Matching

match

object

How to match this policy with a TLS ClientHello.If this policy is the first to match, it will be used. Available matchers:

sni - Server Name Indication
remote_ip - Client IP address
Other custom connection matchers

TLS Protocol Settings

cipher_suites

array

The list of cipher suites to support.

Caddy’s defaults are modern and secure. Only customize if you have specific requirements.

Supported cipher suites:

TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
TLS_AES_128_GCM_SHA256 (TLS 1.3)
TLS_AES_256_GCM_SHA384 (TLS 1.3)
TLS_CHACHA20_POLY1305_SHA256 (TLS 1.3)

curves

array

The list of elliptic curves to support.Caddy’s defaults are modern and secure.Supported curves:

x25519
secp256r1 (P-256)
secp384r1 (P-384)
secp521r1 (P-521)

protocol_min

string

default:"tls1.2"

Minimum TLS protocol version to allow.Values: tls1.2, tls1.3

TLS 1.0 and 1.1 are deprecated and insecure. Caddy only supports TLS 1.2 and 1.3.

protocol_max

string

default:"tls1.3"

Maximum TLS protocol version to allow.Values: tls1.2, tls1.3

alpn

array

Protocols to use for Application-Layer Protocol Negotiation (ALPN) during the handshake.Default: ["h2", "http/1.1"] (enables HTTP/2 and HTTP/1.1)

Certificate Selection

certificate_selection

object

How to choose a certificate if more than one matches the given ServerName (SNI) value.Can specify criteria like public key algorithm, serial number, subject organization, etc.

default_sni

string

DefaultSNI becomes the ServerName in a ClientHello if there is no policy configured for the empty SNI value.

fallback_sni

string

FallbackSNI becomes the ServerName in a ClientHello if the original ServerName doesn’t match any certificates in the cache.

EXPERIMENTAL: Subject to change or removal.

Use cases are very niche. Typically useful if a client (like a CDN) passes through the ServerName of the downstream handshake but can accept a certificate with the origin’s hostname instead.

Client Authentication

client_authentication

object

Enables and configures TLS client authentication (mutual TLS).

client_authentication.mode

string

The mode for authenticating the client.

Mode	Description
`request`	Ask clients for a certificate, but allow even if there isn’t one; do not verify it
`require`	Require clients to present a certificate, but do not verify it
`verify_if_given`	Ask clients for a certificate; allow even if there isn’t one, but verify it if there is
`require_and_verify`	Require clients to present a valid certificate that is verified

Default is require_and_verify if trust pool is provided; otherwise require.

client_authentication.trust_pool

object

Certificate authority module which provides the certificate pool of trusted certificates.Available providers:

inline - Base64 DER-encoded CA certificates
file - Load CA certificates from PEM files
pki - Use CA from Caddy’s PKI app

client_authentication.verifiers

array

Client certificate verification modules.These can perform custom client authentication checks, such as ensuring the certificate is not revoked.Available verifiers:

leaf - Verify against specific leaf certificates

Advanced Settings

drop

boolean

default:"false"

Reject TLS connections that match this policy.

EXPERIMENTAL: May change.

insecure_secrets_log

string

Also known as “SSLKEYLOGFILE”. TLS secrets will be written to this file in NSS key log format.

ENABLING THIS LOG COMPROMISES SECURITY! This allows other programs or tools to decrypt TLS connections. Only use for debugging and troubleshooting.

EXPERIMENTAL: Subject to change or removal.

Configuration Examples

Basic Connection Policy

{
  "apps": {
    "http": {
      "servers": {
        "srv0": {
          "tls_connection_policies": [
            {
              "match": {
                "sni": ["example.com", "*.example.com"]
              },
              "protocol_min": "tls1.2",
              "protocol_max": "tls1.3"
            }
          ]
        }
      }
    }
  }
}

Client Authentication (Mutual TLS)

{
  "tls_connection_policies": [
    {
      "client_authentication": {
        "mode": "require_and_verify",
        "trust_pool": {
          "provider": "file",
          "pem_files": ["/path/to/client-ca.pem"]
        }
      }
    }
  ]
}

Inline CA Certificates

{
  "client_authentication": {
    "mode": "require_and_verify",
    "trust_pool": {
      "provider": "inline",
      "trusted_ca_certs": [
        "base64-encoded-der-certificate-1",
        "base64-encoded-der-certificate-2"
      ]
    }
  }
}

Leaf Certificate Verification

{
  "client_authentication": {
    "mode": "require_and_verify",
    "verifiers": [
      {
        "verifier": "leaf",
        "leaf_certs_loaders": [
          {
            "loader": "file",
            "files": ["/path/to/client-cert.pem"]
          }
        ]
      }
    ]
  }
}

Custom Cipher Suites

{
  "tls_connection_policies": [
    {
      "cipher_suites": [
        "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384",
        "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"
      ],
      "curves": ["x25519", "secp256r1"]
    }
  ]
}

SNI-Based Policy Matching

{
  "tls_connection_policies": [
    {
      "match": {
        "sni": ["api.example.com"]
      },
      "client_authentication": {
        "mode": "require_and_verify",
        "trust_pool": {
          "provider": "file",
          "pem_files": ["/etc/caddy/api-clients-ca.pem"]
        }
      }
    },
    {
      "match": {
        "sni": ["example.com", "www.example.com"]
      }
    }
  ]
}

Caddyfile Configuration

Basic TLS Settings

example.com {
  tls {
    protocols tls1.2 tls1.3
    ciphers TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  }
}

Client Authentication

example.com {
  tls {
    client_auth {
      mode require_and_verify
      trust_pool file {
        pem_file /path/to/client-ca.pem
      }
    }
  }
}

Multiple Policies

{
  servers {
    srv0 {
      tls_connection_policy {
        match {
          sni api.example.com
        }
        client_auth {
          mode require_and_verify
          trust_pool file {
            pem_file /etc/caddy/api-ca.pem
          }
        }
      }
      
      tls_connection_policy {
        match {
          sni example.com
        }
      }
    }
  }
}

api.example.com {
  respond "API Server"
}

example.com {
  respond "Web Server"
}

Session Tickets

Caddy automatically manages session tickets for resumption unless disabled:

{
  "apps": {
    "tls": {
      "session_tickets": {
        "disabled": false
      }
    }
  }
}

Session tickets are automatically disabled when client authentication is enabled to prevent privilege escalation across virtual hosts.

Best Practices

Default Settings: Caddy’s default cipher suites and protocols are carefully selected for security and compatibility. Only customize if you have specific requirements.

Client Authentication: When using mutual TLS, ensure proper certificate validation. Use the appropriate mode for your security requirements.

Protocol Versions: TLS 1.3 offers better performance and security. Only allow TLS 1.2 if you need to support older clients.

Cipher Suites: Weak cipher suites are not supported by Caddy. The available suites are all considered secure for modern use.

Common Use Cases

API with Client Certificates

{
  "tls_connection_policies": [
    {
      "match": {
        "sni": ["api.example.com"]
      },
      "client_authentication": {
        "mode": "require_and_verify",
        "trust_pool": {
          "provider": "file",
          "pem_files": ["/etc/caddy/client-ca.pem"]
        }
      },
      "alpn": ["h2"]
    }
  ]
}

Internal Services (TLS 1.3 only)

{
  "tls_connection_policies": [
    {
      "protocol_min": "tls1.3",
      "protocol_max": "tls1.3"
    }
  ]
}

Legacy Client Support

If you must support very old clients (not recommended):

{
  "tls_connection_policies": [
    {
      "protocol_min": "tls1.2",
      "cipher_suites": [
        "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384",
        "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
        "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
        "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"
      ]
    }
  ]
}

HTTP

TLS

Other Modules

TLS Connection Policies

Connection Policy

Policy Matching

TLS Protocol Settings

Certificate Selection

Client Authentication

Advanced Settings

Configuration Examples

Basic Connection Policy

Client Authentication (Mutual TLS)

Inline CA Certificates

Leaf Certificate Verification

Custom Cipher Suites

SNI-Based Policy Matching

Caddyfile Configuration

Basic TLS Settings

Client Authentication

Multiple Policies

Session Tickets

Best Practices

Common Use Cases

API with Client Certificates

Internal Services (TLS 1.3 only)

Legacy Client Support

Build docs developers (and LLMs) love

HTTP

TLS

Other Modules

​Connection Policy

​Policy Matching

​TLS Protocol Settings

​Certificate Selection

​Client Authentication

​Advanced Settings

​Configuration Examples

​Basic Connection Policy

​Client Authentication (Mutual TLS)

​Inline CA Certificates

​Leaf Certificate Verification

​Custom Cipher Suites

​SNI-Based Policy Matching

​Caddyfile Configuration

​Basic TLS Settings

​Client Authentication

​Multiple Policies

​Session Tickets

​Best Practices

​Common Use Cases

​API with Client Certificates

​Internal Services (TLS 1.3 only)

​Legacy Client Support

Build docs developers (and LLMs) love

Connection Policy

Policy Matching

TLS Protocol Settings

Certificate Selection

Client Authentication

Advanced Settings

Configuration Examples

Basic Connection Policy

Client Authentication (Mutual TLS)

Inline CA Certificates

Leaf Certificate Verification

Custom Cipher Suites

SNI-Based Policy Matching

Caddyfile Configuration

Basic TLS Settings

Client Authentication

Multiple Policies

Session Tickets

Best Practices

Common Use Cases

API with Client Certificates

Internal Services (TLS 1.3 only)

Legacy Client Support