Serveur ACME
local-cert expose un point d'entrée ACME (RFC 8555) sur /acme/directory. Tout outil qui sait demander un certificat à Let's Encrypt peut le demander à local-cert à la place, pour des hôtes que Let's Encrypt ne pourrait jamais joindre.
https://certs.example.com/acme/directoryCe que c'est, et ce que ce n'est pas
Ce n'est pas une autorité de certification. local-cert ne signe rien : il sert d'intermédiaire entre votre client ACME et Let's Encrypt, et le certificat que vous recevez est un vrai certificat Let's Encrypt, reconnu partout.
Le problème qu'il règle : un client ACME classique prouve qu'il contrôle un nom en répondant sur le port 80 (HTTP-01), ce qui suppose que Let's Encrypt puisse atteindre la machine. Sur un LAN, c'est impossible. La preuve par DNS (DNS-01) fonctionne, mais oblige à donner des credentials DNS à chaque machine. local-cert garde ces credentials pour lui et fait la preuve DNS à la place du client.
Comment un certificat est émis
- Enregistrement. Le client crée son compte ACME en présentant un identifiant EAB. Une seule fois ; ensuite il signe avec sa propre clé de compte.
- Commande. Le client demande un certificat pour un ou plusieurs noms. local-cert vérifie qu'ils appartiennent à un domaine géré, et que l'identifiant EAB y a droit. Sinon la commande est refusée tout de suite.
- Challenge. local-cert propose un challenge HTTP-01, comme une CA ordinaire. Le client prépare sa réponse et signale qu'il est prêt.
- Validation réelle. local-cert ne va jamais chercher la réponse HTTP. À la place, il ouvre une commande chez Let's Encrypt, écrit l'enregistrement TXT
_acme-challengedans votre zone, attend sa propagation, fait valider, puis supprime l'enregistrement. Le challenge du client passe àvalidquand c'est terminé. - Finalisation. Le client envoie son CSR. local-cert le transmet à Let's Encrypt et renvoie la chaîne de certificats. La clé privée n'a jamais quitté le client.
Les identifiants EAB
EAB signifie External Account Binding. C'est le mécanisme prévu par ACME pour qu'une CA n'accepte que les clients qu'elle connaît déjà : au moment de créer son compte, le client prouve qu'il détient un secret remis à l'avance. Ici, c'est ce qui remplace la clé d'API.
Un identifiant EAB se compose de deux valeurs, plus l'URL du serveur :
| Valeur | Où la trouver | Dans ce guide |
|---|---|---|
| Directory ACME | fixe pour chaque instance | https://certs.example.com/acme/directory |
| Key ID (kid) | Clés & droits → Identifiants EAB | eab_XXXXXXXXXXXXXXXX |
| Clé HMAC | affichée une seule fois à la création | CLE_HMAC |
Il se crée dans Clés & droits → Identifiants EAB → + nouvel identifiant, avec :
- un nom, pour savoir à quel client il a été remis ;
- une expiration facultative ;
- les domaines autorisés : le client ne peut demander de certificats que sous ceux-là.
Ce qu'il faut savoir
- La clé HMAC n'est affichée qu'une fois. Perdue, il faut créer un nouvel identifiant.
- Le client ne s'en sert qu'à l'enregistrement, mais local-cert relit l'identifiant à chaque requête : le révoquer ou le laisser expirer coupe aussi les clients déjà enregistrés.
- Un identifiant peut servir à plusieurs clients. Un identifiant par client permet de les couper séparément et de savoir qui a émis quoi.
- La clé est encodée en base64url, le format attendu par tous les clients (
hmacEncoded,--eab-hmac-key,mac_key…).
Ce que le client doit savoir faire
Trois choses, que la quasi-totalité des clients ACME modernes proposent :
- utiliser une URL de directory personnalisée ;
- s'enregistrer avec un External Account Binding ;
- résoudre un challenge HTTP-01.
| Outil | Support | Guide |
|---|---|---|
| Traefik | natif | ouvrir |
| Caddy | natif | ouvrir |
| Apache httpd | natif (mod_md) | ouvrir |
| Nginx | via certbot ou acme.sh | ouvrir |
| HAProxy | via acme.sh | ouvrir |
| Nginx Proxy Manager | import manuel | ouvrir |
| Kubernetes | natif (cert-manager) | ouvrir |
| Dokploy | natif (Traefik) | ouvrir |
| Coolify | natif (Traefik) | ouvrir |
| Synology DSM | via acme.sh | ouvrir |
| Proxmox VE | natif (pvenode) | ouvrir |
| certbot, acme.sh, lego | natif | ouvrir |
Pour tout le reste, voir Autres systèmes.
Règles et limites
- Un nom hors des domaines gérés est refusé (
rejectedIdentifier) ; un domaine non autorisé pour l'identifiant aussi (unauthorized). - Tous les noms d'une même commande doivent appartenir au même domaine géré.
- Les jokers (
*.home.example.com) sont acceptés : la validation réelle étant faite en DNS-01, la restriction habituelle de HTTP-01 ne s'applique pas. Certains clients refusent toutefois d'eux-mêmes un joker en HTTP-01. - Ces certificats apparaissent dans Certificats avec le type de clé
external, sans clé privée ni renouvellement automatique : c'est le client qui renouvelle. - Un compte ACME peut révoquer les certificats qu'il a obtenus. La rotation de clé de compte (
keyChange) n'est pas implémentée.
Dépannage
| Symptôme | Cause |
|---|---|
JWS "url" is … but this endpoint is … | local-cert est derrière un proxy qui ne transmet pas X-Forwarded-Proto / X-Forwarded-Host. Transmettez-les, ou fixez la variable PUBLIC_URL. |
externalAccountRequired | Le client s'enregistre sans EAB. Vérifiez sa configuration. |
unauthorized à l'enregistrement | Identifiant inconnu, révoqué ou expiré, ou clé HMAC erronée. |
rejectedIdentifier | Le nom demandé n'est sous aucun domaine géré. |
| Le client abandonne après ~1 minute | Son délai d'attente est plus court que la validation DNS. Relancez : la commande en cours est reprise. |
| Erreur TLS vers local-cert | local-cert est servi avec un certificat que le client ne reconnaît pas. Servez-le avec un certificat public, ou ajoutez sa CA au magasin du client. |