Let’s Encrypt avec Cert Warden

Let’s Encrypt avec Cert Warden (challenge DNS-01)

Cert Warden est un gestionnaire de certificats que vous hébergez vous-même. Il commande et renouvelle les certificats Let’s Encrypt et les distribue à vos serveurs. Avec les deux scripts ci-dessous, Cert Warden effectue la validation via notre API DNS, donc par le challenge DNS-01. Cela fonctionne sans port 80 ouvert, même pour des systèmes totalement injoignables depuis internet, ainsi que pour les certificats wildcard comme *.votredomaine.ch.

Conditions préalables

Le domaine doit pointer vers nos serveurs de noms, la zone DNS doit donc être hébergée chez FireStorm
L’accès API doit être activé dans l’espace client (admin.firestorm.ch => Compte => Profil client)
Une installation Cert Warden en service, généralement sous forme de conteneur Docker
curl doit être présent dans le conteneur. jq est utilisé s’il est disponible, mais n’est pas nécessaire

1. Créer une clé API

Connectez-vous à l’espace client et ouvrez Compte => Profil client.

Cochez Accès API et cliquez sur GÉRER LES CLÉS API.

Créez une nouvelle clé :

Désignation : par exemple certwarden
Domaines : sélectionnez les domaines concernés
Autoriser aussi la gestion DNS complète : cochez cette case

Notez la clé API. Elle n’est affichée qu’une seule fois.

2. Mettre les scripts en place

Placez les deux scripts sur le stockage persistant de votre conteneur Cert Warden, par exemple sous /app/data/scripts/ :

curl -o /app/data/scripts/firestorm_dns01_challenge_add.sh https://api.firestorm.ch/downloads/firestorm_dns01_challenge_add.txt
curl -o /app/data/scripts/firestorm_dns01_challenge_del.sh https://api.firestorm.ch/downloads/firestorm_dns01_challenge_del.txt
chmod 755 /app/data/scripts/firestorm_dns01_challenge_add.sh /app/data/scripts/firestorm_dns01_challenge_del.sh

Si vous téléchargez les fichiers depuis un ordinateur Windows, veillez à les enregistrer avec des fins de ligne Unix. Sinon, le conteneur signale bad interpreter au démarrage du script.

3. Créer le challenge provider dans Cert Warden

Ouvrez la rubrique Providers dans Cert Warden et créez un New Challenge Provider.

Champ	Valeur
Provider Type	`DNS-01 Manual Script`
Domains	Votre domaine, par exemple `votredomaine.ch`
Post Provision Wait	`300`
Environment Variables	`FIRESTORM_API_KEY=VOTRE-CLE-API`
Path to DNS Record Create Script	`/app/data/scripts/firestorm_dns01_challenge_add.sh`
Path to DNS Record Delete Script	`/app/data/scripts/firestorm_dns01_challenge_del.sh`

Enregistrez avec SUBMIT. Vous pouvez ensuite commander un certificat : Cert Warden pose l’enregistrement TXT tout seul et le supprime après la validation.

Autres réglages

Les scripts se pilotent par des variables d’environnement. Seule la clé API est obligatoire, tout le reste est facultatif :

Variable	Signification
`FIRESTORM_API_KEY`	Votre clé API. Seule indication obligatoire
`FIRESTORM_ZONE_ID`	ID de zone fixe. Si elle reste vide, le script cherche lui-même la zone correspondante via la liste des zones. Avec une clé limitée à certaines zones qui n’a pas le droit de voir cette liste, indiquez l’ID ici
`FIRESTORM_TTL`	Durée de validité de l’enregistrement TXT, valeur par défaut `60`
`FIRESTORM_TIMEOUT`	Délai d’attente de l’appel API en secondes, valeur par défaut `180`
`FIRESTORM_DEBUG`	`1` inscrit les requêtes et les réponses dans le journal, la clé y reste masquée

Cet appel vous donne l’ID de zone :

curl -H "X-Api-Key: VOTRE-CLE-API" https://api.firestorm.ch/dns/v1/zones

Tester à la main

Les deux scripts peuvent être appelés directement, également depuis d’autres clients ACME. L’essai à blanc ne change rien et montre seulement ce qui serait envoyé :

FIRESTORM_API_KEY=VOTRE-CLE-API ./firestorm_dns01_challenge_add.sh --dry-run "_acme-challenge.test.votredomaine.ch" "valeurtest"

Sans --dry-run, l’enregistrement est réellement posé puis supprimé :

FIRESTORM_API_KEY=VOTRE-CLE-API ./firestorm_dns01_challenge_add.sh "_acme-challenge.test.votredomaine.ch" "valeurtest"
FIRESTORM_API_KEY=VOTRE-CLE-API ./firestorm_dns01_challenge_del.sh "_acme-challenge.test.votredomaine.ch" "valeurtest"

Avec --help, les scripts affichent leur description complète.

Dépannage

La création prend une à deux minutes
C’est voulu. Pour les enregistrements de challenge, notre API attend elle-même que tous nos serveurs de noms connaissent la valeur avant de répondre. Le script n’est donc pas bloqué, il attend.

« Échec de l’authentification »
Vérifiez la clé API et si l’accès API est activé dans le profil client. Après plusieurs tentatives erronées, notre protection bloque temporairement l’adresse IP.

« Accès refusé »
La clé est limitée à certains domaines et la zone demandée n’en fait pas partie, ou la gestion DNS complète n’a pas été autorisée lors de la création.

« Aucune zone correspondante trouvée »
Le domaine n’existe pas comme zone dans votre compte, ou la clé n’a pas le droit de le voir. Dans ce cas, indiquez FIRESTORM_ZONE_ID explicitement.

« bad interpreter » au démarrage du script
Le fichier a des fins de ligne Windows. Enregistrez-le avec des fins de ligne Unix ou exécutez sed -i 's/\r$//' firestorm_dns01_challenge_add.sh dans le conteneur.

La validation échoue bien que l’enregistrement soit posé
Augmentez la valeur de Post Provision Wait dans Cert Warden.

D’autres instructions sur notre interface se trouvent dans l’article API DNS. Ces scripts nous ont aimablement été mis à disposition par l’un de nos clients.