SSL#
Proporciona el soporte necesario para HTTPS.
Al compilar desde el código fuente,
este módulo no se compila por defecto;
debe habilitarse con la
opción de compilación
‑‑with‑http_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 las conexiones keep-alive,
habilitar la caché de sesión compartida,
deshabilitar la caché de sesión integrada,
y posiblemente aumentar la duración de la sesión (por defecto, 5 minutos):
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;
# ...
}
Directivas#
ssl_buffer_size#
Establece el tamaño del búfer utilizado para enviar datos.
Por defecto, el tamaño del búfer es de 16k, lo que corresponde a una sobrecarga mínima al enviar respuestas grandes. Para minimizar el Time To First Byte puede ser beneficioso usar valores más pequeños, por ejemplo:
ssl_buffer_size 4k;
ssl_certificate#
Especifica un archivo con el certificado en formato PEM para el servidor virtual dado. Si se deben especificar certificados intermedios además de un certificado primario, deben especificarse en el mismo archivo en el siguiente orden: primero el certificado primario, luego los certificados intermedios. Una clave secreta en formato PEM puede colocarse en el mismo archivo.
Esta directiva puede especificarse varias veces para cargar certificados de diferentes tipos, por ejemplo, RSA y ECDSA:
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;
# ...
}
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 cuando se usa 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, y esto puede tener un impacto negativo en el rendimiento.
Se puede especificar el valor data:$variable en lugar de archivo, lo que carga un certificado desde una variable sin usar archivos intermedios. Tenga en cuenta que el uso inadecuado de esta sintaxis puede tener implicaciones de seguridad, como escribir datos de clave secreta en el registro de errores.
Nota
Debe tenerse en cuenta que debido a las limitaciones del protocolo HTTPS para máxima interoperabilidad, los servidores virtuales deben escuchar en diferentes direcciones IP.
Added in version 1.2.0: Si ssl_ntls está habilitado, la directiva puede aceptar dos argumentos (las partes de firma y cifrado del certificado) en lugar de uno:
listen ... ssl;
ssl_ntls on;
# certificado NTLS dual
ssl_certificate sign.crt enc.crt;
ssl_certificate_key sign.key enc.key;
# puede usarse junto con un certificado RSA regular
ssl_certificate rsa.crt;
ssl_certificate_key rsa.key;
ssl_certificate_cache#
| |
Predeterminado |
|
http, server |
Define una caché que almacena certificados SSL y claves secretas especificadas mediante 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 después del cual se elimina un elemento si no ha sido accedido. El valor predeterminado es 10 segundos.valid— define el tiempo durante el cual un elemento en caché se considera válido y puede ser reutilizado. El valor predeterminado es 60 segundos. Después de este período, los certificados se recargan o revalidan.off— desactiva la 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_key#
Especifica un archivo con la clave secreta en formato PEM para el servidor virtual dado.
Nota
Se pueden usar variables en el nombre del archivo cuando se usa OpenSSL 1.0.2 o superior.
El valor engine:name:id puede especificarse en lugar del archivo, lo que carga una clave secreta con un id específico desde el motor OpenSSL name.
El valor data:$variable puede especificarse en lugar del archivo, lo que carga una clave secreta desde una variable sin usar archivos intermedios. Tenga en cuenta que el uso inadecuado de esta sintaxis puede tener implicaciones de seguridad, como escribir datos de clave secreta en el registro de errores.
Added in version 1.2.0: Si ssl_ntls está habilitado, la directiva puede aceptar dos argumentos (las partes de firma y cifrado de la clave) en lugar de uno:
listen ... ssl;
ssl_ntls on;
# certificado NTLS dual
ssl_certificate sign.crt enc.crt;
ssl_certificate_key sign.key enc.key;
# puede usarse junto con un certificado RSA regular
ssl_certificate rsa.crt;
ssl_certificate_key rsa.key;
ssl_ciphers#
Especifica los cifrados habilitados. Los cifrados se especifican en el formato entendido por la 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 se puede ver usando el comando openssl ciphers.
Advertencia
La directiva ssl_ciphers no configura cifrados para TLS
1.3 cuando se usa OpenSSL. Para ajustar los cifrados TLS 1.3 con OpenSSL, use la
directiva ssl_conf_command, que se agregó para admitir configuración
SSL avanzada.
En LibreSSL, los cifrados TLS 1.3 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 de confianza en formato PEM utilizados para verificar certificados de cliente y respuestas OCSP si ssl_stapling está habilitado.
La lista de certificados se enviará a los clientes. Si esto no es deseable, se puede usar la directiva ssl_trusted_certificate.
ssl_conf_command#
Establece comandos de configuración OpenSSL arbitrarios.
Nota
La directiva es compatible cuando se usa 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 si y solo si no hay directivas ssl_conf_command definidas en el nivel actual.
Advertencia
Configurar OpenSSL directamente podría resultar en un comportamiento inesperado.
ssl_crl#
Especifica un archivo con certificados revocados (CRL) en formato PEM utilizado para verificar certificados de cliente.
ssl_dhparam#
Especifica un archivo con parámetros DH para cifrados DHE.
Por defecto no se establecen parámetros, y por lo tanto los cifrados DHE no se utilizarán.
ssl_early_data#
Habilita o deshabilita TLS 1.3 early data.
Las solicitudes enviadas dentro de early data están sujetas a ataques de reproducción. Para proteger contra tales ataques a nivel de la aplicación, se debe utilizar la variable $ssl_early_data.
proxy_set_header Early-Data $ssl_early_data;
Nota
La directiva es compatible cuando se utiliza OpenSSL 1.1.1 o superior o BoringSSL.
ssl_ecdh_curve#
Especifica una curva para cifrados ECDHE.
Nota
Cuando se utiliza OpenSSL 1.0.2 o superior, es posible especificar múltiples curvas, por ejemplo:
ssl_ecdh_curve prime256v1:secp384r1;
El valor especial auto corresponde a la lista de curvas integradas en la biblioteca OpenSSL para OpenSSL 1.0.2 o superior, o prime256v1 para versiones anteriores.
Nota
Cuando se utiliza OpenSSL 1.0.2 o superior, esta directiva establece la lista de curvas soportadas por el servidor. Por lo tanto, para que los certificados ECDSA funcionen, es importante incluir las curvas utilizadas en los certificados.
ssl_ntls#
Added in version 1.2.0.
Habilita el soporte del lado del servidor para NTLS cuando se utiliza la biblioteca TLS TongSuo.
listen ... ssl;
ssl_ntls on;
Nota
Angie debe compilarse con el parámetro de configuración --with-ntls, con la biblioteca SSL correspondiente 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 solo del certificado del cliente.
Para que la validación OCSP funcione, la directiva ssl_verify_client debe establecerse 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#
Establece el nombre y tamaño de la caché que almacena el estado del certificado del cliente para la validación OCSP. La caché se comparte entre todos los procesos de trabajo. Una caché con el mismo nombre puede utilizarse en varios servidores virtuales.
El parámetro off prohíbe el uso de la caché.
ssl_ocsp_responder#
Anula el 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 http://:
ssl_ocsp_responder http://ocsp.example.com/;
ssl_password_file#
Especifica un archivo con frases de contraseña para claves secretas donde cada frase de contraseña se especifica en una línea separada. Las frases de contraseña se prueban sucesivamente al cargar la clave.
Ejemplo:
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;
# también se puede usar una tubería con nombre en lugar de un archivo
ssl_password_file /etc/keys/fifo;
ssl_certificate_key /etc/keys/second.key;
}
}
ssl_prefer_server_ciphers#
| |
Predeterminado |
|
http, server |
Especifica que los cifrados del servidor deben ser preferidos sobre los cifrados del cliente cuando se utilizan los protocolos SSLv3 y TLS.
ssl_protocols#
| |
Predeterminado |
|
http, server |
Distinto en la versión 1.2.0: El parámetro TLSv1.3 fue añadido al conjunto predeterminado.
Habilita los protocolos especificados.
Nota
Los parámetros TLSv1.1 y TLSv1.2 solo funcionan cuando se utiliza OpenSSL 1.0.1 o superior.
El parámetro TLSv1.3 solo funciona cuando se utiliza 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 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;
}
ssl_session_cache#
| |
Predeterminado |
|
http, 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 explícitamente le dice al cliente que las sesiones no pueden ser reutilizadas. |
| el uso de una caché de sesión está suavemente deshabilitado: Angie le dice al cliente que las sesiones pueden ser reutilizadas, pero no almacena realmente los parámetros de sesión en la caché. |
| una caché integrada en OpenSSL; utilizada por un solo proceso de trabajo. El tamaño de la caché se especifica en sesiones. Si no se proporciona 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 de trabajo. El tamaño de la caché se especifica en bytes; un megabyte puede almacenar aproximadamente 4000 sesiones. Cada caché compartida debe tener un nombre arbitrario. Una caché con el mismo nombre puede ser utilizada en varios servidores virtuales. También se utiliza para generar automáticamente, almacenar y rotar periódicamente las claves de ticket de sesión TLS a menos que se configure explícitamente usando la directiva ssl_session_ticket_key. |
Ambos tipos de caché pueden ser utilizados simultáneamente, por ejemplo:
ssl_session_cache builtin:1000 shared:SSL:10m;
pero usar solo la caché compartida sin la caché integrada debería ser más eficiente.
ssl_session_ticket_key#
Establece un archivo con la clave secreta utilizada para cifrar y descifrar tickets de sesión TLS. La directiva es necesaria si la misma clave necesita ser compartida entre múltiples servidores. Por defecto, se utiliza una clave generada aleatoriamente.
Si se especifican varias claves, solo la primera clave se utiliza 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 utilizando el siguiente comando:
openssl rand 80 > ticket.key
Dependiendo del tamaño del archivo, se utilizará 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 a través de tickets de sesión TLS.
ssl_session_timeout#
Especifica un 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 el servidor. Ejemplo:
ssl_stapling on;
resolver 127.0.0.53;
Para que el grapado OCSP funcione, el certificado del emisor del certificado del servidor debe ser conocido. Si el archivo ssl_certificate no contiene certificados intermedios, el certificado del emisor del certificado del servidor debe estar presente en el archivo especificado por la directiva 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#
Overrides the URI of the OCSP responder specified in the "Authority Information Access" certificate extension.
Only http:// OCSP responders are supported:
ssl_stapling_responder http://ocsp.example.com/;
ssl_stapling_verify#
Habilita o deshabilita la verificación de OCSP por el 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 confiables utilizando 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 y respuestas OCSP si ssl_stapling está habilitado.
A diferencia del certificado establecido por ssl_client_certificate, la lista de estos certificados no se enviará a los clientes.
ssl_verify_client#
| |
Predeterminado |
|
http, server |
Habilita la verificación de certificados de cliente. El resultado de la verificación se almacena en la variable $ssl_client_verify.
| solicita el certificado del cliente y lo verifica si el certificado está presente. |
| solicita el certificado del cliente pero no requiere que esté firmado por un certificado CA de confianza. Esto está destinado a usarse en 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 del cliente.
Procesamiento de Errores#
El módulo http_ssl admite varios códigos de error no estándar que pueden utilizarse para redirecciones mediante la directiva error_page:
| se ha producido un error durante la verificación del certificado del cliente; |
| un cliente no ha presentado el certificado requerido; |
| se ha enviado una solicitud normal al puerto HTTPS. |
La redirección ocurre después de que la solicitud se analiza completamente y las variables, como $request_uri, $uri, $args y otras, están disponibles.
Variables Integradas#
El módulo http_ssl admite variables integradas: devuelve el protocolo seleccionado por ALPN durante el handshake SSL, o una cadena vacía en caso contrario. devuelve el nombre del cifrado utilizado para una conexión SSL establecida. devuelve la lista de cifrados compatibles con el cliente. Los cifrados conocidos se enumeran por nombres, los desconocidos se muestran en hexadecimal, por ejemplo: AES128-SHA:AES256-SHA:0x00ff Nota La variable solo es totalmente compatible cuando se utiliza OpenSSL versión 1.0.2 o superior. Con versiones anteriores, la variable solo está disponible para nuevas sesiones y enumera únicamente los cifrados conocidos. devuelve el certificado del cliente en formato PEM (codificado en URL) para una conexión SSL establecida. devuelve la huella SHA1 del certificado del cliente para una conexión SSL establecida. devuelve la cadena "issuer DN" del certificado del cliente para una conexión SSL establecida según RFC 2253. devuelve la cadena "issuer DN" del certificado del cliente para una conexión SSL establecida. devuelve el certificado del cliente en formato PEM para una conexión SSL establecida. devuelve la cadena "subject DN" del certificado del cliente para una conexión SSL establecida según RFC 2253. devuelve la cadena "subject DN" del certificado del cliente para una conexión SSL establecida. devuelve el número de serie del certificado del cliente para una conexión SSL establecida. devuelve la fecha de finalización del certificado del cliente. devuelve el número de días hasta que caduque el certificado del cliente. devuelve la fecha de inicio del certificado del cliente. devuelve el resultado de la verificación del certificado del cliente: devuelve la curva negociada utilizada para el intercambio de claves durante el handshake SSL. Las curvas conocidas se enumeran por nombres, las desconocidas se muestran en hexadecimal, por ejemplo: prime256v1 Nota La variable solo es compatible cuando se utiliza 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 compatibles con el cliente. Las curvas conocidas se enumeran por nombres, las desconocidas se muestran en hexadecimal, por ejemplo: 0x001d:prime256v1:secp521r1:secp384r1 Nota La variable solo es compatible cuando se utiliza OpenSSL versión 1.0.2 o superior. Con versiones anteriores, el valor de la variable será una cadena vacía. La variable solo está disponible para nuevas sesiones. devuelve "1" si se utilizan datos tempranos de TLS 1.3 y el handshake no está completo, de lo contrario "". devuelve el protocolo de una conexión SSL establecida. toma los valores devuelve el nombre del servidor solicitado a través de SNI. devuelve el identificador de sesión de una conexión SSL establecida. devuelve $ssl_alpn_protocol#$ssl_cipher#$ssl_ciphers#$ssl_client_escaped_cert#$ssl_client_fingerprint#$ssl_client_i_dn#$ssl_client_i_dn_legacy#$ssl_client_raw_cert#$ssl_client_s_dn#$ssl_client_s_dn_legacy#$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ó un certificado.$ssl_curve#$ssl_curves#$ssl_early_data#$ssl_protocol#$ssl_server_cert_type#RSA, DSA, ECDSA, ED448,
ED25519, SM2, RSA-PSS, o unknown dependiendo
del tipo de certificado y clave del servidor.$ssl_server_name#$ssl_session_id#$ssl_session_reused#r si se reutilizó una sesión SSL, o "." en caso contrario.
Contenido