Pular para conteúdo

acme: Módulo de gerenciamento automático de certificados (ACMEv2) para NGINX

Instalação

Você pode instalar este módulo em qualquer distribuição baseada em RHEL, incluindo, mas não se limitando a:

  • RedHat Enterprise Linux 7, 8, 9 e 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 e Amazon Linux 2023
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

Ative o módulo adicionando o seguinte no topo de /etc/nginx/nginx.conf:

load_module modules/ngx_http_acme_module.so;

Este documento descreve o nginx-module-acme v0.3.1 lançado em 08 de dezembro de 2025.

Status do Projeto: Ativo – O projeto alcançou um estado estável e utilizável e está sendo desenvolvido ativamente. Suporte da Comunidade Fórum da Comunidade Licença Covenant do Contribuidor

nginx-acme

nginx-acme é um módulo NGINX com a implementação do protocolo de gerenciamento automático de certificados (ACMEv2).

O módulo implementa as seguintes especificações:

  • RFC8555 (Ambiente de Gerenciamento Automático de Certificados) com limitações:
    • Apenas o tipo de desafio HTTP-01 é suportado
  • RFC8737 (Extensão de Negociação de Protocolo de Camada de Aplicação TLS ACME)
  • RFC8738 (Extensão de Validação de Identificador IP ACME)
  • draft-ietf-acme-profiles (Extensão de Perfis ACME, versão 00)

Começando

checkout, configure e construa o NGINX em ../nginx

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

O resultado estará localizado em `target/release/libnginx_acme.so`.

Outra maneira é usar o script de configuração fornecido:

```sh
## no diretório de origem do NGINX
auto/configure \
    --with-compat \
    --with-http_ssl_module \
    --add-[dynamic-]module=/path/to/nginx-acme

O resultado estará localizado em objs/ngx_http_acme_module.so.

Atualmente, esse método produz uma biblioteca ligeiramente maior, pois não instruímos o vinculador a realizar LTO e remover código não utilizado.

Testando

O repositório contém um conjunto de testes de integração baseado nos nginx-tests. O seguinte comando irá construir o módulo e executar os testes:

## Caminho para o checkout da fonte do nginx, padrão para ../nginx se não especificado.
export NGINX_SOURCE_DIR=$(realpath ../nginx)
## Caminho para o checkout do nginx-tests; padrão para ../nginx/tests se não especificado.
export NGINX_TESTS_DIR=$(realpath ../nginx-tests)

make test

A maioria dos testes requer o binário do servidor de teste pebble no caminho ou em um local especificado pela variável de ambiente TEST_NGINX_PEBBLE_BINARY.

Como Usar

Adicione o módulo à configuração do NGINX e configure conforme descrito abaixo. Observe que este módulo requer uma configuração de resolver no bloco http.

Exemplo de Configuração

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      # não suportado por alguns servidores ACME
                 2001:db8::1    # não suportado por alguns servidores ACME
                 ;

    acme_certificate example;

    ssl_certificate       $acme_certificate;
    ssl_certificate_key   $acme_certificate_key;

    # não parsear o certificado em cada requisição
    ssl_certificate_cache max=2;
}

server {
    # ouvinte na porta 80 é necessário para processar desafios ACME HTTP-01
    listen 80;

    location / {
        return 404;
    }
}

Diretivas

[!IMPORTANTE] A referência abaixo reflete a versão atual em desenvolvimento. Veja a documentação de ngx_http_acme_module no nginx.org para a versão mais recente lançada.

acme_issuer

Sintaxe: acme_issuer nome { ... }

Padrão: -

Contexto: http

Define um objeto emissor de certificado ACME.

uri

Sintaxe: uri uri

Padrão: -

Contexto: acme_issuer

A URL do diretório do servidor ACME. Esta diretiva é obrigatória.

account_key

Sintaxe: account_key alg[:tamanho] | arquivo

Padrão: -

Contexto: acme_issuer

A chave privada da conta usada para autenticação de requisições.

Valores aceitos:

  • ecdsa:256/384/521 para algoritmos de Assinatura Web JSON ES256, ES384 ou ES512
  • rsa:2048/3072/4096 para RS256.
  • Caminho do arquivo para uma chave existente, usando um dos algoritmos acima.

As chaves de conta geradas são preservadas entre recargas, mas serão perdidas na reinicialização, a menos que state_path esteja configurado.

challenge

Sintaxe: challenge tipo

Padrão: http-01

Contexto: acme_issuer

Esta diretiva apareceu na versão 0.2.0.

Especifica o tipo de desafio ACME a ser usado para o emissor.

Valores aceitos:

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

Desafios ACME são versionados. Se um nome não versionado for especificado, o módulo seleciona automaticamente a versão mais recente implementada.

contact

Sintaxe: contact URL

Padrão: -

Contexto: acme_issuer

Define um array de URLs que o servidor ACME pode usar para contatar o cliente sobre problemas de conta. O esquema mailto: será usado, a menos que especificado explicitamente.

external_account_key

Sintaxe: external_account_key kid arquivo

Padrão: -

Contexto: acme_issuer

Esta diretiva apareceu na versão 0.2.0.

Especifica um identificador de chave kid e um arquivo com a chave MAC para autorização de conta externa.

O valor data:key pode ser especificado em vez do arquivo, que carrega uma chave diretamente da configuração sem usar arquivos intermediários.

Em ambos os casos, espera-se que a chave esteja codificada em base64url.

preferred_chain

Sintaxe: preferred_chain nome

Padrão: -

Contexto: acme_issuer

Esta diretiva apareceu na versão 0.3.0.

Especifica a cadeia de certificados preferida.

Se o servidor ACME oferecer várias cadeias de certificados, prefira a cadeia com o certificado mais alto emitido do Nome Comum do Sujeito nome. Se não houver correspondências, a cadeia padrão será usada.

profile

Sintaxe: profile nome [require]

Padrão: -

Contexto: acme_issuer

Esta diretiva apareceu na versão 0.3.0.

Solicita o perfil de certificado nome do servidor ACME.

O parâmetro require fará com que renovações de certificados falhem se o servidor não suportar o perfil especificado.

ssl_trusted_certificate

Sintaxe: ssl_trusted_certificate arquivo

Padrão: pacote CA do sistema

Contexto: acme_issuer

Especifica um arquivo com certificados CA confiáveis no formato PEM usados para verificar o certificado do servidor ACME.

ssl_verify

Sintaxe: ssl_verify on | off

Padrão: on

Contexto: acme_issuer

Habilita ou desabilita a verificação do certificado do servidor ACME.

state_path

Sintaxe: state_path caminho | off

Padrão: acme_<nome>

Contexto: acme_issuer

Define um diretório para armazenar os dados do módulo que podem ser persistidos entre reinicializações. Isso pode melhorar o tempo de carregamento, pulando algumas requisições na inicialização, e evitar atingir limites de taxa de requisições no servidor ACME.

O diretório contém conteúdo sensível, como a chave da conta, certificados emitidos e chaves privadas.

O parâmetro off (0.2.0) desabilita o armazenamento das informações da conta e dos certificados emitidos no disco.

Antes da versão 0.2.0, o diretório de estado não era criado por padrão.

accept_terms_of_service

Sintaxe: accept_terms_of_service

Padrão: -

Contexto: acme_issuer

Concorda com os termos de serviço sob os quais o servidor ACME será usado. Alguns servidores exigem a aceitação dos termos de serviço antes do registro da conta. Os termos geralmente estão disponíveis no site do servidor ACME, e a URL será impressa no log de erros, se necessário.

acme_shared_zone

Sintaxe: acme_shared_zone zone=nome:tamanho

Padrão: zone=ngx_acme_shared:256k

Contexto: http

Permite aumentar o tamanho do armazenamento em memória do módulo. A zona de memória compartilhada será usada para armazenar os certificados emitidos, chaves e dados de desafio para todos os emissores de certificados configurados.

O tamanho da zona padrão é suficiente para conter aproximadamente 50 chaves ECDSA prime256v1 ou 35 chaves RSA 2048.

acme_certificate

Sintaxe: acme_certificate emissor [identificador ...] [key=alg[:tamanho]]

Padrão: -

Contexto: server

Define um certificado com a lista de identificadores solicitados do emissor emissor.

A lista explícita de identificadores pode ser omitida. Nesse caso, os identificadores serão retirados da diretiva server_name no mesmo bloco server. Nem todos os valores aceitos em server_name são identificadores de certificado válidos: expressões regulares e curingas não são suportados.

O parâmetro key define o tipo de uma chave privada gerada. Algoritmos e tamanhos de chave suportados: ecdsa:256 (padrão), ecdsa:384, ecdsa:521, rsa:2048, rsa:3072, rsa:4096.

Variáveis Embutidas

O módulo ngx_http_acme_module suporta variáveis embutidas, válidas no bloco server com a diretiva acme_certificate:

$acme_certificate

Certificado SSL que pode ser passado para o ssl_certificate.

$acme_certificate_key

Chave privada do certificado SSL que pode ser passada para o ssl_certificate_key.

GitHub

Você pode encontrar dicas adicionais de configuração e documentação para este módulo no repositório do GitHub para nginx-module-acme.