SSL#
Proporciona el soporte necesario para que un servidor proxy de stream funcione con el protocolo SSL/TLS.
Cuando se compila desde el código fuente, este módulo
no se compila por defecto; debe habilitarse con la opción de
compilación --with-stream_ssl_module.
En paquetes e imágenes de nuestros repositorios, el módulo está incluido en la compilación.
Nota
Este módulo requiere la biblioteca OpenSSL.
Ejemplo de configuración#
Para reducir la carga del procesador, se recomienda:
establecer el número de procesos de trabajo igual al número de procesadores;
habilitar la caché de sesión compartida;
deshabilitar la caché de sesión incorporada;
si es necesario, aumentar el tiempo de vida de la sesión (por defecto, 5 minutos).
Por ejemplo:
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;
# ...
}
Directivas#
ssl_alpn#
Especifica la lista de protocolos ALPN admitidos. Uno de los protocolos debe ser negociado si el cliente utiliza 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 el certificado en formato PEM para el servidor dado. Los certificados intermedios, si los hay, siguen al certificado primario en el mismo archivo o valor; también puede colocarse allí una clave secreta en formato PEM.
El valor se interpreta como en la directiva ssl_certificate
del módulo HTTP SSL: una ruta de archivo, o el texto PEM del
certificado tras el prefijo data:.
El valor puede contener variables. En ese caso, Angie carga todos los certificados y claves del servidor en cada negociación SSL; ssl_certificate_cache los conserva para reutilizarlos, mientras que ssl_stapling y ssl_certificate_compression no tienen efecto sobre ellos.
A diferencia de HTTP, las variables se evalúan dentro de la sesión, después de
que se hayan ejecutado las directivas set del servidor
predeterminado para la dirección de escucha; los valores que estas asignan están
disponibles durante la negociación, junto con $ssl_server_name y las
variables que map deriva de ella. Si el nombre de servidor TLS
selecciona otro servidor, las directivas set de ese servidor aún no se
han ejecutado en ese momento, por lo que sus valores de certificado deben
basarse en $ssl_server_name y map.
Esta directiva puede especificarse varias veces para cargar certificados de distintos tipos, por ejemplo, RSA y 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#
| |
Predeterminado |
|
stream, server |
Define una caché que almacena certificados SSL y claves secretas especificados usando variables.
La directiva admite los siguientes parámetros:
max— establece el número máximo de elementos en la caché. Cuando la caché se desborda, se eliminan los elementos menos utilizados recientemente (LRU).inactive— define el tiempo tras el cual un elemento se elimina si no ha sido accedido durante ese tiempo, incluso si todavía está dentro de su períodovalid; cada acceso reinicia este temporizador. El valor predeterminado es 10 segundos.valid— define el tiempo durante el cual un elemento en caché se reutiliza sin comprobaciones. El valor predeterminado es 60 segundos. Pasado este período, un elemento cargado desde un archivo se recarga solo si el archivo ha cambiado, y una clave cargada con el prefijoengine:ostore:se vuelve a cargar; un elemento especificado con el prefijodata:sigue siendo válido.off— desactiva la caché.
Las claves protegidas por una frase de contraseña (véase ssl_password_file) no se almacenan en caché.
Ejemplo:
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#
| |
Predeterminado |
|
stream, server |
Habilita la compresión de certificados de servidor TLS 1.3.
Nota
La directiva es compatible al usar OpenSSL 3.2 o superior; la lista de algoritmos de compresión admitidos es proporcionada por la biblioteca.
Nota
La directiva es compatible al usar BoringSSL; la lista de algoritmos de compresión admitidos incluye zlib.
La directiva es incompatible con ssl_stapling: una configuración que habilita ambas en el mismo servidor no se carga.
ssl_certificate_key#
| |
Predeterminado | — |
stream, server |
Especifica la clave secreta en formato PEM para el servidor dado.
El valor, incluidos los prefijos engine: y store:, se interpreta
como en la directiva ssl_certificate_key del módulo
HTTP SSL, y las variables en él funcionan como se describe en
ssl_certificate. Una clave protegida por una frase de contraseña se
descifra con las frases de contraseña de ssl_password_file.
ssl_ciphers#
Especifica los cifrados habilitados. Los cifrados se indican en el formato que entiende la biblioteca OpenSSL, por ejemplo:
ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
La lista de cifrados depende de la versión de OpenSSL instalada. La lista completa puede consultarse con el comando openssl ciphers.
Advertencia
Con OpenSSL, la directiva ssl_ciphers no configura los cifrados de TLS 1.3;
en su lugar, configúrelos con el comando Ciphersuites de la directiva
ssl_conf_command. La directiva ssl_ciphers ignora los nombres de cifrados
TLS 1.3 de su valor, por lo que dichos nombres no restringen las conexiones
TLS 1.3. Si el valor consta únicamente de tales nombres, por ejemplo
TLS_AES_128_GCM_SHA256, la configuración no se carga y se produce
el error no cipher match.
En LibreSSL, los cifrados TLS 1.3 sí pueden configurarse usando
ssl_ciphers.En BoringSSL, los cifrados TLS 1.3 no pueden configurarse en absoluto.
ssl_client_certificate#
Especifica un archivo con certificados de CA confiables en formato PEM usados para verificar los certificados de cliente y respuestas OCSP si se habilita ssl_stapling.
La lista de certificados se enviará a los clientes. Si esto no es deseado, se puede usar la directiva ssl_trusted_certificate.
ssl_conf_command#
Establece comandos arbitrarios de configuración de OpenSSL.
Nota
La directiva es compatible al usar OpenSSL 1.0.2 o superior.
El comando Ciphersuites, que configura los cifrados de TLS 1.3, requiere
OpenSSL 1.1.1 o superior.
Se pueden especificar varias directivas ssl_conf_command en el mismo nivel:
ssl_conf_command Options PrioritizeChaCha;
ssl_conf_command Ciphersuites TLS_CHACHA20_POLY1305_SHA256;
Estas directivas se heredan del nivel de configuración anterior únicamente si no se definen directivas ssl_conf_command en el nivel actual.
Advertencia
Configurar OpenSSL directamente puede resultar en un comportamiento inesperado.
ssl_crl#
Especifica un archivo con certificados revocados (CRL) en formato PEM usados para verificar los certificados de cliente.
ssl_dhparam#
Especifica un archivo con parámetros DH para los cifrados DHE.
Advertencia
Por defecto no se establecen parámetros, y por lo tanto no se usarán cifrados DHE.
ssl_early_data#
Habilita o deshabilita los early data de TLS 1.3.
Nota
La directiva es compatible al usar OpenSSL 1.1.1 o superior o BoringSSL.
ssl_ecdh_curve#
Especifica una curva para cifrados ECDHE.
Nota
Al usar OpenSSL 1.0.2 o superior, es posible especificar múltiples curvas, por ejemplo:
ssl_ecdh_curve prime256v1:secp384r1;
El valor especial auto indica a Angie que use una lista integrada en la biblioteca OpenSSL cuando se usa OpenSSL 1.0.2 o superior, o prime256v1 con versiones anteriores.
Nota
Al usar OpenSSL 1.0.2 o superior, esta directiva establece la lista de curvas admitidas por el servidor. Por lo tanto, para que los certificados ECDSA funcionen, es importante incluir las curvas usadas en los certificados.
ssl_encrypted_hello_key#
Added in version 1.11.0.
Especifica un archivo con una clave secreta y una configuración para la extensión TLS Encrypted Client Hello (ECH), que oculta el nombre del servidor solicitado por el cliente frente a los observadores de la red. La variable $ssl_encrypted_hello indica si la extensión se utilizó en un protocolo de enlace.
La directiva puede especificarse varias veces, lo que permite rotar las claves: todas las claves se usan para el descifrado, pero solo la configuración de la primera clave se ofrece a los clientes para los reintentos.
ssl_encrypted_hello_key current.ech;
ssl_encrypted_hello_key previous.ech;
El archivo contiene una clave secreta seguida de una ECHConfigList, ambas en formato PEM. Con la rama de la característica ECH de OpenSSL, dicho archivo se crea con:
$ openssl ech -public_name public.example.com -out example.ech
Con BoringSSL, bssl generate-ech escribe la clave y la ECHConfigList en
archivos binarios separados, y ninguno de los dos es utilizable tal cual. Ambos
deben combinarse en un único archivo PEM: la clave en bruto debe envolverse en
una estructura PKCS#8 y codificarse en base64 dentro de un bloque
PRIVATE KEY, seguido de la ECHConfigList, y no un ECHConfig suelto,
codificada en base64 dentro de un bloque ECHCONFIG. Las compilaciones con
BoringSSL solo admiten claves X25519. El formato en sí no depende de la
biblioteca TLS, por lo que un archivo generado con el comando anterior también es
válido para una compilación con BoringSSL.
Angie descifra el ClientHello antes de conocer el nombre del servidor
solicitado a través de SNI, por lo que, con varios servidores
virtuales, las claves deben especificarse para el servidor predeterminado del
puerto en el que escuchan.
Nota
El soporte de ECH proviene de la biblioteca TLS, por lo que Angie debe enlazarse con una que lo proporcione: la rama de la característica ECH de OpenSSL, que se configura así:
$ ./configure --with-openssl=../openssl-ech
o BoringSSL, que se configura de otra manera. De lo contrario, la directiva se ignora con una advertencia en el registro de errores.
ssl_handshake_timeout#
Especifica un tiempo de espera para que se complete el handshake SSL.
ssl_keylog_file#
Especifica un archivo para registrar las claves SSL/TLS de las conexiones gestionadas por el contexto, con el formato SSLKEYLOGFILE que usan herramientas como Wireshark para descifrar el tráfico TLS capturado.
La directiva no debe usarse con LibreSSL.
Advertencia
El archivo contiene material de claves TLS sensible que permite descifrar el tráfico capturado de las conexiones correspondientes. Use esta directiva solo para depuración o análisis de protocolo, restrinja el acceso al archivo y elimínelo cuando ya no sea necesario.
ssl_ntls#
Habilita el soporte del lado del servidor para NTLS usando la biblioteca Tongsuo.
listen ... ssl;
ssl_ntls on;
Nota
Angie debe compilarse con el parámetro de configuración --with-ntls y una biblioteca SSL con soporte NTLS:
$ ./configure --with-openssl=../Tongsuo-8.3.0 \
--with-openssl-opt=enable-ntls \
--with-ntls
ssl_ocsp#
Habilita la validación OCSP de la cadena de certificados del cliente. El parámetro leaf habilita la validación únicamente del certificado del cliente.
Para que la validación OCSP funcione, la directiva ssl_verify_client debe estar establecida en on u optional.
Para resolver el nombre de host del respondedor OCSP, también debe especificarse la directiva resolver.
Ejemplo:
ssl_verify_client on;
ssl_ocsp on;
resolver 127.0.0.53;
ssl_ocsp_cache#
| |
Predeterminado |
|
stream, server |
Establece el nombre y tamaño de la caché que almacena el estado de los certificados de cliente para la validación OCSP. La caché se comparte entre todos los procesos worker. Una caché con el mismo nombre puede usarse en varios servidores virtuales.
El parámetro off prohíbe el uso de la caché.
ssl_ocsp_responder#
Sobrescribe la URI del respondedor OCSP especificada en la extensión del certificado "Authority Information Access" para la validación de certificados de cliente.
Solo se admiten respondedores OCSP con http://:
ssl_ocsp_responder http://ocsp.example.com/;
ssl_password_file#
Especifica un archivo con contraseñas para las claves secretas donde cada contraseña se especifica en una línea separada. Las contraseñas se prueban en orden al cargar la clave.
Ejemplo:
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;
# también puede usarse un named pipe en lugar de un archivo
ssl_password_file /etc/keys/fifo;
ssl_certificate_key /etc/keys/second.key;
}
}
ssl_prefer_server_ciphers#
| |
Predeterminado |
|
stream, server |
Especifica que deben preferirse los cifrados del servidor sobre los cifrados del cliente cuando se usan los protocolos SSLv3 y TLS.
ssl_protocols#
| |
Predeterminado |
|
stream, server |
Habilita los protocolos especificados.
Nota
Los parámetros TLSv1.1 y TLSv1.2 funcionan solo cuando se usa OpenSSL 1.0.1 o superior.
El parámetro TLSv1.3 funciona solo cuando se usa OpenSSL 1.1.1 o superior.
ssl_reject_handshake#
Si está habilitado, los handshakes SSL en el bloque server serán rechazados.
Por ejemplo, en la siguiente configuración, los handshakes SSL con nombres de servidor distintos a example.com son rechazados:
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#
| |
Predeterminado |
|
stream, server |
Establece los tipos y tamaños de cachés que almacenan parámetros de sesión. Una caché puede ser de cualquiera de los siguientes tipos:
| el uso de una caché de sesión está estrictamente prohibido: Angie indica explícitamente al cliente que las sesiones no pueden reutilizarse. |
| el uso de una caché de sesión está suavemente deshabilitado: Angie indica al cliente que las sesiones pueden reutilizarse, pero en realidad no almacena parámetros de sesión en la caché. |
| una caché integrada en OpenSSL; usada solo por un proceso worker. El tamaño de la caché se especifica en sesiones. Si no se indica el tamaño, es igual a 20480 sesiones. El uso de la caché integrada puede causar fragmentación de memoria. |
| una caché compartida entre todos los procesos worker. El tamaño de la caché se especifica en bytes; un megabyte puede almacenar unas 4000 sesiones. Cada caché compartida debe tener un nombre arbitrario. Una caché con el mismo nombre puede usarse en varios servidores. También se usa para generar, almacenar y rotar periódicamente las claves de tickets de sesión TLS automáticamente, a menos que se configure explícitamente usando la directiva ssl_session_ticket_key. |
Ambos tipos de caché pueden usarse simultáneamente, por ejemplo:
ssl_session_cache builtin:1000 shared:SSL:10m;
pero usar solo la caché compartida sin la integrada debería ser más eficiente.
ssl_session_ticket_key#
Establece un archivo con la clave secreta usada para cifrar y descifrar tickets de sesión TLS. La directiva es necesaria si la misma clave debe compartirse entre múltiples servidores. Por defecto, se usa una clave generada aleatoriamente.
Si se especifican varias claves, solo la primera clave se usa para cifrar tickets de sesión TLS. Esto permite configurar la rotación de claves, por ejemplo:
ssl_session_ticket_key current.key;
ssl_session_ticket_key previous.key;
El archivo debe contener 80 o 48 bytes de datos aleatorios y puede crearse usando el siguiente comando:
$ openssl rand 80 > ticket.key
Dependiendo del tamaño del archivo, se usará AES256 (para claves de 80 bytes) o AES128 (para claves de 48 bytes) para el cifrado.
ssl_session_tickets#
Habilita o deshabilita la reanudación de sesión mediante tickets de sesión TLS.
ssl_session_timeout#
Especifica el tiempo durante el cual un cliente puede reutilizar los parámetros de sesión.
ssl_stapling#
Habilita o deshabilita el grapado de respuestas OCSP por parte del servidor. Ejemplo:
ssl_stapling on;
resolver 127.0.0.53;
Para que el grapado OCSP funcione, debe conocerse el certificado del emisor del certificado del servidor. Si el archivo ssl_certificate no contiene certificados intermedios, el certificado del emisor del certificado del servidor debe estar presente en el archivo ssl_trusted_certificate.
Advertencia
Para la resolución del nombre de host del respondedor OCSP, también debe especificarse la directiva resolver.
ssl_stapling_file#
Cuando se establece, la respuesta OCSP grapada se tomará del archivo especificado en lugar de consultar al respondedor OCSP especificado en el certificado del servidor.
El archivo debe estar en formato DER tal como lo produce el comando openssl ocsp.
ssl_stapling_responder#
Sobrescribe la URI del respondedor OCSP especificado en la extensión del certificado "Authority Information Access".
Solo se admiten respondedores OCSP con http://:
ssl_stapling_responder http://ocsp.example.com/;
ssl_stapling_verify#
Habilita o deshabilita la verificación de respuestas OCSP por parte del servidor.
Para que la verificación funcione, el certificado del emisor del certificado del servidor, el certificado raíz y todos los certificados intermedios deben configurarse como de confianza mediante la directiva ssl_trusted_certificate.
ssl_trusted_certificate#
Especifica un archivo con certificados CA de confianza en formato PEM utilizados para verificar certificados de cliente.
A diferencia del conjunto de certificados establecido por ssl_client_certificate, la lista de estos certificados no se enviará a los clientes.
ssl_verify_client#
| |
Predeterminado |
|
stream, server |
Habilita la verificación de certificados de cliente. El resultado de la verificación se almacena en la variable $ssl_client_verify. Si ocurre un error durante la verificación del certificado de cliente o el cliente no presenta el certificado requerido, la conexión se cierra.
| solicita el certificado de cliente y lo verifica si el certificado está presente. |
| solicita el certificado de cliente pero no requiere que esté firmado por un certificado CA de confianza. Está pensado para casos en los que un servicio externo a Angie realiza la verificación real del certificado. |
ssl_verify_depth#
Establece la profundidad de verificación en la cadena de certificados de cliente.
Variables integradas#
El módulo devuelve el protocolo seleccionado por ALPN durante el handshake SSL, o una cadena vacía en caso contrario. devuelve el nombre del cifrado usado en una conexión SSL establecida. devuelve la lista de cifrados admitidos por el cliente. Los cifrados conocidos se muestran por nombre, los desconocidos en hexadecimal, por ejemplo: Nota La variable está totalmente soportada solo al usar OpenSSL versión 1.0.2 o superior. Con versiones anteriores, la variable está disponible solo para sesiones nuevas y muestra únicamente los cifrados conocidos. devuelve el certificado de cliente en formato PEM para una conexión SSL establecida, con cada línea (excepto la primera) precedida por un carácter de tabulación. devuelve la huella digital SHA1 del certificado de cliente para una conexión SSL establecida. devuelve la cadena "issuer DN" del certificado de cliente para una conexión SSL establecida, según RFC 2253. devuelve el certificado de cliente en formato PEM para una conexión SSL establecida. devuelve la cadena "subject DN" del certificado de cliente para una conexión SSL establecida, según RFC 2253. devuelve el número de serie del certificado de cliente para una conexión SSL establecida. devuelve el algoritmo de firma del certificado de cliente para una conexión SSL establecida. Nota La variable solo es compatible al usar OpenSSL versión 3.5 o superior. Con versiones anteriores, el valor de la variable será una cadena vacía. Nota La variable está disponible solo para sesiones nuevas. devuelve la fecha de expiración del certificado de cliente. devuelve el número de días restantes hasta que expire el certificado de cliente. devuelve la fecha de inicio del certificado de cliente. devuelve el resultado de la verificación del certificado de cliente: devuelve la curva negociada usada en el proceso de intercambio de claves del handshake SSL. Las curvas conocidas se muestran por nombre, las desconocidas en hexadecimal, por ejemplo: Nota La variable solo es compatible al usar OpenSSL versión 3.0 o superior. Con versiones anteriores, el valor de la variable será una cadena vacía. devuelve la lista de curvas admitidas por el cliente. Las curvas conocidas se muestran por nombre, las desconocidas en hexadecimal, por ejemplo: Nota La variable es compatible únicamente al usar OpenSSL versión 1.0.2 o superior. Con versiones anteriores, el valor de la variable será una cadena vacía. Nota La variable está disponible solo para sesiones nuevas. devuelve "1" si se usa early data de TLS 1.3 y el handshake no está completo; en caso contrario devuelve "". Added in version 1.11.0. devuelve "1" si el devuelve el protocolo de una conexión SSL establecida. toma los valores devuelve el nombre de servidor solicitado mediante SNI. devuelve el identificador de sesión de una conexión SSL establecida. devuelve "r" si una sesión SSL fue reutilizada, o "." en caso contrario. devuelve el algoritmo de firma del certificado de servidor para una conexión SSL establecida. Nota La variable solo es compatible al usar OpenSSL versión 3.5 o superior. Con versiones anteriores, el valor de la variable será una cadena vacía. Nota La variable está disponible solo para sesiones nuevas. devuelve la lista de algoritmos de firma ofrecidos por el cliente durante el handshake SSL, como una lista separada por dos puntos. Nota Con OpenSSL versión 4.0 o superior, los algoritmos se devuelven por nombre; un algoritmo sin nombre recurre a su código hexadecimal sin procesar. Las bibliotecas SSL que exponen la API de algoritmos de firma más antigua devuelven todos los algoritmos como códigos hexadecimales sin procesar. Las compilaciones sin una API de algoritmos de firma compatible devuelven un valor vacío.stream_ssl admite las siguientes variables:$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 y NONE si no se presentó certificado.$ssl_curve#prime256v1
$ssl_curves#0x001d:prime256v1:secp521r1:secp384r1
$ssl_early_data#$ssl_encrypted_hello#ClientHello se descifró mediante la extensión TLS
Encrypted Client Hello (ECH), de lo contrario "".$ssl_protocol#$ssl_server_cert_type#RSA, DSA, ECDSA, ED448, ED25519, SM2, RSA-PSS o unknown según el tipo de certificado y clave del servidor.$ssl_server_name#$ssl_session_id#$ssl_session_reused#$ssl_sigalg#$ssl_sigalgs#
Contenido