# ACME
Proporciona obtención automática de certificados utilizando el [protocolo ACME](https://datatracker.ietf.org/doc/html/rfc8555).
Cuando [compila desde el código fuente](https://es.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), el módulo no se compila por defecto;
debe habilitarse con la [opción de compilación](https://es.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-http_acme_module`.
En paquetes e imágenes de
[nuestros repositorios](https://es.angie.software//angie/docs/installation/index.md#install-packages),
el módulo está incluido en la compilación.
## Ejemplo de configuración
Los ejemplos de configuración e instrucciones de configuración se pueden encontrar en la sección [Configuración de ACME](https://es.angie.software//angie/docs/configuration/acme.md#acme-config).
## Directivas
### acme
| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile) | `acme` nombre; |
|--------------------------------------------------------------------------------------------|------------------|
| Predeterminado | — |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile) | server |
Para todos los dominios especificados en las directivas [server_name](https://es.angie.software//angie/docs/configuration/modules/http/index.md#server-name)
en todos los bloques [server](https://es.angie.software//angie/docs/configuration/modules/http/index.md#server)
que hacen referencia al [cliente ACME](#acme-client) con el nombre dado,
se obtendrá un único certificado;
si la configuración `server_name` cambia,
el certificado se renovará para reflejar los cambios.
Cada vez que Angie se inicia, se solicitan nuevos certificados para todos los dominios
que carecen de un certificado válido.
Las posibles razones incluyen la caducidad del certificado,
archivos faltantes o ilegibles,
y cambios en la configuración del certificado.
#### NOTE
Esta directiva solo controla qué nombres de dominio
se incluyen en las solicitudes de certificados;
no afecta a dónde puede usarse el certificado.
Cualquier bloque `server` puede hacer referencia al certificado
mediante la variable [$acme_cert_](#v-acme-cert-name),
independientemente de si el bloque contiene una directiva `acme`.
Eliminar `acme` de un bloque `server`
simplemente excluye los valores de [server_name](https://es.angie.software//angie/docs/configuration/modules/http/index.md#server-name) de ese bloque
de futuras solicitudes de certificados,
pero no impide que el bloque utilice el certificado.
#### NOTE
Actualmente, los dominios especificados con expresiones regulares
no son compatibles y serán omitidos.
Los dominios comodín solo son compatibles con `challenge=dns`
en `acme_client`.
Esta directiva puede especificarse varias veces
para cargar certificados de diferentes tipos, por ejemplo RSA y ECDSA:
```nginx
server {
listen 443 ssl;
server_name example.com www.example.com;
ssl_certificate $acme_cert_rsa;
ssl_certificate_key $acme_cert_key_rsa;
ssl_certificate $acme_cert_ecdsa;
ssl_certificate_key $acme_cert_key_ecdsa;
acme rsa;
acme ecdsa;
}
```
### acme_client
| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_client` nombre uri [`enabled=``on` | `off`] [`key_type=`tipo] [`key_bits=`número] [`email=`email] [`max_cert_size=`número] [`renew_before_expiry=`tiempo] [`renew_on_load`] [`retry_after_error=`off|tiempo] [`challenge=``dns` | `http` | `alpn`] [`account_key=`archivo]; |
|--------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Predeterminado | — |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Define un cliente ACME con un nombre único a nivel global.
Debe ser válido para un directorio,
es una cadena con variables,
y se utilizará sin distinción entre mayúsculas y minúsculas.
El segundo parámetro obligatorio es la uri del directorio ACME.
Por ejemplo, la URI del directorio ACME de Let's Encrypt está [especificada](https://letsencrypt.org/getting-started/)
como
[https://acme-v02.api.letsencrypt.org/directory](https://acme-v02.api.letsencrypt.org/directory).
#### NOTE
El módulo ACME añade una `location @acme` con nombre
al contexto [client](https://es.angie.software//angie/docs/configuration/modules/http/index.md#client),
que puede utilizarse para configurar solicitudes al directorio ACME;
por defecto, esta `location`
contiene una directiva [proxy_pass](https://es.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass) con la uri del directorio,
a la que se pueden añadir otros ajustes del módulo [Proxy](https://es.angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy).
Para que esta directiva funcione,
debe configurarse un [resolver](https://es.angie.software//angie/docs/configuration/modules/http/index.md#resolver) en el mismo contexto.
#### NOTE
Para fines de prueba,
las autoridades de certificación suelen proporcionar entornos de staging separados.
Por ejemplo, el [entorno de staging de Let's Encrypt](https://letsencrypt.org/docs/staging-environment/)
es
[https://acme-staging-v02.api.letsencrypt.org/directory](https://acme-staging-v02.api.letsencrypt.org/directory).
| `enabled` | Habilita o deshabilita la renovación de certificados para el cliente;
esto es útil, por ejemplo, para suspender temporalmente
sin eliminar el cliente de la configuración.
Predeterminado: `on`. |
|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `key_type` | El tipo de algoritmo de clave privada para el certificado.
Valores válidos: `rsa`, `ecdsa`.
Predeterminado: `ecdsa`. |
| `key_bits` | Número de bits en la clave del certificado.
Predeterminado: 256 para `ecdsa`, 2048 para `rsa`. |
| `email` | Dirección de correo electrónico opcional para retroalimentación;
se utiliza al crear una cuenta en el servidor CA. |
| `max_cert_size` | Especifica el tamaño máximo permitido de un nuevo archivo de certificado en bytes
para reservar espacio para el nuevo certificado en memoria compartida;
cuantos más dominios se soliciten para el certificado,
más espacio se requiere.
Este parámetro no limita el tamaño de las respuestas del servidor ACME;
utilice [acme_max_response_size](#acme-max-response-size) para eso.
Si el parámetro no está establecido, Angie calcula un tamaño aproximado
basándose en la lista de dominios configurada y lo utiliza para la
asignación de memoria compartida.
Si un certificado ya existe al inicio pero su tamaño excede el valor de
`max_cert_size`, el valor de `max_cert_size` se incrementa
dinámicamente para coincidir con el tamaño del archivo de certificado
existente.
Si el tamaño de un certificado obtenido durante la renovación
excede `max_cert_size`,
el proceso de renovación fallará con un error.
Predeterminado: calculado automáticamente. |
| `renew_before_expiry` | [Tiempo](https://es.angie.software//angie/docs/configuration/configfile.md#syntax) antes de la expiración del certificado
cuando debe comenzar la renovación.
Predeterminado: `30d`. |
| `renew_on_load` | Especifica que el certificado debe renovarse forzosamente
cada vez que se carga la configuración. |
| `retry_after_error` | [Tiempo](https://es.angie.software//angie/docs/configuration/configfile.md#syntax) de espera antes de reintentar
si la obtención del certificado falló.
Si se establece en `off`,
el cliente no reintentará obtener el certificado después de un error.
Predeterminado: `2h`. |
| `challenge` | Especifica el tipo de verificación para el cliente ACME.
Valores válidos: `dns`, `http`, `alpn`.
El valor `alpn` habilita la validación [TLS-ALPN-01](https://datatracker.ietf.org/doc/rfc8737/) y requiere
que Angie esté compilado con OpenSSL que soporte ALPN
(no compatible con compilaciones de BoringSSL o AWS-LC).
Predeterminado: `http`. |
| `account_key` | Especifica la ruta completa a un archivo que contiene una clave en formato PEM.
Esto es útil si desea utilizar una clave de cuenta existente
en lugar de la generación automática,
o si necesita utilizar una clave para múltiples clientes ACME.
Tipos de claves soportados:
- Claves RSA con longitudes que son múltiplos de 8, desde 2048 hasta 8192 bits.
- Claves ECDSA con longitudes de 256, 384 o 521 bits.
Al especificar el parámetro `account_key`,
asegúrese de que el archivo de clave realmente exista.
Si el archivo no existe,
Angie intentará crearlo en la ruta especificada.
Tenga en cuenta que las claves para los clientes ACME se crean en el orden
en que se mencionan los clientes correspondientes en la configuración
en las directivas [acme_client](#acme-client), [acme](#id1) o [acme_hook](#acme-hook).
Por lo tanto, si un cliente debe usar una clave
creada para otro,
ese otro cliente debe aparecer antes en la configuración.
Además, las claves solo se crean para clientes
que tienen el parámetro `enabled=on` establecido. |
### acme_max_response_size
| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_max_response_size` tamaño; |
|--------------------------------------------------------------------------------------------|------------------------------------|
| Predeterminado | `acme_max_response_size 32k;` |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Limita el tamaño máximo del cuerpo de una respuesta del servidor ACME. Si una respuesta excede
este límite, la solicitud falla con un error. Aumente el valor si ve
errores como `too big subrequest response while sending to client`.
### acme_client_path
| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_client_path` ruta; |
|--------------------------------------------------------------------------------------------|----------------------------|
| Predeterminado | — |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Anula la ruta al directorio para almacenar certificados y claves,
establecida durante la compilación usando el [parámetro de compilación](https://es.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--http-acme-client-path`.
### acme_dns_port
| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_dns_port` puerto | ip[:puerto] | [ip6][:puerto]; |
|--------------------------------------------------------------------------------------------|----------------------------------------------------------|
| Predeterminado | `acme_dns_port 53;` |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Especifica el puerto
que el módulo utiliza para manejar consultas DNS desde el servidor ACME a través de UDP.
El número de puerto debe estar en el rango de 1 a 65535.
También se admite especificar una dirección IP junto con un puerto opcional.
Se pueden utilizar tanto direcciones IPv4 en la forma `ip:puerto`
como direcciones IPv6 en la forma `[ip6]:puerto`:
```nginx
acme_dns_port 8053;
acme_dns_port 127.0.0.1;
acme_dns_port [::1];
```
Para usar un número de puerto 1024 o inferior,
Angie debe ejecutarse con [privilegios de superusuario](https://es.angie.software//angie/docs/configuration/modules/core.md#user).
### acme_http_port
| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_http_port` puerto | ip[:puerto] | [ip6][:puerto]; |
|--------------------------------------------------------------------------------------------|-----------------------------------------------------------|
| Predeterminado | `acme_http_port 80;` |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Especifica el puerto
que el módulo utiliza para manejar solicitudes de desafío ACME HTTP.
El número de puerto debe estar en el rango de 1 a 65535.
También se admite especificar una dirección IP junto con un puerto opcional.
Se pueden utilizar tanto direcciones IPv4 en la forma `ip:puerto`
como direcciones IPv6 en la forma `[ip6]:puerto`:
```nginx
acme_http_port 8080;
acme_http_port 127.0.0.1;
acme_http_port [::1];
```
Si no hay ningún servidor configurado para escuchar en la dirección y puerto especificados,
el módulo crea un listener dedicado para desafíos HTTP.
Para usar un número de puerto 1024 o inferior,
Angie debe ejecutarse con [privilegios de superusuario](https://es.angie.software//angie/docs/configuration/modules/core.md#user).
### acme_hook
| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_hook` nombre [uri]; |
|--------------------------------------------------------------------------------------------|-----------------------------|
| Predeterminado | — |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile) | location |
Habilita la validación de dominio basada en hooks
para el [cliente ACME](#acme-client) especificado por nombre.
Cuando la emisión o renovación de un certificado requiere la verificación de dominio,
Angie genera una solicitud interna
al `location` con nombre donde se encuentra esta directiva.
La forma en que se gestiona la solicitud depende enteramente
de las demás directivas configuradas en el mismo `location`,
como [fastcgi_pass](https://es.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-pass), [proxy_pass](https://es.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass),
o cualquier otro manejador de solicitudes.
| nombre | El nombre del [cliente ACME](#acme-client)
para el que este hook gestiona la verificación de dominio. |
|----------|-----------------------------------------------------------------------------------------------------------------------|
| uri | Una cadena con variables;
especifica la URI de solicitud para las llamadas al hook.
Predeterminado: `/`. |
Por ejemplo, la siguiente configuración pasa los valores de las [variables de hook](#http-acme-variables)
a una aplicación FastCGI a través de la URI de solicitud:
```nginx
acme_hook example uri=/acme_hook/$acme_hook_name?domain=$acme_hook_domain&key=$acme_hook_keyauth;
fastcgi_param REQUEST_URI $request_uri;
fastcgi_pass ...;
```
## Variables integradas
### `$acme_cert_`
Contenido del último archivo de certificado (si existe)
obtenido por el cliente con este nombre.
### `$acme_cert_key_`
Contenido del archivo de clave del certificado
utilizado por el cliente con este nombre.
#### NOTE
El archivo de certificado está disponible
solo si el cliente ACME ha obtenido al menos un certificado,
pero el archivo de clave está disponible inmediatamente después del inicio.
### `$acme_hook_challenge`
El tipo de desafío. Valores posibles: `dns`, `http`, `alpn`.
### `$acme_hook_client`
El nombre del cliente ACME que inicia la solicitud.
### `$acme_hook_domain`
El dominio que se está verificando.
Si es un dominio comodín, se pasará sin el prefijo `*.`.
### `$acme_hook_keyauth`
La cadena de autorización:
- Para el desafío DNS, se utiliza como el valor del registro TXT,
cuyo nombre se forma como
`_acme-challenge. + $acme_hook_domain + .`.
- Para el desafío HTTP, esta cadena debe utilizarse
como el contenido de la respuesta solicitada por el servidor ACME.
### `$acme_hook_name`
El nombre del hook. Para diferentes tipos de desafío, puede tener diferentes valores y significados:
| Valor | Significado para desafío DNS | Significado para desafío HTTP |
|--------------------------------|-----------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
| `add` (hook de adición) | El registro TXT correspondiente debe añadirse a la configuración DNS. | Se debe preparar una respuesta a la solicitud HTTP correspondiente. |
| `remove` (hook de eliminación) | El registro TXT puede eliminarse de la configuración DNS. | Esta solicitud HTTP ya no es relevante;
el archivo creado previamente con la cadena de autorización puede eliminarse. |
### `$acme_hook_token`
El token de verificación.
Para el desafío HTTP, se utiliza como el nombre del archivo solicitado:
`/.well-known/acme-challenge/` + `$acme_hook_token`.