caddy-tls-file-pair

caddy-tls-file-pair is a Caddy certificate-manager module for passive TLS consumers. It reads an existing PEM certificate chain and private key from two fixed filesystem paths instead of obtaining or renewing a certificate.

The module ID is:

tls.get_certificate.file_pair

Build

Pin a release when building Caddy:

xcaddy build v2.11.4 \
  --with github.com/art12354/caddy-tls-file-pair@v0.2.0

Caddyfile

*.example.com {
    tls {
        get_certificate file_pair {
            names *.example.com
            cert /shared/certificates/wildcard.example.com.crt
            key /shared/certificates/wildcard.example.com.key
        }
    }

    reverse_proxy 127.0.0.1:8080
}

names is required and accepts exact DNS names and one-label wildcards. A wildcard such as *.example.com matches app.example.com, but not example.com or deep.app.example.com.

cert and key are required fixed paths. On every certificate-manager lookup, the module:

1. checks the requested SNI against names;
2. reads the certificate chain and private key;
3. verifies that they form a valid key pair; and
4. verifies that the leaf certificate covers the requested SNI.

It never constructs a path from client-supplied SNI.

Intended use

This module is designed for a single-issuer architecture:

ACME issuer -> shared filesystem -> passive Caddy consumers

Only the issuer should hold DNS provider credentials or configure an ACME issuer. Consumers use this module and must not manually load the same wildcard with tls <cert> <key>, because an already-cached certificate can be selected before an external manager is consulted.

The filesystem is in the TLS handshake path when a manager lookup occurs. Protect the private key, use reliable storage, and monitor read and handshake failures.

Development

go test ./...

The project is licensed under the MIT License.

Repositories

• Public/canonical module path: https://github.com/art12354/caddy-tls-file-pair
• Forgejo development origin: https://forgejo.arthursommer.com/arthur/caddy-tls-file-pair