<!-- review: finished -->

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

# SSL

Fornece o suporte necessário para HTTPS.

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‑http_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-42"></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 conexões [keep-alive](https://pt.angie.software//angie/docs/configuration/modules/http/index.md#keepalive-timeout),
* habilitar o cache de sessão [compartilhado](#ssl-session-cache),
* desabilitar o cache de sessão [integrado](#ssl-session-cache),
* e possivelmente aumentar o [tempo de vida](#ssl-session-timeout) da sessão (por padrão, 5 minutos):

```nginx
worker_processes auto;

http {

    # ...

    server {
        listen              443 ssl;
        keepalive_timeout   70;

        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-45"></a>

## Diretivas

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

<a id="ssl-buffer-size"></a>

### ssl_buffer_size

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_buffer_size` size;   |
|-------------------------------------------------------------------------------------------|---------------------------|
| Padrão                                                                                    | `ssl_buffer_size 16k;`    |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server              |

Define o tamanho do buffer usado para enviar dados.

Por padrão, o tamanho do buffer é 16k, que corresponde ao overhead mínimo ao enviar respostas grandes. Para minimizar o Time To First Byte pode ser benéfico usar valores menores, por exemplo:

```nginx
ssl_buffer_size 4k;
```

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

<a id="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)  | http, server              |

Especifica um arquivo com o certificado no formato PEM para o servidor virtual dado. 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              443 ssl;
    server_name         example.com;

    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.

#### NOTE
Variáveis podem ser usadas no nome do arquivo ao usar OpenSSL 1.0.2 ou superior:

```nginx
ssl_certificate     $ssl_server_name.crt;
ssl_certificate_key $ssl_server_name.key;
```

Note que usar variáveis implica que um certificado será carregado para cada handshake SSL, e isso pode ter um impacto negativo na performance.

O valor `data:$variable` pode ser especificado em vez do file, que carrega um certificado de uma variável 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).

#### NOTE
> Deve-se ter em mente que devido às limitações do protocolo HTTPS para máxima interoperabilidade, servidores virtuais devem escutar em [endereços IP diferentes](https://pt.angie.software//angie/docs/configuration/ssl.md#https-separate-ips).

Se [ssl_ntls](#ssl-ntls) estiver habilitado, a diretiva pode aceitar dois argumentos
(as partes de assinatura e criptografia do certificado)
em vez de um:

```nginx
listen ... ssl;

ssl_ntls  on;

# certificado NTLS duplo
ssl_certificate      sign.crt enc.crt;
ssl_certificate_key  sign.key enc.key;

# pode ser usado junto com um certificado RSA regular
ssl_certificate  rsa.crt;
ssl_certificate_key rsa.key;
```

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

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

### ssl_certificate_cache

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_certificate_cache` `off`;<br/><br/>`ssl_certificate_cache` `max=`N [`inactive=`time] [`valid=`time];   |
|-------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------|
| Padrão                                                                                    | `ssl_certificate_cache off;`                                                                                |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                                                                                                |

Define um cache que armazena [certificados SSL](#ssl-certificate) e [chaves secretas](#ssl-certificate-key) especificados usando variáveis.

A diretiva suporta os seguintes parâmetros:

- `max` — define o número máximo de elementos no cache. Quando o cache
  transborda, os elementos menos recentemente usados (LRU) são removidos.
- `inactive` — define o tempo após o qual um elemento é removido se não
  foi acessado. O padrão é 10 segundos.
- `valid` — define o tempo durante o qual um elemento em cache é considerado
  válido e pode ser reutilizado. O padrão é 60 segundos. Após este período,
  certificados são recarregados ou revalidados.
- `off` — desabilita o cache.

Exemplo:

```nginx
ssl_certificate       $ssl_server_name.crt;
ssl_certificate_key   $ssl_server_name.key;
ssl_certificate_cache max=1000 inactive=20s valid=1m;
```

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

<a id="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)  | http, 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`.

Se [ssl_stapling](#ssl-stapling) estiver habilitado, a compressão de certificados é desabilitada.

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

<a id="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)  | http, server                  |

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

#### NOTE
Variáveis podem ser usadas no nome do arquivo ao usar OpenSSL 1.0.2 ou superior.

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:$variable` pode ser especificado em vez do file, que carrega uma chave secreta de uma variável 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).

> Se [ssl_ntls](#ssl-ntls) estiver habilitado, a diretiva pode aceitar dois argumentos
> (as partes de assinatura e criptografia da chave)
> em vez de um:

> ```nginx
> listen ... ssl;

> ssl_ntls  on;

> # certificado NTLS duplo
> ssl_certificate      sign.crt enc.crt;
> ssl_certificate_key  sign.key enc.key;

> # pode ser usado junto com um certificado RSA regular
> ssl_certificate  rsa.crt;
> ssl_certificate_key rsa.key;
> ```

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

<a id="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)  | http, 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 configurar cifras TLS 1.3 com OpenSSL, use a
diretiva [ssl_conf_command](#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-6"></a>

<a id="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)  | http, server                     |

Especifica um arquivo com certificados CA confiáveis no formato PEM usado para
[verificar](#ssl-verify-client) certificados de cliente e respostas OCSP se
[ssl_stapling](#ssl-stapling) estiver habilitado.

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

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

<a id="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)  | http, server                     |

Define [comandos de configuração](https://docs.openssl.org/master/man3/SSL_CONF_cmd/) 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 houver diretivas ssl_conf_command definidas no nível atual.

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

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

<a id="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)  | http, server      |

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

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

<a id="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)  | http, 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-10"></a>

<a id="ssl-early-data"></a>

### ssl_early_data

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

Habilita ou desabilita [dados iniciais](https://datatracker.ietf.org/doc/html/rfc8446#section-2.3) TLS 1.3.

Requisições enviadas dentro de dados iniciais estão sujeitas a [ataques de replay](https://datatracker.ietf.org/doc/html/rfc8470). Para proteger contra tais ataques na camada de aplicação, a variável [$ssl_early_data](#v-ssl-early-data) deve ser usada.

```nginx
proxy_set_header Early-Data $ssl_early_data;
```

#### NOTE
A diretiva é suportada ao usar OpenSSL 1.1.1 ou superior ou [BoringSSL](https://boringssl.googlesource.com/boringssl/).

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

<a id="ssl-encrypted-hello-key"></a>

### ssl_encrypted_hello_key

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

Especifica um arquivo com uma chave privada ECH e ECHConfigList no formato PEM.
A diretiva pode ser especificada múltiplas vezes.
Requer uma compilação OpenSSL ou BoringSSL com suporte a Encrypted Client Hello (ECH);
caso contrário, não é suportada.

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

<a id="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)  | http, 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` corresponde à lista de curvas incorporadas na biblioteca OpenSSL para OpenSSL 1.0.2 ou superior, ou prime256v1 para 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-13"></a>

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

### ssl_ntls

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

Habilita suporte do lado do servidor para NTLS ao usar a biblioteca TLS [TongSuo](https://github.com/Tongsuo-Project/Tongsuo).

```nginx
listen ... ssl;
ssl_ntls  on;
```

#### NOTE
O Angie deve ser compilado com o parâmetro de configuração `--with-ntls`, com a biblioteca SSL correspondente com suporte NTLS

```default
./configure --with-openssl=../Tongsuo-8.3.0 \
            --with-openssl-opt=enable-ntls  \
            --with-ntls
```

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

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

### ssl_ocsp

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

Habilita validação OCSP da cadeia de certificados do cliente. O parâmetro `leaf` habilita validação apenas do certificado do cliente.

Para que a validação OCSP funcione, a diretiva [ssl_verify_client](#ssl-verify-client) deve ser definida como `on` ou `optional`.

Para resolver o nome do host do respondedor OCSP, a diretiva [resolver](https://pt.angie.software//angie/docs/configuration/modules/http/index.md#resolver) também deve ser especificada.

Exemplo:

```nginx
ssl_verify_client on;
ssl_ocsp          on;
resolver          127.0.0.53;
```

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

<a id="ssl-ocsp-cache"></a>

### ssl_ocsp_cache

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ocsp_cache` `off` | [shared:name:size];   |
|-------------------------------------------------------------------------------------------|------------------------------------------------|
| Padrão                                                                                    | `ssl_ocsp_cache off;`                          |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                                   |

Define o nome e tamanho do cache que armazena o status do certificado do cliente para validação OCSP. O cache é compartilhado entre todos os processos worker. Um cache com o mesmo nome pode ser usado em vários servidores virtuais.

O parâmetro `off` proíbe o uso do cache.

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

<a id="ssl-ocsp-responder"></a>

### ssl_ocsp_responder

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

Substitui a URI do respondedor OCSP especificada na extensão de certificado ["Authority Information Access"](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.2.1) para [validação](#ssl-ocsp) de certificados de cliente.

Apenas respondedores OCSP `http://` são suportados:

```nginx
ssl_ocsp_responder http://ocsp.example.com/;
```

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

<a id="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)  | http, server                |

Especifica um arquivo com senhas para [chaves secretas](#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
http {
    ssl_password_file /etc/keys/global.pass;
    ...

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

    server {
        server_name www2.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-18"></a>

<a id="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)  | http, server                                |

Especifica que as cifras do servidor devem ser preferidas sobre as cifras do cliente ao usar os protocolos SSLv3 e TLS.

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

<a id="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)  | http, server                                                                         |

#### Versionchanged
Alterado na versão 1.2.0: O parâmetro `TLSv1.3` foi 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-20"></a>

<a id="ssl-reject-handshake"></a>

### ssl_reject_handshake

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

Se habilitado, handshakes SSL no bloco [server](https://pt.angie.software//angie/docs/configuration/modules/http/index.md#server) serão rejeitados.

Por exemplo, na seguinte configuração, handshakes SSL com nomes de servidor diferentes de example.com são rejeitados:

```nginx
server {
    listen               443 ssl default_server;
    ssl_reject_handshake on;
}

server {
    listen              443 ssl;
    server_name         example.com;
    ssl_certificate     example.com.crt;
    ssl_certificate_key example.com.key;
}
```

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

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

### ssl_session_cache

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_cache` `off` | `none` | [builtin[:size]] [shared:name:size];   |
|-------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| Padrão                                                                                    | `ssl_session_cache none;`                                                   |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, 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 virtuais. 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](#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-22"></a>

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

### ssl_session_ticket_key

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_ticket_key` file;   |
|-------------------------------------------------------------------------------------------|----------------------------------|
| Padrão                                                                                    | —                                |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, 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 precisa 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) será usado para criptografia.

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

<a id="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)  | http, 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-24"></a>

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

### ssl_session_timeout

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

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

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

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

### ssl_stapling

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

Habilita ou desabilita o [stapling de respostas OCSP](https://datatracker.ietf.org/doc/html/rfc6066#section-8) pelo servidor. Exemplo:

```nginx
ssl_stapling on;
resolver 127.0.0.53;
```

Para que o stapling OCSP funcione, o certificado do emissor do certificado do servidor deve ser conhecido. Se o arquivo [ssl_certificate](#ssl-certificate) não contiver certificados intermediários, o certificado do emissor do certificado do servidor deve estar presente no arquivo especificado pela diretiva [ssl_trusted_certificate](#ssl-trusted-certificate).

#### WARNING
Para a resolução do nome do host do respondedor OCSP, a diretiva [resolver](https://pt.angie.software//angie/docs/configuration/modules/http/index.md#resolver) também deve ser especificada.

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

<a id="ssl-stapling-file"></a>

### ssl_stapling_file

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

Quando definido, a resposta OCSP anexada será obtida do arquivo especificado em vez de consultar o respondedor OCSP especificado no certificado do servidor.

O arquivo deve estar no formato DER conforme produzido pelo comando `openssl ocsp`.

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

<a id="ssl-stapling-responder"></a>

### ssl_stapling_responder

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

Substitui o URI do respondedor OCSP especificado na extensão de certificado ["Authority Information Access"](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.2.1).

Apenas respondedores OCSP `http://` são suportados:

```nginx
ssl_stapling_responder http://ocsp.example.com/;
```

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

<a id="ssl-stapling-verify"></a>

### ssl_stapling_verify

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

Habilita ou desabilita a verificação de respostas OCSP pelo servidor.

Para que a verificação funcione, o certificado do emissor do certificado do servidor, o certificado raiz e todos os certificados intermediários devem ser configurados como confiáveis usando a diretiva [ssl_trusted_certificate](#ssl-trusted-certificate).

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

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

### ssl_trusted_certificate

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

Especifica um arquivo com certificados CA confiáveis no formato PEM usado para [verificar](#ssl-verify-client) certificados de cliente e respostas OCSP se [ssl_stapling](#ssl-stapling) estiver habilitado.

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

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

<a id="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)  | http, server                                                        |

Habilita a verificação de certificados de cliente. O resultado da verificação é armazenado na variável [$ssl_client_verify](#v-ssl-client-verify).

| `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 seja assinado por um certificado CA confiável. Isso é destinado ao uso em casos quando um serviço externo ao Angie executa a verificação real do certificado. |

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

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

### ssl_verify_depth

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

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

<a id="ssl-error-codes"></a>

## Processamento de Erros

O módulo `http_ssl` suporta vários códigos de erro não padrão que podem ser usados para redirecionamentos usando a diretiva [error_page](https://pt.angie.software//angie/docs/configuration/modules/http/index.md#error-page):

| `495`   | ocorreu um erro durante a verificação do certificado do cliente;   |
|---------|--------------------------------------------------------------------|
| `496`   | um cliente não apresentou o certificado obrigatório;               |
| `497`   | uma requisição regular foi enviada para a porta HTTPS.             |

O redirecionamento acontece após a requisição ser completamente analisada e as variáveis, como [$request_uri](https://pt.angie.software//angie/docs/configuration/modules/http/index.md#v-request-uri), [$uri](https://pt.angie.software//angie/docs/configuration/modules/http/index.md#v-uri), [$args](https://pt.angie.software//angie/docs/configuration/modules/http/index.md#v-args) e outras, estarem disponíveis.

<a id="built-in-variables-12"></a>

## Variáveis Integradas

O módulo `http_ssl` suporta variáveis integradas:

<a id="v-ssl-alpn-protocol"></a>

### `$ssl_alpn_protocol`

retorna o protocolo selecionado pelo ALPN durante o handshake SSL, ou uma string vazia caso contrário.

<a id="v-ssl-cipher"></a>

### `$ssl_cipher`

retorna o nome da cifra usada para uma conexão SSL estabelecida.

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

### `$ssl_ciphers`

retorna a lista de cifras suportadas pelo cliente. Cifras conhecidas são listadas por nomes, desconhecidas são mostradas em hexadecimal, por exemplo:

> AES128-SHA:AES256-SHA:0x00ff

#### NOTE
A variável é totalmente suportada apenas quando usando OpenSSL versão 1.0.2 ou superior. Com versões mais antigas, a variável está disponível apenas para novas sessões e lista apenas cifras conhecidas.

<a id="v-ssl-client-escaped-cert"></a>

### `$ssl_client_escaped_cert`

retorna o certificado do cliente no formato PEM (urlencoded) para uma conexão SSL estabelecida.

<a id="v-ssl-client-fingerprint"></a>

### `$ssl_client_fingerprint`

retorna a impressão digital SHA1 do certificado do cliente para uma conexão SSL estabelecida.

<a id="v-ssl-client-i-dn"></a>

### `$ssl_client_i_dn`

retorna a string "issuer DN" do certificado do cliente para uma conexão SSL estabelecida de acordo com a [RFC 2253](https://datatracker.ietf.org/doc/html/rfc2253).

<a id="v-ssl-client-i-dn-legacy"></a>

### `$ssl_client_i_dn_legacy`

retorna a string "issuer DN" do certificado do cliente para uma conexão SSL estabelecida.

<a id="v-ssl-client-raw-cert"></a>

### `$ssl_client_raw_cert`

retorna o certificado do cliente no formato PEM para uma conexão SSL estabelecida.

<a id="v-ssl-client-s-dn"></a>

### `$ssl_client_s_dn`

retorna a string "subject DN" do certificado do cliente para uma conexão SSL estabelecida de acordo com a [RFC 2253](https://datatracker.ietf.org/doc/html/rfc2253).

<a id="v-ssl-client-s-dn-legacy"></a>

### `$ssl_client_s_dn_legacy`

retorna a string "subject DN" do certificado do cliente para uma conexão SSL estabelecida.

<a id="v-ssl-client-serial"></a>

### `$ssl_client_serial`

retorna o número de série do certificado do cliente para uma conexão SSL estabelecida.

<a id="v-ssl-client-sigalg"></a>

### `$ssl_client_sigalg`

retorna o [algoritmo de assinatura](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16) para o certificado do cliente para uma conexão SSL estabelecida.

#### NOTE
A variável é suportada apenas quando usando OpenSSL versão 3.5 ou superior. Com versões mais antigas, o valor da variável será uma string vazia.

#### NOTE
A variável está disponível apenas para novas sessões.

<a id="v-ssl-client-v-end"></a>

### `$ssl_client_v_end`

retorna a data de término do certificado do cliente.

<a id="v-ssl-client-v-remain"></a>

### `$ssl_client_v_remain`

retorna o número de dias até o certificado do cliente expirar.

<a id="v-ssl-client-v-start"></a>

### `$ssl_client_v_start`

retorna a data de início do certificado do cliente.

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

### `$ssl_client_verify`

retorna o resultado da verificação do certificado do cliente: `SUCCESS`, `FAILED:reason`, e `NONE` se um certificado não estava presente.

<a id="v-ssl-curve"></a>

### `$ssl_curve`

retorna a curva negociada usada para troca de chaves durante o handshake SSL. Curvas conhecidas são listadas por nomes, desconhecidas são mostradas em hexadecimal, por exemplo:

> prime256v1

#### NOTE
A variável é suportada apenas quando usando OpenSSL versão 3.0 ou superior. Com versões mais antigas, o valor da variável será uma string vazia.

<a id="v-ssl-curves"></a>

### `$ssl_curves`

retorna a lista de curvas suportadas pelo cliente. Curvas conhecidas são listadas por nomes, desconhecidas são mostradas em hexadecimal, por exemplo:

> 0x001d:prime256v1:secp521r1:secp384r1

#### NOTE
A variável é suportada apenas quando usando OpenSSL versão 1.0.2 ou superior. Com versões mais antigas, o valor da variável será uma string vazia.

A variável está disponível apenas para novas sessões.

<a id="v-ssl-early-data"></a>

### `$ssl_early_data`

retorna "1" se TLS 1.3 [early data](#ssl-early-data) é usado e o handshake não está completo, caso contrário "".

<a id="v-ssl-encrypted-hello"></a>

### `$ssl_encrypted_hello`

retorna "1" se Encrypted Client Hello (ECH) é usado, caso contrário "".

<a id="v-ssl-protocol"></a>

### `$ssl_protocol`

retorna o protocolo de uma conexão SSL estabelecida.

<a id="v-ssl-server-cert-type"></a>

### `$ssl_server_cert_type`

assume os valores `RSA`, `DSA`, `ECDSA`, `ED448`,
`ED25519`, `SM2`, `RSA-PSS`, ou `unknown` dependendo
do tipo de certificado e chave do servidor.

<a id="v-ssl-server-name"></a>

### `$ssl_server_name`

retorna o nome do servidor solicitado através de [SNI](http://en.wikipedia.org/wiki/Server_Name_Indication).

<a id="v-ssl-session-id"></a>

### `$ssl_session_id`

retorna o identificador de sessão de uma conexão SSL estabelecida.

<a id="v-ssl-session-reused"></a>

### `$ssl_session_reused`

retorna "r" se uma sessão SSL foi reutilizada, ou "." caso contrário.

<a id="v-ssl-sigalg"></a>

### `$ssl_sigalg`

retorna o [algoritmo de assinatura](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16) para o certificado do servidor para uma conexão SSL estabelecida.

#### NOTE
A variável é suportada apenas quando usando OpenSSL versão 3.5 ou superior. Com versões mais antigas, o valor da variável será uma string vazia.

#### NOTE
A variável está disponível apenas para novas sessões.