filepair

README

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

Documentation

Overview

Package filepair provides a Caddy certificate manager which reads a PEM certificate chain and private key from separate, fixed filesystem paths.

Index

• type FilePair
  • func (FilePair) CaddyModule() caddy.ModuleInfo
  • func (f FilePair) GetCertificate(_ context.Context, hello *tls.ClientHelloInfo) (*tls.Certificate, error)
  • func (f *FilePair) Provision(caddy.Context) error
  • func (f *FilePair) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

Types

type FilePair

type FilePair struct {
	Names []string `json:"names,omitempty"`
	Cert  string   `json:"cert,omitempty"`
	Key   string   `json:"key,omitempty"`
}

FilePair reads the current certificate and key on every manager lookup. Names is an allowlist; entries may be exact DNS names or one-label wildcards.

func (FilePair) CaddyModule

func (FilePair) CaddyModule() caddy.ModuleInfo

func (FilePair) GetCertificate

func (f FilePair) GetCertificate(_ context.Context, hello *tls.ClientHelloInfo) (*tls.Certificate, error)

func (*FilePair) Provision

func (f *FilePair) Provision(caddy.Context) error

func (*FilePair) UnmarshalCaddyfile

func (f *FilePair) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile supports:

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