acme: Módulo de gestión automática de certificados (ACMEv2) para NGINX

Instalación

Puedes instalar este módulo en cualquier distribución basada en RHEL, incluyendo, pero no limitado a:

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

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 y 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

Habilita el módulo añadiendo lo siguiente en la parte superior de /etc/nginx/nginx.conf:

load_module modules/ngx_http_acme_module.so;

Este documento describe nginx-module-acme v0.3.1 lanzado el 08 de diciembre de 2025.

nginx-acme

nginx-acme es un módulo de NGINX con la implementación del protocolo de gestión automática de certificados (ACMEv2).

El módulo implementa las siguientes especificaciones:

RFC8555 (Entorno de Gestión Automática de Certificados) con limitaciones:
- Solo se admite el tipo de desafío HTTP-01
RFC8737 (Extensión de Desafío de Negociación de Protocolo de Capa de Aplicación TLS (ALPN) de ACME)
RFC8738 (Extensión de Validación de Identificador IP de ACME)
draft-ietf-acme-profiles (Extensión de Perfiles de ACME, versión 00)

Comenzando

checkout, configurar y construir NGINX en ../nginx

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

El resultado se ubicará en `target/release/libnginx_acme.so`.

Otra forma es usar el script de configuración proporcionado:

```sh
## en el directorio fuente de NGINX
auto/configure \
    --with-compat \
    --with-http_ssl_module \
    --add-[dynamic-]module=/path/to/nginx-acme

El resultado se ubicará en objs/ngx_http_acme_module.so.

Actualmente, este método produce una biblioteca ligeramente más grande, ya que no instruimos al enlazador para realizar LTO y eliminar el código no utilizado.

Pruebas

El repositorio contiene un conjunto de pruebas de integración basado en nginx-tests. El siguiente comando construirá el módulo y ejecutará las pruebas:

## Ruta al checkout de la fuente de nginx, por defecto es ../nginx si no se especifica.
export NGINX_SOURCE_DIR=$(realpath ../nginx)
## Ruta al checkout de nginx-tests; por defecto es ../nginx/tests si no se especifica.
export NGINX_TESTS_DIR=$(realpath ../nginx-tests)

make test

La mayoría de las pruebas requieren el binario del servidor de pruebas pebble en la ruta, o en una ubicación especificada a través de la variable de entorno TEST_NGINX_PEBBLE_BINARY.

Cómo Usar

Agrega el módulo a la configuración de NGINX y configúralo como se describe a continuación. Ten en cuenta que este módulo requiere una configuración de resolver en el bloque http.

Ejemplo de Configuración

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      # no soportado por algunos servidores ACME
                 2001:db8::1    # no soportado por algunos servidores ACME
                 ;

    acme_certificate example;

    ssl_certificate       $acme_certificate;
    ssl_certificate_key   $acme_certificate_key;

    # no parsear el certificado en cada solicitud
    ssl_certificate_cache max=2;
}

server {
    # el listener en el puerto 80 es necesario para procesar los desafíos HTTP-01 de ACME
    listen 80;

    location / {
        return 404;
    }
}

Directivas

[!IMPORTANTE] La referencia a continuación refleja la versión actual en desarrollo. Consulta la documentación de ngx_http_acme_module en nginx.org para la última versión publicada.

acme_issuer

Sintaxis: acme_issuer nombre { ... }

Predeterminado: -

Contexto: http

Define un objeto emisor de certificados ACME.

uri

Sintaxis: uri uri

Predeterminado: -

Contexto: acme_issuer

La URL del directorio del servidor ACME. Esta directiva es obligatoria.

account_key

Sintaxis: account_key alg[:size] | file

Predeterminado: -

Contexto: acme_issuer

La clave privada de la cuenta utilizada para la autenticación de solicitudes.

Valores aceptados:

ecdsa:256/384/521 para algoritmos de firma JSON Web ES256, ES384 o ES512
rsa:2048/3072/4096 para RS256.
Ruta de archivo para una clave existente, utilizando uno de los algoritmos anteriores.

Las claves de cuenta generadas se conservan entre recargas, pero se perderán al reiniciar a menos que se configure state_path.

challenge

Sintaxis: challenge tipo

Predeterminado: http-01

Contexto: acme_issuer

Esta directiva apareció en la versión 0.2.0.

Especifica el tipo de desafío ACME que se utilizará para el emisor.

Valores aceptados:

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

Los desafíos ACME están versionados. Si se especifica un nombre no versionado, el módulo selecciona automáticamente la última versión implementada.

contact

Sintaxis: contact URL

Predeterminado: -

Contexto: acme_issuer

Establece un array de URLs que el servidor ACME puede usar para contactar al cliente con respecto a problemas de la cuenta. Se utilizará el esquema mailto: a menos que se especifique explícitamente.

external_account_key

Sintaxis: external_account_key kid file

Predeterminado: -

Contexto: acme_issuer

Esta directiva apareció en la versión 0.2.0.

Especifica un identificador de clave kid y un file con la clave MAC para autorización de cuenta externa.

El valor data:key puede especificarse en lugar del file, lo que carga una clave directamente desde la configuración sin usar archivos intermedios.

En ambos casos, se espera que la clave esté codificada en base64url.

preferred_chain

Sintaxis: preferred_chain nombre

Predeterminado: -

Contexto: acme_issuer

Esta directiva apareció en la versión 0.3.0.

Especifica la cadena de certificados preferida.

Si el servidor ACME ofrece múltiples cadenas de certificados, se prefiere la cadena con el certificado superior emitido desde el Nombre Común del Sujeto nombre. Si no hay coincidencias, se utilizará la cadena predeterminada.

profile

Sintaxis: profile nombre [require]

Predeterminado: -

Contexto: acme_issuer

Esta directiva apareció en la versión 0.3.0.

Solicita el perfil de certificado nombre al servidor ACME.

El parámetro require hará que las renovaciones de certificados fallan si el servidor no admite el perfil especificado.

ssl_trusted_certificate

Sintaxis: ssl_trusted_certificate file

Predeterminado: paquete CA del sistema

Contexto: acme_issuer

Especifica un file con certificados CA de confianza en formato PEM utilizados para verificar el certificado del servidor ACME.

ssl_verify

Sintaxis: ssl_verify on | off

Predeterminado: on

Contexto: acme_issuer

Habilita o deshabilita la verificación del certificado del servidor ACME.

state_path

Sintaxis: state_path path | off

Predeterminado: acme_<nombre>

Contexto: acme_issuer

Define un directorio para almacenar los datos del módulo que pueden persistir entre reinicios. Esto puede mejorar el tiempo de carga al omitir algunas solicitudes al inicio, y evitar alcanzar los límites de tasa de solicitudes en el servidor ACME.

El directorio contiene contenido sensible, como la clave de cuenta, certificados emitidos y claves privadas.

El parámetro off (0.2.0) desactiva el almacenamiento de la información de la cuenta y los certificados emitidos en el disco.

Anteriormente a la versión 0.2.0, el directorio de estado no se creaba por defecto.

accept_terms_of_service

Sintaxis: accept_terms_of_service

Predeterminado: -

Contexto: acme_issuer

Acepta los términos de servicio bajo los cuales se utilizará el servidor ACME. Algunos servidores requieren aceptar los términos de servicio antes de registrar la cuenta. Los términos suelen estar disponibles en el sitio web del servidor ACME, y la URL se imprimirá en el registro de errores si es necesario.

acme_shared_zone

Sintaxis: acme_shared_zone zone=nombre:tamaño

Predeterminado: zone=ngx_acme_shared:256k

Contexto: http

Permite aumentar el tamaño del almacenamiento en memoria del módulo. La zona de memoria compartida se utilizará para almacenar los certificados emitidos, claves y datos de desafío para todos los emisores de certificados configurados.

El tamaño de zona predeterminado es suficiente para contener aproximadamente 50 claves ECDSA prime256v1 o 35 claves RSA 2048.

acme_certificate

Sintaxis: acme_certificate emisor [identificador ...] [key=alg[:size]]

Predeterminado: -

Contexto: server

Define un certificado con la lista de identificadores solicitados al emisor emisor.

La lista explícita de identificadores puede omitirse. En este caso, los identificadores se tomarán de la directiva server_name en el mismo bloque server. No todos los valores aceptados en server_name son identificadores de certificados válidos: no se admiten expresiones regulares ni comodines.

El parámetro key establece el tipo de clave privada generada. Algoritmos y tamaños de clave admitidos: ecdsa:256 (predeterminado), ecdsa:384, ecdsa:521, rsa:2048, rsa:3072, rsa:4096.

Variables Incorporadas

El módulo ngx_http_acme_module admite variables incorporadas, válidas en el bloque server con la directiva acme_certificate:

`$acme_certificate`

Certificado SSL que se puede pasar a la ssl_certificate.

`$acme_certificate_key`

Clave privada del certificado SSL que se puede pasar a la ssl_certificate_key.

GitHub

Puedes encontrar consejos de configuración adicionales y documentación para este módulo en el repositorio de GitHub para nginx-module-acme.