SSL#
Fornece o suporte necessário para um servidor proxy stream trabalhar com o protocolo SSL/TLS.
Ao compilar a partir do código-fonte, o módulo não é
compilado por padrão; ele deve ser habilitado com a opção de
compilação --with-stream_ssl_module.
Em pacotes e imagens de nossos repositórios, o módulo está incluído na compilação.
Nota
Este módulo requer a biblioteca OpenSSL.
Exemplo de configuração#
Para reduzir a carga do processador, recomenda-se:
definir o número de processos worker igual ao número de processadores;
habilitar o cache de sessão compartilhado;
desabilitar o cache de sessão integrado;
se necessário, aumentar o tempo de vida da sessão (por padrão, 5 minutos).
Por exemplo:
worker_processes auto;
stream {
#...
server {
listen 12345 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;
# ...
}
Diretivas#
ssl_alpn#
Especifica a lista de protocolos ALPN suportados. Um dos protocolos deve ser negociado se o cliente usar ALPN:
map $ssl_alpn_protocol $proxy {
h2 127.0.0.1:8001;
http/1.1 127.0.0.1:8002;
}
server {
listen 12346;
proxy_pass $proxy;
ssl_alpn h2 http/1.1;
}
ssl_certificate#
Especifica o certificado no formato PEM para o servidor especificado. Certificados intermediários, se houver, vêm depois do certificado primário no mesmo arquivo ou valor; uma chave secreta no formato PEM também pode ser colocada ali.
O valor é interpretado como na diretiva ssl_certificate
do módulo HTTP SSL: um caminho de arquivo ou o texto PEM do
certificado após o prefixo data:.
O valor pode conter variáveis. Nesse caso, o Angie carrega todos os certificados e chaves do servidor durante cada handshake SSL; ssl_certificate_cache os mantém para reutilização, enquanto ssl_stapling e ssl_certificate_compression não têm efeito sobre eles.
Diferentemente do HTTP, as variáveis são avaliadas dentro da sessão, depois que
as diretivas set do servidor padrão para o endereço de escuta
foram executadas; os valores que elas atribuem estão disponíveis durante o
handshake, junto com $ssl_server_name e as variáveis que
map deriva dele. Se o nome de servidor TLS selecionar outro
servidor, as diretivas set desse servidor ainda não foram executadas
nesse momento, então os valores de certificado dele devem se basear em
$ssl_server_name e map.
Esta diretiva pode ser especificada múltiplas vezes para carregar certificados de diferentes tipos, por exemplo, RSA e ECDSA:
server {
listen 12345 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;
# ...
}
ssl_certificate_cache#
| |
Padrão |
|
stream, server |
Define um cache que armazena certificados SSL e chaves secretas 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 durante esse tempo, mesmo que ainda esteja dentro de seu períodovalid; cada acesso reinicia este temporizador. O padrão é 10 segundos.valid— define o tempo durante o qual um elemento em cache é reutilizado sem verificações. O padrão é 60 segundos. Após este período, um elemento carregado de um arquivo é recarregado apenas se o arquivo tiver mudado, e uma chave carregada com o prefixoengine:oustore:é carregada novamente; um elemento especificado com o prefixodata:permanece válido.off— desabilita o cache.
Chaves protegidas por senha (veja ssl_password_file) não são armazenadas em cache.
Exemplo:
ssl_certificate $ssl_server_name.crt;
ssl_certificate_key $ssl_server_name.key;
ssl_certificate_cache max=1000 inactive=20s valid=1m;
ssl_certificate_compression#
| |
Padrão |
|
stream, server |
Habilita compressão de certificados de servidor do TLS 1.3.
Nota
A diretiva é suportada ao usar OpenSSL 3.2 ou superior; a lista de algoritmos de compressão suportados é fornecida pela biblioteca.
Nota
A diretiva é suportada ao usar BoringSSL; a lista de algoritmos de compressão suportados inclui zlib.
A diretiva é incompatível com ssl_stapling: uma configuração que habilita ambos no mesmo servidor falha ao carregar.
ssl_certificate_key#
| |
Padrão | — |
stream, server |
Especifica a chave secreta no formato PEM para o servidor especificado.
O valor, incluindo os prefixos engine: e store:, é interpretado
como na diretiva ssl_certificate_key
do módulo HTTP SSL, e as variáveis nele funcionam conforme
descrito em ssl_certificate. Uma chave protegida por senha é
descriptografada com as senhas de ssl_password_file.
ssl_ciphers#
Especifica as cifras habilitadas. As cifras são especificadas no formato compreendido pela biblioteca OpenSSL, por exemplo:
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.
Aviso
Com o OpenSSL, a diretiva ssl_ciphers não configura cifras TLS 1.3;
defina-as com o comando Ciphersuites da diretiva
ssl_conf_command. A diretiva ssl_ciphers ignora nomes de
cifras TLS 1.3 em seu valor, portanto esses nomes não restringem as conexões TLS 1.3.
Se o valor consistir apenas em tais nomes, por exemplo
TLS_AES_128_GCM_SHA256, a configuração não é carregada, com
o erro no cipher match.
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.
ssl_client_certificate#
Especifica um arquivo com certificados CA confiáveis no formato PEM usados para verificar certificados de cliente e respostas OCSP se ssl_stapling estiver habilitado.
A lista de certificados será enviada aos clientes. Se isso não for desejado, a diretiva ssl_trusted_certificate pode ser usada.
ssl_conf_command#
Define comandos de configuração OpenSSL arbitrários.
Nota
A diretiva é suportada ao usar OpenSSL 1.0.2 ou superior.
O comando Ciphersuites, que define as cifras TLS 1.3, requer
OpenSSL 1.1.1 ou superior.
Várias diretivas ssl_conf_command podem ser especificadas no mesmo nível:
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.
Aviso
Configurar o OpenSSL diretamente pode resultar em comportamento inesperado.
ssl_crl#
Especifica um arquivo com certificados revogados (CRL) no formato PEM usado para verificar certificados de cliente.
ssl_dhparam#
Especifica um arquivo com parâmetros DH para cifras DHE.
Aviso
Por padrão, nenhum parâmetro é definido e, portanto, as cifras DHE não serão usadas.
ssl_early_data#
Habilita ou desabilita early data do TLS 1.3.
Nota
A diretiva é suportada ao usar OpenSSL 1.1.1 ou superior ou BoringSSL.
ssl_ecdh_curve#
Especifica uma curva para cifras ECDHE.
Nota
Ao usar OpenSSL 1.0.2 ou superior, é possível especificar múltiplas curvas, por exemplo:
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.
Nota
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.
ssl_encrypted_hello_key#
Adicionado na versão 1.11.0.
Especifica um arquivo com uma chave secreta e uma configuração para a extensão TLS Encrypted Client Hello (ECH), que oculta o nome do servidor solicitado pelo cliente dos observadores na rede. A variável $ssl_encrypted_hello indica se a extensão foi utilizada em um handshake.
A diretiva pode ser especificada várias vezes, o que permite rotacionar as chaves: todas as chaves são usadas para a descriptografia, mas apenas a configuração da primeira chave é oferecida aos clientes para novas tentativas.
ssl_encrypted_hello_key current.ech;
ssl_encrypted_hello_key previous.ech;
O arquivo contém uma chave secreta seguida de uma ECHConfigList, ambas no formato PEM. Com a ramificação do recurso ECH do OpenSSL, esse arquivo é criado com:
$ openssl ech -public_name public.example.com -out example.ech
Com o BoringSSL, bssl generate-ech grava a chave e a ECHConfigList em
arquivos binários separados, e nenhum dos dois é utilizável como está. Os dois
precisam ser reunidos em um único arquivo PEM: a chave bruta precisa ser
encapsulada em uma estrutura PKCS#8 e codificada em base64 dentro de um bloco
PRIVATE KEY, seguida da ECHConfigList, e não de um ECHConfig isolado,
codificada em base64 dentro de um bloco ECHCONFIG. Compilações com o
BoringSSL aceitam apenas chaves X25519. O formato em si não depende da biblioteca
TLS, portanto um arquivo gerado com o comando acima também é aceito por uma
compilação com o BoringSSL.
O Angie descriptografa o ClientHello antes de saber o nome do servidor
solicitado por meio do SNI, portanto, com vários servidores
virtuais, as chaves precisam ser especificadas para o servidor padrão da porta em
que escutam.
Nota
O suporte a ECH vem da biblioteca TLS, portanto o Angie precisa ser vinculado a uma que o forneça: a ramificação do recurso ECH do OpenSSL, que é configurada assim:
$ ./configure --with-openssl=../openssl-ech
ou o BoringSSL, que é configurado de outra forma. Caso contrário, a diretiva é ignorada com um aviso no log de erros.
ssl_handshake_timeout#
Especifica um tempo limite para a conclusão do handshake SSL.
ssl_keylog_file#
Especifica um arquivo para registrar as chaves SSL/TLS das conexões tratadas pelo contexto, usando o formato SSLKEYLOGFILE utilizado por ferramentas como o Wireshark para descriptografar o tráfego TLS capturado.
A diretiva não deve ser usada com LibreSSL.
Aviso
O arquivo contém material de chaves TLS sensível que permite descriptografar o tráfego capturado das conexões correspondentes. Use esta diretiva apenas para depuração ou análise de protocolo, restrinja o acesso ao arquivo e remova-o quando não for mais necessário.
ssl_ntls#
Habilita o suporte do lado do servidor para NTLS usando a biblioteca Tongsuo.
listen ... ssl;
ssl_ntls on;
Nota
O Angie deve ser compilado com o parâmetro de configuração --with-ntls e uma biblioteca SSL com suporte a NTLS:
$ ./configure --with-openssl=../Tongsuo-8.3.0 \
--with-openssl-opt=enable-ntls \
--with-ntls
ssl_ocsp#
Habilita a validação OCSP da cadeia de certificados do cliente. O parâmetro leaf
habilita a validação apenas do certificado do cliente.
Para que a validação OCSP funcione, a diretiva ssl_verify_client deve
ser definida como on ou optional.
Para resolver o nome do host do respondedor OCSP, a diretiva resolver também deve ser especificada.
Exemplo:
ssl_verify_client on;
ssl_ocsp on;
resolver 127.0.0.53;
ssl_ocsp_cache#
Define o nome e tamanho do cache que armazena o status dos certificados de 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.
ssl_ocsp_responder#
Substitui a URI do respondedor OCSP especificada na extensão de certificado "Authority Information Access" para validação de certificados de cliente.
Apenas respondedores OCSP http:// são suportados:
ssl_ocsp_responder http://ocsp.example.com/;
ssl_password_file#
Especifica um arquivo com senhas para chaves secretas onde cada senha é especificada em uma linha separada. As senhas são testadas em sequência ao carregar a chave.
Exemplo:
stream {
ssl_password_file /etc/keys/global.pass;
...
server {
listen 127.0.0.1:12345;
ssl_certificate_key /etc/keys/first.key;
}
server {
listen 127.0.0.1:12346;
# named pipe também pode ser usado em vez de um arquivo
ssl_password_file /etc/keys/fifo;
ssl_certificate_key /etc/keys/second.key;
}
}
ssl_prefer_server_ciphers#
| |
Padrão |
|
stream, server |
Especifica que as cifras do servidor devem ser preferidas sobre as cifras do cliente quando os protocolos SSLv3 e TLS são usados.
ssl_protocols#
| |
Padrão |
|
stream, server |
Habilita os protocolos especificados.
Nota
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.
ssl_reject_handshake#
Se habilitado, os handshakes SSL no bloco server serão recusados.
Por exemplo, na configuração a seguir, handshakes SSL com nomes de servidor diferentes de example.com são recusados:
server {
listen 12345 ssl default_server;
ssl_reject_handshake on;
}
server {
listen 12345 ssl;
server_name example.com;
ssl_certificate example.com.crt;
ssl_certificate_key example.com.key;
}
ssl_session_cache#
| |
Padrão |
|
stream, 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:
| 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. |
| 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. |
| 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. |
| 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 as chaves de ticket de sessão TLS, a menos que configurado explicitamente usando a diretiva ssl_session_ticket_key. |
Ambos os tipos de cache podem ser usados simultaneamente, por exemplo:
ssl_session_cache builtin:1000 shared:SSL:10m;
mas usar apenas cache compartilhado sem o cache integrado deve ser mais eficiente.
ssl_session_ticket_key#
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 forem especificadas, apenas a primeira chave é usada para criptografar tickets de sessão TLS. Isso permite configurar rotação de chaves, por exemplo:
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:
$ 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.
ssl_session_tickets#
Habilita ou desabilita a retomada de sessão através de tickets de sessão TLS.
ssl_session_timeout#
Especifica um tempo durante o qual um cliente pode reutilizar os parâmetros de sessão.
ssl_stapling#
Habilita ou desabilita o grampeamento de respostas OCSP pelo servidor. Exemplo:
ssl_stapling on;
resolver 127.0.0.53;
Para que o grampeamento OCSP funcione, o certificado do emissor do certificado do servidor deve ser conhecido. Se o arquivo ssl_certificate não contiver certificados intermediários, o certificado do emissor do certificado do servidor deve estar presente no arquivo ssl_trusted_certificate.
Aviso
Para a resolução do nome do host do respondedor OCSP, a diretiva resolver também deve ser especificada.
ssl_stapling_file#
Quando definido, a resposta OCSP grampeada 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.
ssl_stapling_responder#
Substitui a URI do respondedor OCSP especificada na extensão de certificado "Authority Information Access".
Apenas respondedores OCSP http:// são suportados:
ssl_stapling_responder http://ocsp.example.com/;
ssl_stapling_verify#
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#
Especifica um arquivo com certificados CA confiáveis no formato PEM usado para verificar certificados de cliente.
Em contraste com o conjunto de certificados definido por ssl_client_certificate, a lista desses certificados não será enviada aos clientes.
ssl_verify_client#
| |
Padrão |
|
stream, server |
Habilita a verificação de certificados de cliente. O resultado da verificação é armazenado na variável $ssl_client_verify. Se ocorrer um erro durante a verificação do certificado do cliente ou se um cliente não apresentar o certificado necessário, a conexão é fechada.
| solicita o certificado do cliente e o verifica se o certificado estiver presente. |
| 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. |
ssl_verify_depth#
Define a profundidade de verificação na cadeia de certificados do cliente.
Variáveis integradas#
O módulo retorna o protocolo selecionado pelo ALPN durante o handshake SSL, ou uma string vazia caso contrário. retorna o nome da cifra usada para uma conexão SSL estabelecida. retorna a lista de cifras suportadas pelo cliente. Cifras conhecidas são listadas por nomes, desconhecidas são mostradas em hexadecimal, por exemplo: Nota 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. retorna o certificado do cliente no formato PEM para uma conexão SSL estabelecida, com cada linha exceto a primeira precedida pelo caractere de tabulação. retorna a impressão digital SHA1 do certificado do cliente para uma conexão SSL estabelecida. retorna a string "issuer DN" do certificado do cliente para uma conexão SSL estabelecida de acordo com a RFC 2253. retorna o certificado do cliente no formato PEM para uma conexão SSL estabelecida. retorna a string "subject DN" do certificado do cliente para uma conexão SSL estabelecida de acordo com a RFC 2253. retorna o número de série do certificado do cliente para uma conexão SSL estabelecida. retorna o algoritmo de assinatura para o certificado do cliente para uma conexão SSL estabelecida. Nota 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. Nota A variável está disponível apenas para novas sessões. retorna a data de término do certificado do cliente. retorna o número de dias até o certificado do cliente expirar. retorna a data de início do certificado do cliente. retorna o resultado da verificação do certificado do cliente: retorna a curva negociada usada para o processo de troca de chaves do handshake SSL. Curvas conhecidas são listadas por nomes, desconhecidas são mostradas em hexadecimal, por exemplo: Nota 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. retorna a lista de curvas suportadas pelo cliente. Curvas conhecidas são listadas por nomes, desconhecidas são mostradas em hexadecimal, por exemplo: Nota 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. Nota A variável está disponível apenas para novas sessões. retorna "1" se TLS 1.3 early data é usado e o handshake não está completo, caso contrário "". Adicionado na versão 1.11.0. retorna "1" se o retorna o protocolo de uma conexão SSL estabelecida. assume os valores retorna o nome do servidor solicitado através de SNI. retorna o identificador de sessão de uma conexão SSL estabelecida. retorna "r" se uma sessão SSL foi reutilizada, ou "." caso contrário. retorna o algoritmo de assinatura para o certificado do servidor para uma conexão SSL estabelecida. Nota 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. Nota A variável está disponível apenas para novas sessões. retorna a lista de algoritmos de assinatura oferecidos pelo cliente durante o handshake SSL, como uma lista separada por dois pontos. Nota Com o OpenSSL versão 4.0 ou superior, os algoritmos são retornados por nome; um algoritmo sem nome recorre ao seu código hexadecimal bruto. Bibliotecas SSL que expõem a API de algoritmos de assinatura mais antiga retornam todos os algoritmos como códigos hexadecimais brutos. Compilações sem uma API de algoritmos de assinatura compatível retornam um valor vazio.stream_ssl suporta as seguintes variáveis:$ssl_alpn_protocol#$ssl_cipher#$ssl_ciphers#AES128-SHA:AES256-SHA:0x00ff
$ssl_client_cert#$ssl_client_fingerprint#$ssl_client_i_dn#$ssl_client_raw_cert#$ssl_client_s_dn#$ssl_client_serial#$ssl_client_sigalg#$ssl_client_v_end#$ssl_client_v_remain#$ssl_client_v_start#$ssl_client_verify#SUCCESS, FAILED:reason e NONE se um certificado não estava presente.$ssl_curve#prime256v1
$ssl_curves#0x001d:prime256v1:secp521r1:secp384r1
$ssl_early_data#$ssl_encrypted_hello#ClientHello foi descriptografado por meio da extensão
TLS Encrypted Client Hello (ECH), caso contrário "".$ssl_protocol#$ssl_server_cert_type#RSA, DSA, ECDSA, ED448,
ED25519, SM2, RSA-PSS ou unknown dependendo
do tipo de certificado e chave do servidor.$ssl_server_name#$ssl_session_id#$ssl_session_reused#$ssl_sigalg#$ssl_sigalgs#
Conteúdo