<!-- review: finished -->

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

# SSL

O módulo habilita o suporte à criptografia SSL/TLS para protocolos de proxy de email (POP3,
IMAP, SMTP), permitindo comunicação segura entre clientes e o servidor. Ele
fornece criptografia SSL/TLS para conexões de entrada, suporta atualizações
STARTTLS, gerencia certificados e chaves, e controla configurações SSL como
cifras e versões de protocolo.

Ao [compilar a partir do código-fonte](https://pt.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild),
este módulo não é compilado por padrão;
ele deve ser habilitado com a
`‑‑with‑mail_ssl_module`
[opção de compilação](https://pt.angie.software//angie/docs/installation/sourcebuild.md#configure).

Em pacotes e imagens dos [nossos repositórios](https://pt.angie.software//angie/docs/installation/index.md#install-packages),
o módulo está incluído na compilação.

#### NOTE
Este módulo requer a biblioteca OpenSSL.

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

## Exemplo de Configuração

Para reduzir a carga do processador é recomendado

* definir o número de [processos worker](https://pt.angie.software//angie/docs/configuration/modules/core.md#worker-processes) igual ao número de processadores,
* habilitar o cache de sessão [compartilhado](#m-ssl-session-cache),
* desabilitar o cache de sessão [integrado](#m-ssl-session-cache),
* e possivelmente aumentar o [tempo de vida](#m-ssl-session-timeout) da sessão (por padrão, 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>

## Diretivas

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

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

### ssl_certificate

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_certificate` file;   |
|-------------------------------------------------------------------------------------------|---------------------------|
| Padrão                                                                                    | —                         |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server              |

Especifica um arquivo com o certificado no formato PEM para o servidor especificado. Se certificados intermediários devem ser especificados além de um certificado primário, eles devem ser especificados no mesmo arquivo na seguinte ordem: o certificado primário vem primeiro, depois os certificados intermediários. Uma chave secreta no formato PEM pode ser colocada no mesmo arquivo.

Esta diretiva pode ser especificada múltiplas vezes para carregar certificados de diferentes tipos, por exemplo, RSA e 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;

#    ...
}
```

Apenas OpenSSL 1.0.2 ou superior suporta cadeias de certificados separadas para diferentes certificados. Com versões mais antigas, apenas uma cadeia de certificados pode ser usada.

O valor `data:`certificate`` pode ser especificado em vez do `file`, que carrega um certificado sem usar arquivos intermediários.

Note que o uso inadequado desta sintaxe pode ter implicações de segurança, como escrever dados de chave secreta no [log de erro](https://pt.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

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_certificate_compression` `on` | `off`;   |
|-------------------------------------------------------------------------------------------|-----------------------------------------------|
| Padrão                                                                                    | `ssl_certificate_compression off;`            |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                                  |

Habilita [compressão](https://datatracker.ietf.org/doc/html/rfc8879) TLS 1.3 de certificados de servidor.

#### NOTE
A diretiva é suportada ao usar OpenSSL 3.2 ou superior; a lista de algoritmos de compressão suportados é fornecida pela biblioteca.

#### NOTE
A diretiva é suportada ao usar [BoringSSL](https://boringssl.googlesource.com/boringssl/); a lista de algoritmos de compressão suportados inclui `zlib`.

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

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

### ssl_certificate_key

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_certificate_key` file;   |
|-------------------------------------------------------------------------------------------|-------------------------------|
| Padrão                                                                                    | —                             |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                  |

Especifica um arquivo com a chave secreta no formato PEM para o servidor especificado.

O valor `engine:`name`:id` pode ser especificado em vez do `file`, que carrega uma chave secreta com um id especificado do engine OpenSSL name.

O valor `store:scheme:id` pode ser especificado em vez do `file`, que é usado para carregar uma chave secreta com um id especificado e URI scheme registrado no provedor OpenSSL, como [pkcs11](https://datatracker.ietf.org/doc/html/rfc7512).

O valor `data:`key`` pode ser especificado em vez do `file`, que carrega uma chave secreta sem usar arquivos intermediários. Note que o uso inadequado desta sintaxe pode ter implicações de segurança, como escrever dados de chave secreta no [log de erro](https://pt.angie.software//angie/docs/configuration/modules/core.md#error-log).

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

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

### ssl_ciphers

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ciphers` ciphers;          |
|-------------------------------------------------------------------------------------------|---------------------------------|
| Padrão                                                                                    | `ssl_ciphers HIGH:!aNULL:!MD5;` |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                    |

Especifica as cifras habilitadas. As cifras são especificadas no formato compreendido pela biblioteca OpenSSL, por exemplo:

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

A lista de cifras depende da versão do OpenSSL instalada.
A lista completa pode ser visualizada usando o comando `openssl ciphers`.

#### WARNING
A diretiva `ssl_ciphers` *não* configura cifras para TLS
1.3 ao usar OpenSSL. Para ajustar cifras TLS 1.3 com OpenSSL, use a
diretiva [ssl_conf_command](#m-ssl-conf-command), que foi adicionada para suportar
configuração SSL avançada.

- No LibreSSL, cifras TLS 1.3 *podem* ser configuradas usando
  `ssl_ciphers`.
- No BoringSSL, cifras TLS 1.3 não podem ser configuradas de forma alguma.

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

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

### ssl_client_certificate

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_client_certificate` file;   |
|-------------------------------------------------------------------------------------------|----------------------------------|
| Padrão                                                                                    | —                                |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                     |

Especifica um arquivo com certificados CA confiáveis no formato PEM usados para [verificar](#m-ssl-verify-client) certificados de cliente.

A lista de certificados será enviada aos clientes. Se isso não for desejado, a diretiva [ssl_trusted_certificate](#m-ssl-trusted-certificate) pode ser usada.

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

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

### ssl_conf_command

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_conf_command` name value;   |
|-------------------------------------------------------------------------------------------|----------------------------------|
| Padrão                                                                                    | —                                |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                     |

Define [comandos](https://docs.openssl.org/master/man3/SSL_CONF_cmd/) de configuração OpenSSL arbitrários.

#### NOTE
A diretiva é suportada ao usar OpenSSL 1.0.2 ou superior.
Para configurar cifras TLS 1.3 com OpenSSL, use o comando `ciphersuites`.

Várias diretivas ssl_conf_command podem ser especificadas no mesmo nível:

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

Essas diretivas são herdadas do nível de configuração anterior se e somente se não há diretivas ssl_conf_command definidas no nível atual.

#### WARNING
Note que configurar o OpenSSL diretamente pode resultar em comportamento inesperado.

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

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

### ssl_crl

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_crl` file;   |
|-------------------------------------------------------------------------------------------|-------------------|
| Padrão                                                                                    | —                 |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server      |

Especifica um arquivo com certificados revogados (CRL) no formato PEM usados para [verificar](#m-ssl-verify-client) certificados de cliente.

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

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

### ssl_dhparam

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_dhparam` file;   |
|-------------------------------------------------------------------------------------------|-----------------------|
| Padrão                                                                                    | —                     |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server          |

Especifica um arquivo com parâmetros DH para cifras DHE.

#### WARNING
Por padrão nenhum parâmetro é definido, e portanto cifras DHE não serão usadas.

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

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

### ssl_ecdh_curve

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ecdh_curve` curve;   |
|-------------------------------------------------------------------------------------------|---------------------------|
| Padrão                                                                                    | `ssl_ecdh_curve auto;`    |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server              |

Especifica uma curva para cifras ECDHE.

#### NOTE
Ao usar OpenSSL 1.0.2 ou superior, é possível especificar múltiplas curvas, por exemplo:

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

O valor especial `auto` instrui o Angie a usar uma lista integrada na biblioteca OpenSSL ao usar OpenSSL 1.0.2 ou superior, ou prime256v1 com versões mais antigas.

#### NOTE
Ao usar OpenSSL 1.0.2 ou superior, esta diretiva define a lista de curvas suportadas pelo servidor. Assim, para que certificados ECDSA funcionem, é importante incluir as curvas usadas nos certificados.

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

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

### ssl_password_file

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_password_file` file;   |
|-------------------------------------------------------------------------------------------|-----------------------------|
| Padrão                                                                                    | —                           |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                |

Especifica um arquivo com senhas para [chaves secretas](#m-ssl-certificate-key) onde cada senha é especificada em uma linha separada. As senhas são tentadas em sequência ao carregar a chave.

Exemplo:

```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;

        # pipe nomeado também pode ser usado em vez de um arquivo
        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

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_prefer_server_ciphers` `on` | `off`;   |
|-------------------------------------------------------------------------------------------|---------------------------------------------|
| Padrão                                                                                    | `ssl_prefer_server_ciphers off;`            |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                                |

Especifica que as cifras do servidor devem ser preferidas sobre as cifras do cliente quando os protocolos SSLv3 e TLS são usados.

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

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

### ssl_protocols

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_protocols` [`SSLv2`] [`SSLv3`] [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`];   |
|-------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
| Padrão                                                                                    | `ssl_protocols TLSv1.2 TLSv1.3;`                                                     |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                                                                         |

#### Versionchanged
Alterado na versão 1.2.0: Parâmetro `TLSv1.3` adicionado ao conjunto padrão.

Habilita os protocolos especificados.

#### NOTE
Os parâmetros TLSv1.1 e TLSv1.2 funcionam apenas quando OpenSSL 1.0.1 ou superior é usado.

O parâmetro TLSv1.3 funciona apenas quando OpenSSL 1.1.1 ou superior é usado.

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

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

### ssl_session_cache

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_cache` `off` | `none` | [builtin[:tamanho]] [shared:nome:tamanho];   |
|-------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------|
| Padrão                                                                                    | `ssl_session_cache none;`                                                         |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                                                                      |

Define os tipos e tamanhos de caches que armazenam parâmetros de sessão. Um cache pode ser de qualquer um dos seguintes tipos:

| `off`     | o uso de um cache de sessão é estritamente proibido: o Angie explicitamente informa ao cliente que as sessões não podem ser reutilizadas.                                                                                                                                                                                                                                                                                                                                                                 |
|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `none`    | o uso de um cache de sessão é gentilmente desencorajado: o Angie informa ao cliente que as sessões podem ser reutilizadas, mas não armazena realmente os parâmetros de sessão no cache.                                                                                                                                                                                                                                                                                                                   |
| `builtin` | um cache integrado no OpenSSL; usado por apenas um processo worker. O tamanho do cache é especificado em sessões. Se o tamanho não for fornecido, é igual a 20480 sessões. O uso do cache integrado pode causar fragmentação de memória.                                                                                                                                                                                                                                                                  |
| `shared`  | um cache compartilhado entre todos os processos worker. O tamanho do cache é especificado em bytes; um megabyte pode armazenar cerca de 4000 sessões. Cada cache compartilhado deve ter um nome arbitrário. Um cache com o mesmo nome pode ser usado em vários servidores. Também é usado para gerar automaticamente, armazenar e rotacionar periodicamente chaves de ticket de sessão TLS, a menos que configurado explicitamente usando a diretiva [ssl_session_ticket_key](#m-ssl-session-ticket-key). |

Ambos os tipos de cache podem ser usados simultaneamente, por exemplo:

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

mas usar apenas cache compartilhado sem o cache integrado deve ser mais eficiente.

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

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

### ssl_session_ticket_key

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_ticket_key` arquivo;   |
|-------------------------------------------------------------------------------------------|-------------------------------------|
| Padrão                                                                                    | —                                   |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                        |

Define um arquivo com a chave secreta usada para criptografar e descriptografar tickets de sessão TLS. A diretiva é necessária se a mesma chave deve ser compartilhada entre múltiplos servidores. Por padrão, uma chave gerada aleatoriamente é usada.

Se várias chaves são especificadas, apenas a primeira chave é usada para criptografar tickets de sessão TLS. Isso permite configurar rotação de chaves, por exemplo:

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

O arquivo deve conter 80 ou 48 bytes de dados aleatórios e pode ser criado usando o seguinte comando:

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

Dependendo do tamanho do arquivo, AES256 (para chaves de 80 bytes) ou AES128 (para chaves de 48 bytes) é usado para criptografia.

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

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

### ssl_session_tickets

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_tickets` `on` | `off`;   |
|-------------------------------------------------------------------------------------------|---------------------------------------|
| Padrão                                                                                    | `ssl_session_tickets on;`             |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                          |

Habilita ou desabilita a retomada de sessão através de [tickets de sessão TLS](https://datatracker.ietf.org/doc/html/rfc5077).

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

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

### ssl_session_timeout

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_timeout` tempo;   |
|-------------------------------------------------------------------------------------------|--------------------------------|
| Padrão                                                                                    | `ssl_session_timeout 5m;`      |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                   |

Especifica um tempo durante o qual um cliente pode reutilizar os parâmetros de sessão.

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

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

### ssl_trusted_certificate

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_trusted_certificate` arquivo;   |
|-------------------------------------------------------------------------------------------|--------------------------------------|
| Padrão                                                                                    | —                                    |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                         |

Especifica um arquivo com certificados CA confiáveis no formato PEM usado para [verificar](#m-ssl-verify-client) certificados de cliente.

Em contraste com o conjunto de certificados definido por [ssl_client_certificate](#m-ssl-client-certificate), a lista desses certificados não será enviada aos clientes.

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

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

### ssl_verify_client

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_verify_client` `on` | `off` | `optional` | `optional_no_ca`;   |
|-------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
| Padrão                                                                                    | `ssl_verify_client off;`                                            |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                                                        |

Habilita a verificação de certificados de cliente. O resultado da verificação é passado no cabeçalho `Auth-SSL-Verify` da requisição de [autenticação](https://pt.angie.software//angie/docs/configuration/modules/mail/mail_auth_http.md#m-auth-http). Se ocorrer um erro durante a verificação do certificado do cliente ou se um cliente não fornecer o certificado necessário, a conexão é fechada.

| `optional`       | solicita o certificado do cliente e o verifica se o certificado estiver presente                                                                                                                                                                                                                                                                                                                                                                     |
|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `optional_no_ca` | solicita o certificado do cliente mas não exige que ele seja assinado por um certificado de CA confiável. Isso é destinado para uso em casos quando um serviço externo ao Angie executa a verificação real do certificado. O conteúdo do certificado é acessível através de requisições [enviadas](https://pt.angie.software//angie/docs/configuration/modules/mail/mail_auth_http.md#m-auth-http-pass-client-cert) para o servidor de autenticação. |

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

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

### ssl_verify_depth

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_verify_depth` número;   |
|-------------------------------------------------------------------------------------------|------------------------------|
| Padrão                                                                                    | `ssl_verify_depth 1;`        |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                 |

Define a profundidade de verificação na cadeia de certificados do cliente.

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

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

### starttls

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `starttls` `on` | `off` | `only`;   |
|-------------------------------------------------------------------------------------------|-------------------------------------|
| Padrão                                                                                    | `starttls off;`                     |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                        |

| `on`   | permite o uso do comando STLS para POP3 e do comando STARTTLS para IMAP e SMTP;   |
|--------|-----------------------------------------------------------------------------------|
| `off`  | nega o uso dos comandos STLS e STARTTLS;                                          |
| `only` | exige transição TLS preliminar.                                                   |