Client ACME Lego - WildCard SSL

Un guide détaillé pour le déploiement d'un certificat SSL WildCard (étoile) via le client ACME Lego et la validation API DNS avec l'hébergement web VEDOS. La procédure est destinée aux certificats de type example.com et *.example.com, où le renouvellement doit être automatique sans saisie manuelle des enregistrements TXT. Le guide utilise un certificat ACME de l'autorité de certification Certum. Le certificat utilisé ne sert que d'exemple – le principe de fonctionnement et la procédure de déploiement ACME sont les mêmes pour toutes les autorités de certification.

Le guide utilise une syntaxe vérifiée sur Lego 5.2.2. Lego v5 a modifié certains paramètres par rapport aux versions plus anciennes, donc en cas d'erreur telle que flag provided but not defined, vérifiez la syntaxe correcte à l'aide de lego accounts register --help, lego run --help ou lego --help.

Concepts de base

• ACME – protocole pour l'émission et le renouvellement automatisés des certificats SSL/TLS.
• Lego – un client ACME écrit en Go. Il peut effectuer la validation DNS via de nombreux fournisseurs DNS (liste des fournisseurs DNS pris en charge).
• DNS-01 – validation via l'enregistrement DNS TXT _acme-challenge. Elle est requise pour les certificats WildCard.
• EAB kid + hmac – détails External Account Binding (EAB) fournis par l'autorité de certification. Ils relient ACME client à un compte ou à un produit.
• VEDOS WAPI – l'interface API de VEDOS par laquelle Lego crée et supprime les enregistrements DNS TXT.
• Service systemd - un fichier de configuration qui indique au système Linux comment démarrer une application et la maintenir en fonctionnement même après un redémarrage du serveur.

Dans tous les exemples présentés, remplacez le domaine example.com par votre propre domaine.

Installation de Lego

apt update
apt install -y curl tar

cd /tmp
LEGO_URL=$(curl -s https://api.github.com/repos/go-acme/lego/releases/latest | sed -n 's/.*"browser_download_url": "\(.*linux_amd64.tar.gz\)".*/\1/p' | head -n1)
echo "$LEGO_URL"
curl -L -o lego.tar.gz "$LEGO_URL"
tar -xzf lego.tar.gz
install -m 0755 lego /usr/local/bin/lego
lego --version

Après une installation réussie, nous recommandons de supprimer les fichiers temporaires.

rm -f /tmp/lego /tmp/lego.tar.gz /tmp/LICENSE /tmp/CHANGELOG.md

Fournisseur d'API DNS

Ce guide utilise l'API DNS du registraire de domaines Vedos, qui propose une API pour gérer le DNS des domaines enregistrés. Pour l'hébergement web Vedos, vous devez activer WAPI et également renseigner les adresses IP autorisées ainsi que le mot de passe WAPI.

Adresses IP du serveur VPS

curl -4 ifconfig.me
curl -6 ifconfig.me

Dans le champ Adresses IP autorisées, saisissez toutes les adresses IP sortantes de votre serveur, généralement à la fois IPv4 et IPv6. Les valeurs sont séparées par un espace. VEDOS n'autorise les requêtes API que depuis les adresses IP indiquées.
Important : si vous n'autorisez que l'IPv4 et qu'une requête API sort en IPv6, l'émission du certificat peut réussir, mais le nettoyage des enregistrements TXT échouera avec l'erreur Access not allowed from this IP address.

Valeurs recommandées pour le fournisseur DNS VEDOS

Apache, webroot

La configuration de base d'Apache est un élément d'appoint. La validation DNS s'effectue via l'API DNS, et non via HTTP, mais le vhost Apache est nécessaire pour servir le site web après l'émission du certificat.

cd /var/www
apt update
apt install -y apache2
systemctl enable --now apache2
a2enmod rewrite headers ssl
systemctl reload apache2

DOMAIN="example.com"
mkdir -p /var/www/$DOMAIN/public
chown -R www-data:www-data /var/www/$DOMAIN
chmod -R 755 /var/www/$DOMAIN
echo "OK $DOMAIN" > /var/www/$DOMAIN/public/index.html

cat > /etc/apache2/sites-available/$DOMAIN.conf <<EOF
<VirtualHost *:80>
    ServerName $DOMAIN
    ServerAlias *.$DOMAIN

    DocumentRoot /var/www/$DOMAIN/public
    <Directory /var/www/$DOMAIN/public>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog \${APACHE_LOG_DIR}/${DOMAIN}_error.log
    CustomLog \${APACHE_LOG_DIR}/${DOMAIN}_access.log combined
</VirtualHost>
EOF

a2ensite $DOMAIN.conf
apache2ctl configtest
systemctl reload apache2
curl -I http://$DOMAIN

Fichiers de configuration de Lego

L'approche recommandée pour Lego v5 est de stocker les paramètres dans un fichier de configuration. Le service systemd n'a alors pas besoin de contenir une longue commande avec les domaines, le fournisseur DNS et les hooks.

Fichier de configuration .env

Le fichier .env est un fichier de configuration texte dans lequel sont stockées des variables d'environnement, par exemple des identifiants d'accès, des clés API ou des paramètres d'application. Pour plus de clarté, vous pouvez nommer le fichier provider-domain.env. Le fichier vedos-example.com.env contiendra les identifiants de connexion VEDOS WAPI, nous le stockons donc dans /etc/lego et lui appliquons des permissions restreintes.

DOMAIN="example.com"

mkdir -p /etc/lego/$DOMAIN
nano /etc/lego/vedos-$DOMAIN.env

Dans la configuration ci-dessous, remplacez WEDOS_LOGIN par votre identifiant VEDOS et WEDOS_WAPI_PASSWORD par le mot de passe généré dans VEDOS WAPI. Vous pouvez laisser les valeurs de timeout et d'intervalle telles quelles.

WEDOS_USERNAME='WEDOS_LOGIN'
WEDOS_WAPI_PASSWORD='WEDOS_WAPI_PASSWORD'
WEDOS_PROPAGATION_TIMEOUT=3600
WEDOS_POLLING_INTERVAL=30
WEDOS_TTL=300

Fichier de configuration lego.yml

Le fichier .yml est un fichier de configuration texte au format YAML, utilisé pour une notation claire des paramètres, des options et des données structurées. Avant d'enregistrer la configuration YAML, remplacez example.com par votre propre domaine, *.example.com par le nom wildcard, vas@email.cz par votre e-mail de contact et les valeurs KID / HMAC par les détails de votre commande de certificat ACME. Des noms tels que certum-example ou example-com-wildcard sont des étiquettes internes ; vous pouvez les laisser, mais avec plusieurs domaines il est conseillé de les renommer selon le domaine.

mkdir /etc/lego/$DOMAIN
nano /etc/lego/$DOMAIN/lego.yml

storage: /etc/lego/example.com

accounts:
  certum-example:
    server: certum
    email: vas@email.cz
    acceptsTermsOfService: true
    eab:
      kid: KID
      hmacKey: HMAC

servers:
  certum:
    url: https://acme.certum.pl/directory

challenges:
  vedos-dns:
    dns:
      provider: vedos
      envFile: /etc/lego/vedos-example-com.env
      resolvers:
        - 1.1.1.1:53

certificates:
  example-com-wildcard:
    account: certum-example
    challenge: vedos-dns
    domains:
      - example.com
      - "*.example.com"
    renew:
      days: 30

hooks:
  deploy:
    command: systemctl reload apache2

Émission du certificat

Avant l'exécution, remplacez example.com dans le chemin par le domaine que vous avez utilisé lors de la création du répertoire. La première exécution crée le compte ACME, définit les enregistrements DNS TXT via l'API DNS, effectue la validation DNS-01 et enregistre le certificat.

Pendant l'attente, Lego peut afficher :

Cela signifie que Lego vérifie le DNS toutes les 30 secondes et attend au maximum 1 heure. Après le succès, vérifiez les fichiers :

Le répertoire certificates/ contient les .crt, .key émis, les certificats intermédiaires de l'autorité de certification et les métadonnées.

Procédure CLI alternative pour Lego v5

lego accounts register \
  --path /etc/lego/example.com \
  --server https://acme.certum.pl/directory \
  --email vas@email.cz \
  --accept-tos \
  --eab \
  --eab.kid 'KID' \
  --eab.hmac 'HMAC'

set -a
. /etc/lego/vedos-example.com.env
set +a

lego run \
  --path /etc/lego/example.com \
  --server https://acme.certum.pl/directory \
  --email vas@email.cz \
  --dns vedos \
  --dns.resolvers 1.1.1.1:53 \
  --domains example.com \
  --domains '*.example.com'

Déploiement du certificat vers Apache

Avant de créer le vhost HTTPS, remplacez example.com par votre propre domaine dans le nom du fichier, les valeurs ServerName et ServerAlias, les chemins du webroot et les chemins du certificat. Ces chemins doivent correspondre au domaine utilisé dans la configuration de Lego.

cat > /etc/apache2/sites-available/example.com-le-ssl.conf <<'EOF'
<IfModule mod_ssl.c>
<VirtualHost *:443>
    ServerName example.com
    ServerAlias *.example.com

    DocumentRoot /var/www/example.com/public
    <Directory /var/www/example.com/public>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    SSLEngine on
    SSLCertificateFile /etc/lego/example.com/certificates/example.com.crt
    SSLCertificateKeyFile /etc/lego/example.com/certificates/example.com.key

    ErrorLog ${APACHE_LOG_DIR}/example.com_ssl_error.log
    CustomLog ${APACHE_LOG_DIR}/example.com_ssl_access.log combined
</VirtualHost>
</IfModule>
EOF

a2ensite example.com-le-ssl.conf
apache2ctl configtest
systemctl reload apache2

curl -I https://example.com
curl -I https://test.example.com

Renouvellement automatique

Lego peut renouveler le certificat, mais après l'installation il ne crée pas de timer systemd de lui-même. L'exécution régulière est configurée via un service et un timer personnalisés. Avant l'insertion, remplacez example-com dans le nom du service/timer par votre propre nom sûr sans points, par exemple mojedomena-cz, et remplacez example.com dans le chemin de configuration par votre propre domaine.

cat > /etc/systemd/system/lego-example-com-renew.service <<'EOF'
[Unit]
Description=Renew Certum WildCard SSL for example.com using Lego and VEDOS DNS
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/lego --config /etc/lego/example.com/lego.yml
EOF

cat > /etc/systemd/system/lego-example-com-renew.timer <<'EOF'
[Unit]
Description=Daily Lego renewal check for example.com

[Timer]
OnCalendar=*-*-* 03:20:00
RandomizedDelaySec=1800
Persistent=true

[Install]
WantedBy=timers.target
EOF

systemctl daemon-reload
systemctl enable --now lego-example-com-renew.timer
systemctl list-timers | grep lego

Test sûr du service :

systemctl start lego-example-com-renew.service
journalctl -u lego-example-com-renew.service -n 100 --no-pager

Si le certificat n'est pas proche de l'expiration, Lego peut signaler que le renouvellement n'est pas nécessaire. C'est un comportement correct.

Erreurs courantes

Paramètre inconnu dans Lego

Dans Lego v5, les paramètres EAB sont --eab.kid et --eab.hmac. Les paramètres appartiennent toujours à une sous-commande spécifique.

lego accounts register --help
lego accounts list --help
lego run --help

Le nettoyage des enregistrements TXT échoue sur une IP non autorisée

Ajoutez également l'adresse IPv6 du serveur aux adresses IP autorisées dans VEDOS WAPI. Le certificat peut être émis correctement, mais les enregistrements TXT resteront dans le DNS après la validation.

Liste de vérification

dig TXT _acme-challenge.example.com +short
lego --config /etc/lego/example.com/lego.yml
systemctl status lego-example-com-renew.timer
apache2ctl configtest
curl -I https://example.com

Où aller ensuite ?

• Protocole ACME
• Client ACME Lego
• Client ACME Certbot
• Certificat SSL - Tout ce qu'il faut savoir