SSL#
Proporciona el soporte necesario para que un servidor proxy de stream funcione con el protocolo SSL/TLS.
Cuando se compila a partir del código fuente,
este módulo no se incluye de forma predeterminada;
debe habilitarse con la
opción de compilación --with-stream_ssl_module.
En los 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 sesiones compartida,
deshabilitar la caché de sesiones integrada,
y posiblemente aumentar el tiempo de vida de las sesiones (por defecto, 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;
# ...
}
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 un archivo con el certificado en formato PEM para el servidor dado. Si se deben especificar certificados intermedios además del certificado principal, deben incluirse en el mismo archivo en el siguiente orden: primero el certificado principal y luego los certificados intermedios. Una clave secreta en formato PEM también puede colocarse en el mismo archivo.
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;
# ...
}
Solo OpenSSL 1.0.2 o superior admite cadenas de certificados separadas para diferentes certificados. Con versiones anteriores, solo se puede usar una cadena de certificados.
Nota
Se pueden usar variables en el nombre del archivo al utilizar OpenSSL 1.0.2 o superior:
ssl_certificate $ssl_server_name.crt;
ssl_certificate_key $ssl_server_name.key;
Tenga en cuenta que el uso de variables implica que se cargará un certificado para cada handshake SSL, lo que puede tener un impacto negativo en el rendimiento.
En lugar de archivo, se puede especificar el valor data:`$variable`, que carga un certificado desde una variable sin utilizar archivos intermedios.
Tenga en cuenta que el uso inapropiado de esta sintaxis puede tener implicaciones de seguridad, como escribir datos de claves secretas en el registro de errores.
ssl_certificate_key#
Especifica un archivo con la clave secreta en formato PEM para el servidor dado.
Nota
Se pueden usar variables en el nombre del archivo al utilizar OpenSSL 1.0.2 o superior.
En lugar de archivo, se puede especificar el valor engine:`nombre`:id, que carga una clave secreta con un id determinado desde el motor OpenSSL nombre.
También se puede especificar el valor data:`$variable` en lugar de archivo, que carga una clave secreta desde una variable sin usar archivos intermedios.
Tenga en cuenta que el uso inapropiado de esta sintaxis puede tener implicaciones de seguridad, como escribir datos de claves secretas en el registro de errores.
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
La directiva ssl_ciphers no configura los cifrados para TLS 1.3 al usar OpenSSL.
Para ajustar los cifrados TLS 1.3 con OpenSSL, utilice la directiva ssl_conf_command, añadida para configuración SSL avanzada.
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.
Para configurar cifrados TLS 1.3 con OpenSSL, use el comando ciphersuites.
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 los cifrados ECDHE.
Nota
Al usar OpenSSL 1.0.2 o superior es posible especificar varias curvas, por ejemplo:
ssl_ecdh_curve prime256v1:secp384r1;
El valor especial auto indica a Angie que use la lista integrada en la biblioteca OpenSSL (si se usa OpenSSL 1.0.2 o superior) o prime256v1 con versiones anteriores.
Nota
Con 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_handshake_timeout#
Especifica un tiempo de espera para completar el handshake SSL.
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 especificado 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_ntls#
Added in version 1.2.0.
Habilita el soporte del lado del servidor para NTLS usando la biblioteca TongSuo.
listen ... ssl;
ssl_ntls on;
Nota
Angie debe compilarse con la opción de compilación --with-ntls y enlazarse con una biblioteca SSL que tenga soporte NTLS
./configure --with-openssl=../Tongsuo-8.3.0 \
--with-openssl-opt=enable-ntls \
--with-ntls
ssl_password_file#
Especifica un archivo con las contraseñas para las claves secretas, donde cada contraseña se indica 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 del cliente cuando se usan los protocolos SSLv3 y TLS.
ssl_protocols#
| |
Predeterminado |
|
stream, server |
Distinto en la versión 1.2.0: Se añadió el parámetro TLSv1.3 al conjunto predeterminado.
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_session_cache#
| |
Predeterminado |
|
stream, server |
Establece los tipos y tamaños de caché que almacenan los parámetros de sesión. Una caché puede ser de los siguientes tipos:
| el uso de la caché de sesión está estrictamente prohibido: Angie indica explícitamente al cliente que las sesiones no pueden reutilizarse. |
| el uso de la caché de sesión está suavemente deshabilitado: Angie indica al cliente que las sesiones pueden reutilizarse, pero en realidad no guarda 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, 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, salvo que se configure explícitamente mediante 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 varios servidores. De forma predeterminada, se usa una clave generada aleatoriamente.
Si se especifican varias claves, solo la primera se usa para cifrar los 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 con el siguiente comando:
openssl rand 80 > ticket.key
Dependiendo del tamaño del archivo, se usa 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 TLS session tickets.
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 stapling de respuestas OCSP por parte del servidor. Ejemplo:
ssl_stapling on;
resolver 127.0.0.53;
Para que el OCSP stapling funcione, debe conocerse el certificado del emisor del certificado del servidor. Si el archivo ssl_certificate no contiene certificados intermedios, el certificado del emisor debe estar presente en el archivo ssl_trusted_certificate.
Advertencia
Para resolver el nombre de host del respondedor OCSP, también debe especificarse la directiva resolver.
ssl_stapling_file#
Cuando se establece, la respuesta OCSP stapled se tomará del archivo especificado en lugar de consultar al respondedor OCSP indicado 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 usados para verificar certificados de cliente.
A diferencia del conjunto de certificados definido con ssl_client_certificate, esta lista 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 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#
Define 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 conocidos se muestran por nombre, los desconocidos en hexadecimal, por ejemplo: AES128-SHA:AES256-SHA:0x00ff 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 (emisor) 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 (sujeto) 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 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 de validez del certificado de cliente. devuelve el resultado de la verificación del certificado de cliente:
devuelve la curva negociada usada en el intercambio de claves durante el handshake SSL.
Las curvas conocidas se muestran por nombre, las desconocidas en hexadecimal, por ejemplo: prime256v1 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: 0x001d:prime256v1:secp521r1:secp384r1 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. 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 "". 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 stream_ssl admite las siguientes variables:$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 y NONE si no se presentó certificado.$ssl_curve#$ssl_curves#$ssl_early_data#$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#r si una sesión SSL fue reutilizada, o "." en caso contrario.
Contenido