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,
este módulo não é compilado por padrão;
ele deve ser habilitado com a
--with-stream_ssl_module
opção de compilação.
Em pacotes e imagens dos 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 é recomendado
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,
e possivelmente aumentar o tempo de vida da sessão (por padrão, 5 minutos):
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 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:
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;
# ...
}
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.
Nota
Variáveis podem ser usadas no nome do arquivo ao usar OpenSSL 1.0.2 ou superior:
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.
ssl_certificate_key#
Especifica um arquivo com a chave secreta no formato PEM para o servidor especificado.
Nota
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 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.
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
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, 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.
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.
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:
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 dados iniciais 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 os certificados ECDSA funcionem, é importante incluir as curvas usadas nos certificados.
ssl_handshake_timeout#
Especifica um timeout para a conclusão do handshake SSL.
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_ntls#
Adicionado na versão 1.2.0.
Habilita o suporte do lado do servidor para NTLS usando a biblioteca TongSuo.
listen ... ssl;
ssl_ntls on;
Nota
O Angie deve ser compilado usando a opção de compilação --with-ntls e vinculado com a biblioteca SSL habilitada para NTLS
./configure --with-openssl=../Tongsuo-8.3.0 \
--with-openssl-opt=enable-ntls \
--with-ntls
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;
# 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;
}
}
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 |
Alterado na versão 1.2.0: Parâmetro TLSv1.3 adicionado ao conjunto padrão.
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_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) é 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 contém 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 ocorreu um erro durante a verificação do certificado do cliente ou um cliente não apresentou 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: AES128-SHA:AES256-SHA:0x00ff 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 a data de expiração 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: prime256v1 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: 0x001d:prime256v1:secp521r1:secp384r1 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. 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 "". 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 stream_ssl suporta as seguintes variáveis:$ssl_alpn_protocol#$ssl_cipher#$ssl_ciphers#$ssl_client_cert#$ssl_client_fingerprint#$ssl_client_i_dn#$ssl_client_raw_cert#$ssl_client_s_dn#$ssl_client_serial#$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#$ssl_curves#$ssl_early_data#$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#r se uma sessão SSL foi reutilizada, ou "." caso contrário.
Conteúdo