Aller au contenu
local-cert
Parcourir la documentation

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.

Directory de cette instance
https://certs.example.com/acme/directory

Ce 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

  1. 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.
  2. 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.
  3. 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.
  4. 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-challenge dans votre zone, attend sa propagation, fait valider, puis supprime l'enregistrement. Le challenge du client passe à valid quand c'est terminé.
  5. 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 :

ValeurOù la trouverDans ce guide
Directory ACMEfixe pour chaque instancehttps://certs.example.com/acme/directory
Key ID (kid)Clés & droits → Identifiants EABeab_XXXXXXXXXXXXXXXX
Clé HMACaffichée une seule fois à la créationCLE_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 :

  1. utiliser une URL de directory personnalisée ;
  2. s'enregistrer avec un External Account Binding ;
  3. résoudre un challenge HTTP-01.
OutilSupportGuide
Traefiknatifouvrir
Caddynatifouvrir
Apache httpdnatif (mod_md)ouvrir
Nginxvia certbot ou acme.shouvrir
HAProxyvia acme.shouvrir
Nginx Proxy Managerimport manuelouvrir
Kubernetesnatif (cert-manager)ouvrir
Dokploynatif (Traefik)ouvrir
Coolifynatif (Traefik)ouvrir
Synology DSMvia acme.shouvrir
Proxmox VEnatif (pvenode)ouvrir
certbot, acme.sh, legonatifouvrir

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ômeCause
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.
externalAccountRequiredLe client s'enregistre sans EAB. Vérifiez sa configuration.
unauthorized à l'enregistrementIdentifiant inconnu, révoqué ou expiré, ou clé HMAC erronée.
rejectedIdentifierLe nom demandé n'est sous aucun domaine géré.
Le client abandonne après ~1 minuteSon délai d'attente est plus court que la validation DNS. Relancez : la commande en cours est reprise.
Erreur TLS vers local-certlocal-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.