<!-- review: finished -->

<a id="mail-ssl"></a>

# SSL

El módulo habilita el soporte de cifrado SSL/TLS para protocolos de proxy de correo (POP3, IMAP, SMTP), permitiendo una comunicación segura entre clientes y el servidor. Proporciona cifrado SSL/TLS para conexiones entrantes, soporta actualizaciones STARTTLS, gestiona certificados y claves, y controla configuraciones SSL como cifrados y versiones de protocolo.

Cuando se [compila desde el código fuente](https://es.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), este 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‑mail_ssl_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.

#### NOTE
Este módulo requiere la biblioteca OpenSSL.

<a id="configuration-example-54"></a>

## Ejemplo de configuración

Para reducir la carga del procesador se recomienda

* establecer el número de [procesos de trabajo](https://es.angie.software//angie/docs/configuration/modules/core.md#worker-processes) igual al número de procesadores,
* habilitar la caché de sesión [compartida](#m-ssl-session-cache),
* deshabilitar la caché de sesión [incorporada](#m-ssl-session-cache),
* y posiblemente aumentar el [tiempo de vida](#m-ssl-session-timeout) de la sesión (por defecto, 5 minutos):

```nginx
worker_processes auto;

mail {

    ...

    server {
        listen              993 ssl;

        ssl_protocols       TLSv1.2 TLSv1.3;
        ssl_ciphers         AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5;
        ssl_certificate     /usr/local/angie/conf/cert.pem;
        ssl_certificate_key /usr/local/angie/conf/cert.key;
        ssl_session_cache   shared:SSL:10m;
        ssl_session_timeout 10m;

    #    ...
    }
```

<a id="directives-63"></a>

## Directivas

<a id="index-0"></a>

<a id="m-ssl-certificate"></a>

### ssl_certificate

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_certificate` archivo;   |
|--------------------------------------------------------------------------------------------|------------------------------|
| Predeterminado                                                                             | —                            |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | mail, server                 |

Especifica un archivo con el certificado en formato PEM para el servidor dado. Si se deben especificar certificados intermedios además de un certificado primario, deben especificarse en el mismo archivo en el siguiente orden: primero el certificado primario, luego los certificados intermedios. Una clave secreta en formato PEM puede colocarse en el mismo archivo.

Esta directiva puede especificarse varias veces para cargar certificados de diferentes tipos, por ejemplo, RSA y ECDSA:

```nginx
server {
    listen              993 ssl;

    ssl_certificate     example.com.rsa.crt;
    ssl_certificate_key example.com.rsa.key;

    ssl_certificate     example.com.ecdsa.crt;
    ssl_certificate_key example.com.ecdsa.key;

#    ...
}
```

Solo OpenSSL 1.0.2 o superior admite cadenas de certificados separadas para diferentes certificados. Con versiones anteriores, solo se puede usar una cadena de certificados.

El valor `data:`certificate`` puede especificarse en lugar de `archivo`, lo que carga un certificado sin usar archivos intermedios.

Tenga en cuenta que el uso inadecuado de esta sintaxis puede tener implicaciones de seguridad, como escribir datos de clave secreta en el [registro de errores](https://es.angie.software//angie/docs/configuration/modules/core.md#error-log).

<a id="index-1"></a>

<a id="m-ssl-certificate-compression"></a>

### ssl_certificate_compression

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_certificate_compression` `on` | `off`;   |
|--------------------------------------------------------------------------------------------|-----------------------------------------------|
| Predeterminado                                                                             | `ssl_certificate_compression off;`            |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | mail, server                                  |

Habilita la [compresión](https://datatracker.ietf.org/doc/html/rfc8879) TLS 1.3 de certificados de servidor.

#### NOTE
La directiva es compatible cuando se usa OpenSSL 3.2 o superior; la lista de algoritmos de compresión soportados es proporcionada por la biblioteca.

#### NOTE
La directiva es compatible cuando se usa [BoringSSL](https://boringssl.googlesource.com/boringssl/); la lista de algoritmos de compresión soportados incluye `zlib`.

<a id="index-2"></a>

<a id="m-ssl-certificate-key"></a>

### ssl_certificate_key

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_certificate_key` archivo;   |
|--------------------------------------------------------------------------------------------|----------------------------------|
| Predeterminado                                                                             | —                                |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | mail, server                     |

Especifica un archivo con la clave secreta en formato PEM para el servidor dado.

El valor `engine:`name`:id` puede especificarse en lugar de `archivo`, lo que carga una clave secreta con un id específico desde el motor OpenSSL name.

El valor `store:scheme:id` puede especificarse en lugar de `archivo`, que se utiliza para cargar una clave secreta con un id específico y un URI scheme registrado del proveedor OpenSSL, como [pkcs11](https://datatracker.ietf.org/doc/html/rfc7512).

El valor `data:`key`` puede especificarse en lugar de `archivo`, lo que carga una clave secreta sin usar archivos intermedios. Tenga en cuenta que el uso inadecuado de esta sintaxis puede tener implicaciones de seguridad, como escribir datos de clave secreta en el [registro de errores](https://es.angie.software//angie/docs/configuration/modules/core.md#error-log).

<a id="index-3"></a>

<a id="m-ssl-ciphers"></a>

### ssl_ciphers

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ciphers` cifrados;         |
|--------------------------------------------------------------------------------------------|---------------------------------|
| Predeterminado                                                                             | `ssl_ciphers HIGH:!aNULL:!MD5;` |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | mail, server                    |

Especifica los cifrados habilitados. Los cifrados se especifican en el formato entendido por la biblioteca OpenSSL, por ejemplo:

```nginx
ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
```

La lista de cifrados depende de la versión de OpenSSL instalada.
La lista completa se puede ver usando el comando `openssl ciphers`.

#### WARNING
La directiva `ssl_ciphers` *no* configura cifrados para TLS
1.3 cuando se usa OpenSSL. Para ajustar los cifrados TLS 1.3 con OpenSSL, use la
directiva [ssl_conf_command](#m-ssl-conf-command), que fue añadida para admitir configuración
SSL avanzada.

- En LibreSSL, los cifrados TLS 1.3 *pueden* configurarse usando
  `ssl_ciphers`.
- En BoringSSL, los cifrados TLS 1.3 no pueden configurarse en absoluto.

<a id="index-4"></a>

<a id="m-ssl-client-certificate"></a>

### ssl_client_certificate

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_client_certificate` archivo;   |
|--------------------------------------------------------------------------------------------|-------------------------------------|
| Predeterminado                                                                             | —                                   |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | mail, server                        |

Especifica un archivo con certificados CA de confianza en formato PEM utilizados para [verificar](#m-ssl-verify-client) certificados de cliente.

La lista de certificados se enviará a los clientes. Si esto no es deseable, se puede usar la directiva [ssl_trusted_certificate](#m-ssl-trusted-certificate).

<a id="index-5"></a>

<a id="m-ssl-conf-command"></a>

### ssl_conf_command

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_conf_command` nombre valor;   |
|--------------------------------------------------------------------------------------------|------------------------------------|
| Predeterminado                                                                             | —                                  |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | mail, server                       |

Establece [comandos](https://docs.openssl.org/master/man3/SSL_CONF_cmd/) de configuración OpenSSL arbitrarios.

#### NOTE
La directiva es compatible cuando se usa OpenSSL 1.0.2 o superior.
Para configurar cifrados TLS 1.3 con OpenSSL, use el comando `ciphersuites`.

Se pueden especificar varias directivas ssl_conf_command en el mismo nivel:

```nginx
ssl_conf_command Options PrioritizeChaCha;
ssl_conf_command Ciphersuites TLS_CHACHA20_POLY1305_SHA256;
```

Estas directivas se heredan del nivel de configuración anterior si y solo si no hay directivas ssl_conf_command definidas en el nivel actual.

#### WARNING
Tenga en cuenta que configurar OpenSSL directamente podría resultar en un comportamiento inesperado.

<a id="index-6"></a>

<a id="m-ssl-crl"></a>

### ssl_crl

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_crl` archivo;   |
|--------------------------------------------------------------------------------------------|----------------------|
| Predeterminado                                                                             | —                    |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | mail, server         |

Especifica un archivo con certificados revocados (CRL) en formato PEM utilizado para [verificar](#m-ssl-verify-client) certificados de cliente.

<a id="index-7"></a>

<a id="m-ssl-dhparam"></a>

### ssl_dhparam

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_dhparam` archivo;   |
|--------------------------------------------------------------------------------------------|--------------------------|
| Predeterminado                                                                             | —                        |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | mail, server             |

Especifica un archivo con parámetros DH para cifrados DHE.

#### WARNING
Por defecto no se establecen parámetros, y por lo tanto no se utilizarán cifrados DHE.

<a id="index-8"></a>

<a id="m-ssl-ecdh-curve"></a>

### ssl_ecdh_curve

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ecdh_curve` curva;   |
|--------------------------------------------------------------------------------------------|---------------------------|
| Predeterminado                                                                             | `ssl_ecdh_curve auto;`    |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | mail, server              |

Especifica una curva para cifrados ECDHE.

#### NOTE
Cuando se usa OpenSSL 1.0.2 o superior, es posible especificar múltiples curvas, por ejemplo:

```nginx
ssl_ecdh_curve prime256v1:secp384r1;
```

El valor especial `auto` indica a Angie que use una lista incorporada en la biblioteca OpenSSL cuando se usa OpenSSL 1.0.2 o superior, o prime256v1 con versiones anteriores.

#### NOTE
Cuando se usa OpenSSL 1.0.2 o superior, esta directiva establece la lista de curvas soportadas por el servidor. Por lo tanto, para que los certificados ECDSA funcionen, es importante incluir las curvas utilizadas en los certificados.

<a id="index-9"></a>

<a id="m-ssl-password-file"></a>

### ssl_password_file

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_password_file` archivo;   |
|--------------------------------------------------------------------------------------------|--------------------------------|
| Predeterminado                                                                             | —                              |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | mail, server                   |

Especifica un archivo con frases de contraseña para [claves secretas](#m-ssl-certificate-key) donde cada frase de contraseña se especifica en una línea separada. Las frases de contraseña se prueban sucesivamente al cargar la clave.

Ejemplo:

```nginx
mail {
    ssl_password_file /etc/keys/global.pass;
    ...

    server {
        server_name mail1.example.com;
        ssl_certificate_key /etc/keys/first.key;
    }

    server {
        server_name mail2.example.com;

        # también se puede usar un named pipe en lugar de un archivo
        ssl_password_file /etc/keys/fifo;
        ssl_certificate_key /etc/keys/second.key;
    }
}
```

<a id="index-10"></a>

<a id="m-ssl-prefer-server-ciphers"></a>

### ssl_prefer_server_ciphers

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_prefer_server_ciphers` `on` | `off`;   |
|--------------------------------------------------------------------------------------------|---------------------------------------------|
| Predeterminado                                                                             | `ssl_prefer_server_ciphers off;`            |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | mail, server                                |

Especifica que los cifrados del servidor deben ser preferidos sobre los cifrados del cliente cuando se utilizan los protocolos SSLv3 y TLS.

<a id="index-11"></a>

<a id="m-ssl-protocols"></a>

### ssl_protocols

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_protocols` [`SSLv2`] [`SSLv3`] [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`];   |
|--------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
| Predeterminado                                                                             | `ssl_protocols TLSv1.2 TLSv1.3;`                                                     |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | mail, server                                                                         |

#### Versionchanged
Distinto en la versión 1.2.0: Parámetro `TLSv1.3` añadido al conjunto predeterminado.

Habilita los protocolos especificados.

#### NOTE
Los parámetros TLSv1.1 y TLSv1.2 funcionan solo cuando se utiliza OpenSSL 1.0.1 o superior.

El parámetro TLSv1.3 funciona solo cuando se utiliza OpenSSL 1.1.1 o superior.

<a id="index-12"></a>

<a id="m-ssl-session-cache"></a>

### ssl_session_cache

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_cache` `off` | `none` | [builtin[:size]] [shared:name:size];   |
|--------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| Predeterminado                                                                             | `ssl_session_cache none;`                                                   |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | mail, server                                                                |

Establece los tipos y tamaños de cachés que almacenan los parámetros de sesión. Una caché puede ser de cualquiera de los siguientes tipos:

| `off`     | el uso de una caché de sesión está estrictamente prohibido: Angie explícitamente le dice a un cliente que las sesiones no pueden reutilizarse.                                                                                                                                                                                                                                                                                                                                                                                           |
|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `none`    | el uso de una caché de sesión está suavemente desaconsejado: Angie indica al cliente que las sesiones pueden reutilizarse, pero no almacena realmente los parámetros de sesión en la caché.                                                                                                                                                                                                                                                                                                                                              |
| `builtin` | una caché integrada en OpenSSL; utilizada por un único proceso de trabajo. El tamaño de la caché se especifica en sesiones. Si no se proporciona el tamaño, es igual a 20480 sesiones. El uso de la caché integrada puede provocar fragmentación de la memoria.                                                                                                                                                                                                                                                                          |
| `shared`  | una caché compartida entre todos los procesos de trabajo. El tamaño de la caché se especifica en bytes; un megabyte puede almacenar aproximadamente 4000 sesiones. Cada caché compartida debe tener un nombre arbitrario. Una caché con el mismo nombre puede utilizarse en varios servidores. También se utiliza para generar automáticamente, almacenar y rotar periódicamente las claves de tickets de sesión TLS, a menos que se configure explícitamente mediante la directiva [ssl_session_ticket_key](#m-ssl-session-ticket-key). |

Ambos tipos de caché pueden usarse simultáneamente, por ejemplo:

```nginx
ssl_session_cache builtin:1000 shared:SSL:10m;
```

pero usar solo la caché compartida sin la caché integrada debería ser más eficiente.

<a id="index-13"></a>

<a id="m-ssl-session-ticket-key"></a>

### ssl_session_ticket_key

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_ticket_key` file;   |
|--------------------------------------------------------------------------------------------|----------------------------------|
| Predeterminado                                                                             | —                                |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | mail, server                     |

Establece un archivo con la clave secreta utilizada para cifrar y descifrar los tickets de sesión TLS. La directiva es necesaria si la misma clave debe ser compartida entre múltiples servidores. Por defecto, se utiliza una clave generada aleatoriamente.

Si se especifican varias claves, solo la primera clave se utiliza para cifrar los tickets de sesión TLS. Esto permite configurar la rotación de claves, por ejemplo:

```nginx
ssl_session_ticket_key current.key;
ssl_session_ticket_key previous.key;
```

El archivo debe contener 80 o 48 bytes de datos aleatorios y puede ser creado utilizando el siguiente comando:

```console
openssl rand 80 > ticket.key
```

Dependiendo del tamaño del archivo, se utiliza AES256 (para claves de 80 bytes) o AES128 (para claves de 48 bytes) para el cifrado.

<a id="index-14"></a>

<a id="m-ssl-session-tickets"></a>

### ssl_session_tickets

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_tickets` `on` | `off`;   |
|--------------------------------------------------------------------------------------------|---------------------------------------|
| Predeterminado                                                                             | `ssl_session_tickets on;`             |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | mail, server                          |

Habilita o deshabilita la reanudación de sesión a través de [tickets de sesión TLS](https://datatracker.ietf.org/doc/html/rfc5077).

<a id="index-15"></a>

<a id="m-ssl-session-timeout"></a>

### ssl_session_timeout

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_timeout` time;   |
|--------------------------------------------------------------------------------------------|-------------------------------|
| Predeterminado                                                                             | `ssl_session_timeout 5m;`     |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | mail, server                  |

Especifica un tiempo durante el cual un cliente puede reutilizar los parámetros de sesión.

<a id="index-16"></a>

<a id="m-ssl-trusted-certificate"></a>

### ssl_trusted_certificate

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_trusted_certificate` file;   |
|--------------------------------------------------------------------------------------------|-----------------------------------|
| Predeterminado                                                                             | —                                 |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | mail, server                      |

Especifica un archivo con certificados CA de confianza en formato PEM usados para [verificar](#m-ssl-verify-client) certificados de cliente.

A diferencia del conjunto de certificados establecido por [ssl_client_certificate](#m-ssl-client-certificate), la lista de estos certificados no se enviará a los clientes.

<a id="index-17"></a>

<a id="m-ssl-verify-client"></a>

### ssl_verify_client

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_verify_client` `on` | `off` | `optional` | `optional_no_ca`;   |
|--------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
| Predeterminado                                                                             | `ssl_verify_client off;`                                            |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | mail, server                                                        |

Habilita la verificación de certificados de cliente. El resultado de la verificación se pasa en la cabecera `Auth-SSL-Verify` de la solicitud de [autenticación](https://es.angie.software//angie/docs/configuration/modules/mail/mail_auth_http.md#m-auth-http). Si ocurre un error durante la verificación del certificado del cliente o un cliente no proporciona el certificado requerido, la conexión se cierra.

| `optional`       | solicita el certificado del cliente y lo verifica si el certificado está presente                                                                                                                                                                                                                                                                                                                                                                                       |
|------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `optional_no_ca` | solicita el certificado del cliente pero no requiere que esté firmado por un certificado CA de confianza. Esto está destinado a ser utilizado en casos en los que un servicio externo a Angie realiza la verificación real del certificado. El contenido del certificado es accesible a través de solicitudes [enviadas](https://es.angie.software//angie/docs/configuration/modules/mail/mail_auth_http.md#m-auth-http-pass-client-cert) al servidor de autenticación. |

<a id="index-18"></a>

<a id="m-ssl-verify-depth"></a>

### ssl_verify_depth

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_verify_depth` number;   |
|--------------------------------------------------------------------------------------------|------------------------------|
| Predeterminado                                                                             | `ssl_verify_depth 1;`        |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | mail, server                 |

Establece la profundidad de verificación en la cadena de certificados del cliente.

<a id="index-19"></a>

<a id="m-starttls"></a>

### starttls

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `starttls` `on` | `off` | `only`;   |
|--------------------------------------------------------------------------------------------|-------------------------------------|
| Predeterminado                                                                             | `starttls off;`                     |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | mail, server                        |

| `on`   | permite el uso del comando STLS para POP3 y el comando STARTTLS para IMAP y SMTP;   |
|--------|-------------------------------------------------------------------------------------|
| `off`  | deniega el uso de los comandos STLS y STARTTLS;                                     |
| `only` | requiere transición TLS preliminar.                                                 |