TLS : ce qui se règle

La surface TLS de Pingclair est volontairement petite : un nom obtient un certificat automatiquement, et les réglages qui décident comment sont ceux documentés ici. Tout le reste que Caddy accepte est refusé par son nom plutôt qu’ignoré, donc une configuration ne fait jamais silencieusement moins que ce qu’elle annonce. Cette page rassemble ce qui fonctionne réellement, mesuré sur une vraie machine, et ce qui ne fonctionne pas.

🧾 Avant de commencer

Pingclair installé et en service (Installation).
Pour les parties liées à l’autorité de certification, un nom qui résout vers l’hôte, ou l’autorité interne pour une machine de laboratoire (HTTPS).

🌐 Quels protocoles sont servis

L’ensemble des protocoles vit dans le bloc global servers :

{
    servers {
        protocols h1 h2 h3
    }
}

Mesuré avec sudo ss -lun | grep ':443 ' :

Configuration	Écouteur UDP 443
`protocols h1 h2`	0 — pas de HTTP/3
`protocols h1 h2 h3`	1 — HTTP/3 activé

⚠️ Cette liste décide HTTP/3, et rien d’autre. Lister h1 seul ne retire pas HTTP/2 : avec protocols h1, un client qui proposait h2 en ALPN négociait encore HTTP/2. Le compilateur reporte cette liste sur l’interrupteur HTTP/3 (config.global.http3 = protocols.contains(H3)), donc aucun réglage ne désactive HTTP/2 pour un nom.

Par site, http3 off sort ce nom de HTTP/3 sans arrêter l’écouteur QUIC :

https://internal.test {
    tls {
        internal
        http3 off
    }
    file_server /srv/site
}

🏛️ Sources de certificats

Trois sources, toutes montrées sur la page HTTPS :

Source	Configuration	Usage
Let’s Encrypt	un nom public nu	Noms publics, renouvelés en arrière-plan.
Autorité interne	`tls internal`	Noms de laboratoire, origines privées, tunnels.
Vos fichiers	`tls { cert … key … }`	Certificats émis ailleurs.

Le renouvellement tourne tout seul ; renewal_window_ratio, dans les options globales, change à quel point il commence tôt, en fraction de la durée de vie de chaque certificat.

🔐 Certificats clients

client_auth exige un certificat du client. Générez une petite autorité et un certificat client avec openssl, puis pointez le site vers le fichier de l’autorité :

https://internal.test {
    tls {
        internal
        client_auth {
            mode require_and_verify
            trusted_ca_cert_file /etc/pingclair/client-ca.crt
        }
    }
    file_server /srv/site
}

Mesuré : une requête sans certificat client échoue à la poignée de main, et la même requête avec --cert client.crt --key client.key répond 200.

Les modes sont request, require, verify_if_given et require_and_verify, et il n’y a pas de repli : un mode mal orthographié est refusé avec la liste entière (expected request, require, verify_if_given or require_and_verify).

⚠️ trusted_ca_cert prend le certificat en ligne, et trusted_ca_cert_file prend un chemin. Utiliser le premier avec un chemin compile, puis échoue au démarrage avec trusted_ca_cert is not a certificate: not valid base64: Invalid symbol 45 — le - de -----BEGIN. Le fichier doit aussi être lisible par l’utilisateur pingclair.

📦 Déplacer le magasin de certificats

Le magasin contient les certificats émis, le compte ACME et l’autorité interne, et il vit dans /var/lib/pingclair/.local/share/pingclair — le répertoire de données du compte de service. PINGCLAIR_TLS_STORE le nomme quand une commande tourne sous un autre utilisateur, d’où le préfixe des exemples ci-dessous : la valeur par défaut de root serait /root/.local/share/pingclair. storage-export et storage-import le déplacent :

sudo PINGCLAIR_TLS_STORE=/var/lib/pingclair/.local/share/pingclair pingclair storage-export -o /tmp/store.tar
sudo systemctl stop pingclair
sudo rm -rf /var/lib/pingclair/.local/share/pingclair
sudo mkdir -p /var/lib/pingclair/.local/share/pingclair && sudo chown pingclair:pingclair /var/lib/pingclair/.local/share/pingclair
sudo PINGCLAIR_TLS_STORE=/var/lib/pingclair/.local/share/pingclair pingclair storage-import -i /tmp/store.tar
sudo systemctl start pingclair

✅ Store exported to /tmp/store.tar
✅ Store imported into /var/lib/pingclair/.local/share/pingclair

Trois détails issus de l’exécution. L’archive est un tar simple, quel que soit son nom, et elle est écrite en mode 600 : la relire demande root. L’import restaure la propriété enregistrée dans l’archive. Et le magasin contient autosave.json, la configuration que l’Admin API a appliquée en dernier, donc un import la restaure aussi.

Si le service refuse ensuite de démarrer avec Internal CA I/O error: Permission denied, les fichiers du magasin ne sont pas inscriptibles par le compte de service : sudo chown -R pingclair:pingclair /var/lib/pingclair/.local/share/pingclair corrige, et le site répond de nouveau.

🚫 Ce qui ne se règle pas

Voici des réglages Caddy que Pingclair reconnaît et refuse, pour que le fichier ne tourne jamais avec le réglage silencieusement abandonné :

Caddy-compatible directive 'tls ciphers' is not supported by Pingclair yet: Pingclair does not implement this TLS option yet
Caddy-compatible directive 'tls curves' is not supported by Pingclair yet: Pingclair does not implement this TLS option yet
Caddy-compatible directive 'tls alpn' is not supported by Pingclair yet: Pingclair does not implement this TLS option yet
Caddy-compatible directive 'tls on_demand' is not supported by Pingclair yet: Pingclair does not implement this TLS option yet

Concrètement : les suites de chiffrement, les courbes, la liste ALPN et l’émission à la demande relèvent du binaire, pas de la configuration ; l’agrafage OCSP et preferred_chains ne sont pas implémentés non plus. Si l’un compte pour vous, c’est une demande de fonctionnalité, pas une erreur de configuration.

⚠️ Quand cela ne marche pas

client_auth refuse de démarrer avec not valid base64. Un chemin a été donné à trusted_ca_cert ; l’orthographe fichier est trusted_ca_cert_file.
Un client avec un certificat valide est rejeté. Vérifiez que l’autorité qui l’a signé est celle de trusted_ca_cert_file, et que le certificat n’a pas expiré.
tls ciphers / tls curves / tls alpn / tls on_demand refusent le fichier. Ils ne sont pas implémentés ; voir la section ci-dessus.
HTTP/3 tourne encore après protocols h1 h2. Ce ne devrait pas être le cas : c’est cette liste qui le commande. Si UDP 443 écoute encore, le fichier en service n’est pas celui que vous avez édité (ce que signifie un rechargement).
Le service ne démarre plus après un déplacement de magasin. La propriété, comme ci-dessus.

🧭 Étapes suivantes

HTTPS : les quatre façons d’obtenir un certificat, avec leurs lignes de journal exactes.
HTTP/3 : l’activer et prouver qu’un client l’a utilisé.
tls : la référence de la directive.

🛡️TLS : ce qui se règle