acme: Module de gestion automatique des certificats (ACMEv2) pour NGINX

Installation

Vous pouvez installer ce module dans toute distribution basée sur RHEL, y compris, mais sans s'y limiter :

RedHat Enterprise Linux 7, 8, 9 et 10
CentOS 7, 8, 9
AlmaLinux 8, 9
Rocky Linux 8, 9
Amazon Linux 2 et Amazon Linux 2023

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 et Amazon Linux 2

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-acme

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-acme

Activez le module en ajoutant ce qui suit en haut de /etc/nginx/nginx.conf :

load_module modules/ngx_http_acme_module.so;

Ce document décrit nginx-module-acme v0.3.1 publié le 08 décembre 2025.

nginx-acme

nginx-acme est un module NGINX avec l'implémentation du protocole de gestion automatique des certificats (ACMEv2).

Le module implémente les spécifications suivantes :

RFC8555 (Environnement de gestion automatique des certificats) avec limitations :
- Seul le type de défi HTTP-01 est pris en charge
RFC8737 (Extension de défi de négociation de protocole de couche application TLS ACME (ALPN))
RFC8738 (Extension de validation d'identifiant IP ACME)
draft-ietf-acme-profiles (Extension de profils ACME, version 00)

Prise en main

checkout, configurer et construire NGINX à ../nginx

cd nginx-acme export NGINX_BUILD_DIR=$(realpath ../nginx/objs) cargo build --release

Le résultat sera situé à `target/release/libnginx_acme.so`.

Une autre façon est d'utiliser le script de configuration fourni :

```sh
## dans le répertoire source de NGINX
auto/configure \
    --with-compat \
    --with-http_ssl_module \
    --add-[dynamic-]module=/path/to/nginx-acme

Le résultat sera situé à objs/ngx_http_acme_module.so.

Actuellement, cette méthode produit une bibliothèque légèrement plus grande, car nous n'instruisons pas le linker à effectuer LTO et à supprimer le code inutilisé.

Tests

Le dépôt contient une suite de tests d'intégration basée sur les nginx-tests. La commande suivante construira le module et exécutera les tests :

## Chemin vers le checkout source de nginx, par défaut ../nginx si non spécifié.
export NGINX_SOURCE_DIR=$(realpath ../nginx)
## Chemin vers le checkout de nginx-tests ; par défaut ../nginx/tests si non spécifié.
export NGINX_TESTS_DIR=$(realpath ../nginx-tests)

make test

La plupart des tests nécessitent le binaire du serveur de test pebble dans le chemin, ou dans un emplacement spécifié via la variable d'environnement TEST_NGINX_PEBBLE_BINARY.

Comment utiliser

Ajoutez le module à la configuration de NGINX et configurez-le comme décrit ci-dessous. Notez que ce module nécessite une configuration de resolver dans le bloc http.

Exemple de configuration

resolver 127.0.0.1:53;

acme_issuer example {
    uri         https://acme.example.com/directory;
    # contact     [email protected];
    state_path  /var/cache/nginx/acme-example;
    accept_terms_of_service;
}

acme_shared_zone zone=ngx_acme_shared:1M;

server {
    listen 443 ssl;
    server_name  .example.test
                 192.0.2.1      # non pris en charge par certains serveurs ACME
                 2001:db8::1    # non pris en charge par certains serveurs ACME
                 ;

    acme_certificate example;

    ssl_certificate       $acme_certificate;
    ssl_certificate_key   $acme_certificate_key;

    # ne pas analyser le certificat à chaque requête
    ssl_certificate_cache max=2;
}

server {
    # l'écoute sur le port 80 est requise pour traiter les défis ACME HTTP-01
    listen 80;

    location / {
        return 404;
    }
}

Directives

[!IMPORTANT] La référence ci-dessous reflète la version de développement actuelle. Voir ngx_http_acme_module documentation sur nginx.org pour la dernière version publiée.

acme_issuer

Syntaxe : acme_issuer name { ... }

Par défaut : -

Contexte : http

Définit un objet émetteur de certificat ACME.

uri

Syntaxe : uri uri

Par défaut : -

Contexte : acme_issuer

L'URL du répertoire du serveur ACME. Cette directive est obligatoire.

account_key

Syntaxe : account_key alg[:size] | file

Par défaut : -

Contexte : acme_issuer

La clé privée du compte utilisée pour l'authentification des requêtes.

Valeurs acceptées :

ecdsa:256/384/521 pour les algorithmes de signature JSON Web ES256, ES384 ou ES512
rsa:2048/3072/4096 pour RS256.
Chemin de fichier pour une clé existante, utilisant l'un des algorithmes ci-dessus.

Les clés de compte générées sont préservées entre les rechargements, mais seront perdues au redémarrage à moins que state_path ne soit configuré.

challenge

Syntaxe : challenge type

Par défaut : http-01

Contexte : acme_issuer

Cette directive est apparue dans la version 0.2.0.

Spécifie le type de défi ACME à utiliser pour l'émetteur.

Valeurs acceptées :

http-01 (http)
tls-alpn-01 (tls-alpn)

Les défis ACME sont versionnés. Si un nom non versionné est spécifié, le module sélectionne automatiquement la dernière version implémentée.

contact

Syntaxe : contact URL

Par défaut : -

Contexte : acme_issuer

Définit un tableau d'URLs que le serveur ACME peut utiliser pour contacter le client concernant des problèmes de compte. Le schéma mailto: sera utilisé à moins qu'il ne soit spécifié explicitement.

external_account_key

Syntaxe : external_account_key kid file

Par défaut : -

Contexte : acme_issuer

Cette directive est apparue dans la version 0.2.0.

Spécifie un identifiant de clé kid et un file avec la clé MAC pour l'autorisation de compte externe.

La valeur data:key peut être spécifiée à la place du file, ce qui charge une clé directement à partir de la configuration sans utiliser de fichiers intermédiaires.

Dans les deux cas, la clé est censée être encodée en base64url.

preferred_chain

Syntaxe : preferred_chain name

Par défaut : -

Contexte : acme_issuer

Cette directive est apparue dans la version 0.3.0.

Spécifie la chaîne de certificats préférée.

Si le serveur ACME propose plusieurs chaînes de certificats, préférez la chaîne avec le certificat le plus élevé émis à partir du Nom Commun du Sujet name. S'il n'y a pas de correspondances, la chaîne par défaut sera utilisée.

profile

Syntaxe : profile name [require]

Par défaut : -

Contexte : acme_issuer

Cette directive est apparue dans la version 0.3.0.

Demande le profil de certificat name au serveur ACME.

Le paramètre require fera échouer les renouvellements de certificats si le serveur ne prend pas en charge le profil spécifié.

ssl_trusted_certificate

Syntaxe : ssl_trusted_certificate file

Par défaut : bundle CA système

Contexte : acme_issuer

Spécifie un file avec des certificats CA de confiance au format PEM utilisés pour vérifier le certificat du serveur ACME.

ssl_verify

Syntaxe : ssl_verify on | off

Par défaut : on

Contexte : acme_issuer

Active ou désactive la vérification du certificat du serveur ACME.

state_path

Syntaxe : state_path path | off

Par défaut : acme_<name>

Contexte : acme_issuer

Définit un répertoire pour stocker les données du module qui peuvent être persistées entre les redémarrages. Cela peut améliorer le temps de chargement en évitant certaines requêtes au démarrage, et éviter de dépasser les limites de taux de requêtes sur le serveur ACME.

Le répertoire contient des contenus sensibles, tels que la clé de compte, les certificats émis et les clés privées.

Le paramètre off (0.2.0) désactive le stockage des informations de compte et des certificats émis sur le disque.

Avant la version 0.2.0, le répertoire d'état n'était pas créé par défaut.

accept_terms_of_service

Syntaxe : accept_terms_of_service

Par défaut : -

Contexte : acme_issuer

Accepte les conditions de service sous lesquelles le serveur ACME sera utilisé. Certains serveurs exigent d'accepter les conditions de service avant l'enregistrement du compte. Les conditions sont généralement disponibles sur le site Web du serveur ACME, et l'URL sera imprimée dans le journal des erreurs si nécessaire.

acme_shared_zone

Syntaxe : acme_shared_zone zone=name:size

Par défaut : zone=ngx_acme_shared:256k

Contexte : http

Permet d'augmenter la taille du stockage en mémoire du module. La zone de mémoire partagée sera utilisée pour stocker les certificats émis, les clés et les données de défi pour tous les émetteurs de certificats configurés.

La taille de zone par défaut est suffisante pour contenir environ 50 clés ECDSA prime256v1 ou 35 clés RSA 2048.

acme_certificate

Syntaxe : acme_certificate issuer [identifier ...] [key=alg[:size]]

Par défaut : -

Contexte : server

Définit un certificat avec la liste des identifiers demandés à l'émetteur issuer.

La liste explicite des identifiants peut être omise. Dans ce cas, les identifiants seront pris à partir de la directive server_name dans le même bloc server. Tous les valeurs acceptées dans le server_name ne sont pas des identifiants de certificat valides : les expressions régulières et les jokers ne sont pas pris en charge.

Le paramètre key définit le type d'une clé privée générée. Algorithmes et tailles de clés pris en charge : ecdsa:256 (par défaut), ecdsa:384, ecdsa:521, rsa:2048, rsa:3072, rsa:4096.

Variables intégrées

Le module ngx_http_acme_module prend en charge les variables intégrées, valides dans le bloc server avec la directive acme_certificate :

`$acme_certificate`

Certificat SSL qui peut être passé à la ssl_certificate.

`$acme_certificate_key`

Clé privée du certificat SSL qui peut être passée à la ssl_certificate_key.

GitHub

Vous pouvez trouver des conseils de configuration supplémentaires et de la documentation pour ce module dans le dépôt GitHub pour nginx-module-acme.