<!-- review: finished -->

<a id="http-ssl"></a>

# SSL

Proporciona el soporte necesario para HTTPS.

Al [compilar desde el código fuente](https://es.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild),
este módulo no se compila por defecto;
debe habilitarse con la
[opción de compilación](https://es.angie.software//angie/docs/installation/sourcebuild.md#configure)
`‑‑with‑http_ssl_module`.

En paquetes e imágenes de [nuestros repositorios](https://es.angie.software//angie/docs/installation/index.md#install-packages),
el módulo está incluido en la compilación.

#### NOTE
Este módulo requiere la biblioteca OpenSSL.

<a id="configuration-example-42"></a>

## Ejemplo de configuración

Para reducir la carga del procesador se recomienda

* establecer el número de [procesos worker](https://es.angie.software//angie/docs/configuration/modules/core.md#worker-processes) igual al número de procesadores,
* habilitar las conexiones [keep-alive](https://es.angie.software//angie/docs/configuration/modules/http/index.md#keepalive-timeout),
* habilitar la caché de sesión [compartida](#ssl-session-cache),
* deshabilitar la caché de sesión [integrada](#ssl-session-cache),
* y posiblemente aumentar la [duración](#ssl-session-timeout) de la sesión (por defecto, 5 minutos):

```nginx
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;

        # ...
    }
```

<a id="directives-45"></a>

## Directivas

<a id="index-0"></a>

<a id="ssl-buffer-size"></a>

### ssl_buffer_size

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_buffer_size` tamaño;   |
|--------------------------------------------------------------------------------------------|-----------------------------|
| Predeterminado                                                                             | `ssl_buffer_size 16k;`      |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server                |

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:

```nginx
ssl_buffer_size 4k;
```

<a id="index-1"></a>

<a id="ssl-certificate"></a>

### ssl_certificate

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_certificate` archivo;   |
|--------------------------------------------------------------------------------------------|------------------------------|
| Predeterminado                                                                             | —                            |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server                 |

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:

```nginx
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.

#### NOTE
Se pueden usar variables en el nombre del archivo cuando se usa OpenSSL 1.0.2 o superior:

```nginx
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 del 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](https://es.angie.software//angie/docs/configuration/modules/core.md#error-log).

#### NOTE
> 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](https://es.angie.software//angie/docs/configuration/ssl.md#https-separate-ips).

Si [ssl_ntls](#ssl-ntls) está habilitado, la directiva puede aceptar dos argumentos
(las partes de firma y cifrado del certificado)
en lugar de uno:

```nginx
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;
```

<a id="index-2"></a>

<a id="ssl-certificate-cache"></a>

### ssl_certificate_cache

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_certificate_cache` `off`;<br/><br/>`ssl_certificate_cache` `max=`N [`inactive=`tiempo] [`valid=`tiempo];   |
|--------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------|
| Predeterminado                                                                             | `ssl_certificate_cache off;`                                                                                    |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server                                                                                                    |

Define una caché que almacena [certificados SSL](#ssl-certificate) y [claves secretas](#ssl-certificate-key) 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:

```nginx
ssl_certificate       $ssl_server_name.crt;
ssl_certificate_key   $ssl_server_name.key;
ssl_certificate_cache max=1000 inactive=20s valid=1m;
```

<a id="index-3"></a>

<a id="ssl-certificate-compression"></a>

### ssl_certificate_compression

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_certificate_compression` `on` | `off`;   |
|--------------------------------------------------------------------------------------------|-----------------------------------------------|
| Predeterminado                                                                             | `ssl_certificate_compression off;`            |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server                                  |

Habilita la [compresión](https://datatracker.ietf.org/doc/html/rfc8879) TLS 1.3 de certificados de servidor.

#### NOTE
La directiva es compatible cuando se utiliza OpenSSL 3.2 o superior; la lista de algoritmos de compresión compatibles es proporcionada por la biblioteca.

#### NOTE
La directiva es compatible cuando se utiliza [BoringSSL](https://boringssl.googlesource.com/boringssl/); la lista de algoritmos de compresión compatibles incluye `zlib`.

Si [ssl_stapling](#ssl-stapling) está habilitado, la compresión de certificados se desactiva.

<a id="index-4"></a>

<a id="ssl-certificate-key"></a>

### ssl_certificate_key

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_certificate_key` archivo;   |
|--------------------------------------------------------------------------------------------|----------------------------------|
| Predeterminado                                                                             | —                                |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server                     |

Especifica un archivo con la clave secreta en formato PEM para el servidor virtual dado.

#### NOTE
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 `store:scheme:id` puede especificarse en lugar del archivo, que se utiliza para cargar una clave secreta con un id específico y un URI scheme registrado del proveedor OpenSSL, como [pkcs11](https://datatracker.ietf.org/doc/html/rfc7512).

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](https://es.angie.software//angie/docs/configuration/modules/core.md#error-log).

> Si [ssl_ntls](#ssl-ntls) está habilitado, la directiva puede aceptar dos argumentos
> (las partes de firma y cifrado de la clave)
> en lugar de uno:

> ```nginx
> 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;
> ```

<a id="index-5"></a>

<a id="ssl-ciphers"></a>

### ssl_ciphers

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ciphers` cifrados;         |
|--------------------------------------------------------------------------------------------|---------------------------------|
| Predeterminado                                                                             | `ssl_ciphers HIGH:!aNULL:!MD5;` |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server                    |

Especifica los cifrados habilitados. Los cifrados se especifican en el formato entendido por la biblioteca OpenSSL, por ejemplo:

```nginx
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`.

#### WARNING
La directiva `ssl_ciphers` *no* configura cifrados para TLS
1.3 cuando se usa OpenSSL. Para configurar los cifrados TLS 1.3 con OpenSSL, use la
directiva [ssl_conf_command](#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.

<a id="index-6"></a>

<a id="ssl-client-certificate"></a>

### ssl_client_certificate

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_client_certificate` archivo;   |
|--------------------------------------------------------------------------------------------|-------------------------------------|
| Predeterminado                                                                             | —                                   |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server                        |

Especifica un archivo con certificados de CA de confianza en formato PEM utilizados para
[verificar](#ssl-verify-client) certificados de cliente y respuestas OCSP si
[ssl_stapling](#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-trusted-certificate).

<a id="index-7"></a>

<a id="ssl-conf-command"></a>

### ssl_conf_command

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_conf_command` nombre valor;   |
|--------------------------------------------------------------------------------------------|------------------------------------|
| Predeterminado                                                                             | —                                  |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server                       |

Establece [comandos de configuración](https://docs.openssl.org/master/man3/SSL_CONF_cmd/) OpenSSL arbitrarios.

#### NOTE
La directiva es compatible cuando se utiliza OpenSSL 1.0.2 o superior.
Para configurar cifrados TLS 1.3 con OpenSSL, utilice el comando `Ciphersuites`.

Se pueden especificar varias directivas ssl_conf_command en el mismo nivel:

```nginx
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.

#### WARNING
Configurar OpenSSL directamente podría resultar en un comportamiento inesperado.

<a id="index-8"></a>

<a id="ssl-crl"></a>

### ssl_crl

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_crl` file;   |
|--------------------------------------------------------------------------------------------|-------------------|
| Predeterminado                                                                             | —                 |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server      |

Especifica un archivo con certificados revocados (CRL) en formato PEM utilizado para [verificar](#ssl-verify-client) certificados de cliente.

<a id="index-9"></a>

<a id="ssl-dhparam"></a>

### ssl_dhparam

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_dhparam` file;   |
|--------------------------------------------------------------------------------------------|-----------------------|
| Predeterminado                                                                             | —                     |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server          |

Especifica un archivo con parámetros DH para cifrados DHE.

#### WARNING
Por defecto no se establecen parámetros, y por lo tanto los cifrados DHE no se utilizarán.

<a id="index-10"></a>

<a id="ssl-early-data"></a>

### ssl_early_data

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_early_data` `on` | `off`;   |
|--------------------------------------------------------------------------------------------|----------------------------------|
| Predeterminado                                                                             | `ssl_early_data off;`            |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server                     |

Habilita o deshabilita TLS 1.3 [early data](https://datatracker.ietf.org/doc/html/rfc8446#section-2.3).

Las solicitudes enviadas dentro de early data están sujetas a [ataques de reproducción](https://datatracker.ietf.org/doc/html/rfc8470). Para proteger contra tales ataques a nivel de la aplicación, se debe utilizar la variable [$ssl_early_data](#v-ssl-early-data).

```nginx
proxy_set_header Early-Data $ssl_early_data;
```

#### NOTE
La directiva es compatible cuando se utiliza OpenSSL 1.1.1 o superior o [BoringSSL](https://boringssl.googlesource.com/boringssl/).

<a id="index-11"></a>

<a id="ssl-encrypted-hello-key"></a>

### ssl_encrypted_hello_key

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_encrypted_hello_key` file;   |
|--------------------------------------------------------------------------------------------|-----------------------------------|
| Predeterminado                                                                             | —                                 |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server                      |

Especifica un archivo con una clave privada ECH y ECHConfigList en formato PEM.
La directiva puede especificarse múltiples veces.
Requiere una compilación de OpenSSL o BoringSSL con soporte para Encrypted Client Hello (ECH);
de lo contrario no es compatible.

<a id="index-12"></a>

<a id="ssl-ecdh-curve"></a>

### ssl_ecdh_curve

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ecdh_curve` curve;   |
|--------------------------------------------------------------------------------------------|---------------------------|
| Predeterminado                                                                             | `ssl_ecdh_curve auto;`    |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server              |

Especifica una curva para cifrados ECDHE.

#### NOTE
Cuando se utiliza OpenSSL 1.0.2 o superior, es posible especificar múltiples curvas, por ejemplo:

```nginx
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.

#### NOTE
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.

<a id="index-13"></a>

<a id="ssl-ntls"></a>

### ssl_ntls

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ntls` `on` | `off`;   |
|--------------------------------------------------------------------------------------------|----------------------------|
| Predeterminado                                                                             | `ssl_ntls off;`            |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server               |

Habilita el soporte del lado del servidor para NTLS cuando se utiliza la biblioteca TLS [TongSuo](https://github.com/Tongsuo-Project/Tongsuo).

```nginx
listen ... ssl;
ssl_ntls  on;
```

#### NOTE
Angie debe compilarse con el parámetro de configuración `--with-ntls`, con la biblioteca SSL correspondiente con soporte NTLS

```default
./configure --with-openssl=../Tongsuo-8.3.0 \
            --with-openssl-opt=enable-ntls  \
            --with-ntls
```

<a id="index-14"></a>

<a id="ssl-ocsp"></a>

### ssl_ocsp

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ocsp` `on` | `off` | `leaf`;   |
|--------------------------------------------------------------------------------------------|-------------------------------------|
| Predeterminado                                                                             | `ssl_ocsp off;`                     |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server                        |

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](#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](https://es.angie.software//angie/docs/configuration/modules/http/index.md#resolver).

Ejemplo:

```nginx
ssl_verify_client on;
ssl_ocsp          on;
resolver          127.0.0.53;
```

<a id="index-15"></a>

<a id="ssl-ocsp-cache"></a>

### ssl_ocsp_cache

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ocsp_cache` `off` | [shared:name:size];   |
|--------------------------------------------------------------------------------------------|------------------------------------------------|
| Predeterminado                                                                             | `ssl_ocsp_cache off;`                          |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server                                   |

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é.

<a id="index-16"></a>

<a id="ssl-ocsp-responder"></a>

### ssl_ocsp_responder

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ocsp_responder` uri;   |
|--------------------------------------------------------------------------------------------|-----------------------------|
| Predeterminado                                                                             | —                           |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server                |

Anula el URI del respondedor OCSP especificado en la extensión del certificado ["Authority Information Access"](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.2.1) para la [validación](#ssl-ocsp) de certificados de cliente.

Solo se admiten respondedores OCSP `http://`:

```nginx
ssl_ocsp_responder http://ocsp.example.com/;
```

<a id="index-17"></a>

<a id="ssl-password-file"></a>

### ssl_password_file

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_password_file` file;   |
|--------------------------------------------------------------------------------------------|-----------------------------|
| Predeterminado                                                                             | —                           |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server                |

Especifica un archivo con frases de contraseña para [claves secretas](#ssl-certificate-key) 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:

```nginx
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;
    }
}
```

<a id="index-18"></a>

<a id="ssl-prefer-server-ciphers"></a>

### ssl_prefer_server_ciphers

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_prefer_server_ciphers` `on` | `off`;   |
|--------------------------------------------------------------------------------------------|---------------------------------------------|
| Predeterminado                                                                             | `ssl_prefer_server_ciphers off;`            |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server                                |

Especifica que los cifrados del servidor deben ser preferidos sobre los cifrados del cliente cuando se utilizan los protocolos SSLv3 y TLS.

<a id="index-19"></a>

<a id="ssl-protocols"></a>

### ssl_protocols

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_protocols` [`SSLv2`] [`SSLv3`] [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`];   |
|--------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
| Predeterminado                                                                             | `ssl_protocols TLSv1.2 TLSv1.3;`                                                     |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server                                                                         |

#### Versionchanged
Distinto en la versión 1.2.0: El parámetro `TLSv1.3` fue añadido al conjunto predeterminado.

Habilita los protocolos especificados.

#### NOTE
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.

<a id="index-20"></a>

<a id="ssl-reject-handshake"></a>

### ssl_reject_handshake

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_reject_handshake` `on` | `off`;   |
|--------------------------------------------------------------------------------------------|----------------------------------------|
| Predeterminado                                                                             | `ssl_reject_handshake off;`            |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server                           |

Si está habilitado, los handshakes SSL en el bloque [server](https://es.angie.software//angie/docs/configuration/modules/http/index.md#server) serán rechazados.

Por ejemplo, en la siguiente configuración, los handshakes SSL con nombres de servidor distintos a example.com son rechazados:

```nginx
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;
}
```

<a id="index-21"></a>

<a id="ssl-session-cache"></a>

### ssl_session_cache

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_cache` `off` | `none` | [builtin[:tamaño]] [shared:nombre:tamaño];   |
|--------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------|
| Predeterminado                                                                             | `ssl_session_cache none;`                                                         |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | 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:

| `off`     | 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.                                                                                                                                                                                                                                                                                                                                                                                                |
|-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `none`    | 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é.                                                                                                                                                                                                                                                                                                                                                |
| `builtin` | 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.                                                                                                                                                                                                                                                                                       |
| `shared`  | 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](#ssl-session-ticket-key). |

Ambos tipos de caché pueden ser utilizados simultáneamente, por ejemplo:

```nginx
ssl_session_cache builtin:1000 shared:SSL:10m;
```

pero usar solo la caché compartida sin la caché integrada debería ser más eficiente.

<a id="index-22"></a>

<a id="ssl-session-ticket-key"></a>

### ssl_session_ticket_key

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_ticket_key` archivo;   |
|--------------------------------------------------------------------------------------------|-------------------------------------|
| Predeterminado                                                                             | —                                   |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server                        |

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:

```nginx
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:

```console
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.

<a id="index-23"></a>

<a id="ssl-session-tickets"></a>

### ssl_session_tickets

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_tickets` `on` | `off`;   |
|--------------------------------------------------------------------------------------------|---------------------------------------|
| Predeterminado                                                                             | `ssl_session_tickets on;`             |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server                          |

Habilita o deshabilita la reanudación de sesión a través de [tickets de sesión TLS](https://datatracker.ietf.org/doc/html/rfc5077).

<a id="index-24"></a>

<a id="ssl-session-timeout"></a>

### ssl_session_timeout

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_session_timeout` tiempo;   |
|--------------------------------------------------------------------------------------------|---------------------------------|
| Predeterminado                                                                             | `ssl_session_timeout 5m;`       |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server                    |

Especifica un tiempo durante el cual un cliente puede reutilizar los parámetros de sesión.

<a id="index-25"></a>

<a id="ssl-stapling"></a>

### ssl_stapling

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_stapling` `on` | `off`;   |
|--------------------------------------------------------------------------------------------|--------------------------------|
| Predeterminado                                                                             | `ssl_stapling off;`            |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server                   |

Habilita o deshabilita el [grapado de respuestas OCSP](https://datatracker.ietf.org/doc/html/rfc6066#section-8) por el servidor. Ejemplo:

```nginx
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](#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](#ssl-trusted-certificate).

#### WARNING
Para la resolución del nombre de host del respondedor OCSP, también debe especificarse la directiva [resolver](https://es.angie.software//angie/docs/configuration/modules/http/index.md#resolver).

<a id="index-26"></a>

<a id="ssl-stapling-file"></a>

### ssl_stapling_file

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_stapling_file` archivo;   |
|--------------------------------------------------------------------------------------------|--------------------------------|
| Predeterminado                                                                             | —                              |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server                   |

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`.

<a id="index-27"></a>

<a id="ssl-stapling-responder"></a>

### ssl_stapling_responder

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_stapling_responder` `uri`;   |
|--------------------------------------------------------------------------------------------|-----------------------------------|
| Predeterminado                                                                             | —                                 |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server                      |

Sobrescribe la URI del respondedor OCSP especificada en la extensión de certificado ["Authority Information Access"](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.2.1).

Solo se admiten respondedores OCSP `http://`:

```nginx
ssl_stapling_responder http://ocsp.example.com/;
```

<a id="index-28"></a>

<a id="ssl-stapling-verify"></a>

### ssl_stapling_verify

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_stapling_verify` `on` | `off`;   |
|--------------------------------------------------------------------------------------------|---------------------------------------|
| Predeterminado                                                                             | `ssl_stapling_verify off;`            |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server                          |

Habilita o deshabilita la verificación de respuestas 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).

<a id="index-29"></a>

<a id="ssl-trusted-certificate"></a>

### ssl_trusted_certificate

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_trusted_certificate` archivo;   |
|--------------------------------------------------------------------------------------------|--------------------------------------|
| Predeterminado                                                                             | —                                    |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server                         |

Especifica un archivo con certificados CA de confianza en formato PEM utilizados para [verificar](#ssl-verify-client) certificados de cliente y respuestas OCSP si [ssl_stapling](#ssl-stapling) está habilitado.

A diferencia del conjunto de certificados establecido por [ssl_client_certificate](#ssl-client-certificate), la lista de estos certificados no se enviará a los clientes.

<a id="index-30"></a>

<a id="ssl-verify-client"></a>

### ssl_verify_client

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_verify_client` `on` | `off` | `optional` | `optional_no_ca`;   |
|--------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
| Predeterminado                                                                             | `ssl_verify_client off;`                                            |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server                                                        |

Habilita la verificación de certificados de cliente. El resultado de la verificación se almacena en la variable [$ssl_client_verify](#v-ssl-client-verify).

| `optional`       | solicita el certificado del cliente y lo verifica si el certificado está presente.                                                                                                                                                   |
|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `optional_no_ca` | 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. |

<a id="index-31"></a>

<a id="ssl-verify-depth"></a>

### ssl_verify_depth

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_verify_depth` número;   |
|--------------------------------------------------------------------------------------------|------------------------------|
| Predeterminado                                                                             | `ssl_verify_depth 1;`        |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server                 |

Establece la profundidad de verificación en la cadena de certificados del cliente.

<a id="ssl-error-codes"></a>

## 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](https://es.angie.software//angie/docs/configuration/modules/http/index.md#error-page):

| `495`   | se ha producido un error durante la verificación del certificado del cliente;   |
|---------|---------------------------------------------------------------------------------|
| `496`   | un cliente no ha presentado el certificado requerido;                           |
| `497`   | 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](https://es.angie.software//angie/docs/configuration/modules/http/index.md#v-request-uri), [$uri](https://es.angie.software//angie/docs/configuration/modules/http/index.md#v-uri), [$args](https://es.angie.software//angie/docs/configuration/modules/http/index.md#v-args) y otras, están disponibles.

<a id="built-in-variables-12"></a>

## Variables integradas

El módulo http_ssl admite variables integradas:

<a id="v-ssl-alpn-protocol"></a>

### `$ssl_alpn_protocol`

devuelve el protocolo seleccionado por ALPN durante el handshake SSL, o una cadena vacía en caso contrario.

<a id="v-ssl-cipher"></a>

### `$ssl_cipher`

devuelve el nombre del cifrado utilizado para una conexión SSL establecida.

<a id="v-ssl-ciphers"></a>

### `$ssl_ciphers`

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

#### NOTE
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.

<a id="v-ssl-client-escaped-cert"></a>

### `$ssl_client_escaped_cert`

devuelve el certificado del cliente en formato PEM (codificado en URL) para una conexión SSL establecida.

<a id="v-ssl-client-fingerprint"></a>

### `$ssl_client_fingerprint`

devuelve la huella SHA1 del certificado del cliente para una conexión SSL establecida.

<a id="v-ssl-client-i-dn"></a>

### `$ssl_client_i_dn`

devuelve la cadena "issuer DN" del certificado del cliente para una conexión SSL establecida según [RFC 2253](https://datatracker.ietf.org/doc/html/rfc2253).

<a id="v-ssl-client-i-dn-legacy"></a>

### `$ssl_client_i_dn_legacy`

devuelve la cadena "issuer DN" del certificado del cliente para una conexión SSL establecida.

<a id="v-ssl-client-raw-cert"></a>

### `$ssl_client_raw_cert`

devuelve el certificado del cliente en formato PEM para una conexión SSL establecida.

<a id="v-ssl-client-s-dn"></a>

### `$ssl_client_s_dn`

devuelve la cadena "subject DN" del certificado del cliente para una conexión SSL establecida según [RFC 2253](https://datatracker.ietf.org/doc/html/rfc2253).

<a id="v-ssl-client-s-dn-legacy"></a>

### `$ssl_client_s_dn_legacy`

devuelve la cadena "subject DN" del certificado del cliente para una conexión SSL establecida.

<a id="v-ssl-client-serial"></a>

### `$ssl_client_serial`

devuelve el número de serie del certificado del cliente para una conexión SSL establecida.

<a id="v-ssl-client-sigalg"></a>

### `$ssl_client_sigalg`

devuelve el [algoritmo de firma](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16) del certificado del cliente para una conexión SSL establecida.

#### NOTE
La variable solo es compatible cuando se utiliza OpenSSL versión 3.5 o superior. Con versiones anteriores, el valor de la variable será una cadena vacía.

#### NOTE
La variable solo está disponible para nuevas sesiones.

<a id="v-ssl-client-v-end"></a>

### `$ssl_client_v_end`

devuelve la fecha de finalización del certificado del cliente.

<a id="v-ssl-client-v-remain"></a>

### `$ssl_client_v_remain`

devuelve el número de días hasta que caduque el certificado del cliente.

<a id="v-ssl-client-v-start"></a>

### `$ssl_client_v_start`

devuelve la fecha de inicio del certificado del cliente.

<a id="v-ssl-client-verify"></a>

### `$ssl_client_verify`

devuelve el resultado de la verificación del certificado del cliente: `SUCCESS`, `FAILED:reason`, y `NONE` si no se presentó un certificado.

<a id="v-ssl-curve"></a>

### `$ssl_curve`

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

#### NOTE
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.

<a id="v-ssl-curves"></a>

### `$ssl_curves`

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

#### NOTE
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.

<a id="v-ssl-early-data"></a>

### `$ssl_early_data`

devuelve "1" si se utilizan [datos tempranos](#ssl-early-data) de TLS 1.3 y el handshake no está completo, de lo contrario "".

<a id="v-ssl-encrypted-hello"></a>

### `$ssl_encrypted_hello`

devuelve "1" si se utiliza Encrypted Client Hello (ECH), de lo contrario "".

<a id="v-ssl-protocol"></a>

### `$ssl_protocol`

devuelve el protocolo de una conexión SSL establecida.

<a id="v-ssl-server-cert-type"></a>

### `$ssl_server_cert_type`

toma los valores `RSA`, `DSA`, `ECDSA`, `ED448`,
`ED25519`, `SM2`, `RSA-PSS`, o `unknown` dependiendo
del tipo de certificado y clave del servidor.

<a id="v-ssl-server-name"></a>

### `$ssl_server_name`

devuelve el nombre del servidor solicitado a través de [SNI](http://en.wikipedia.org/wiki/Server_Name_Indication).

<a id="v-ssl-session-id"></a>

### `$ssl_session_id`

devuelve el identificador de sesión de una conexión SSL establecida.

<a id="v-ssl-session-reused"></a>

### `$ssl_session_reused`

devuelve "r" si se reutilizó una sesión SSL, o "." en caso contrario.

<a id="v-ssl-sigalg"></a>

### `$ssl_sigalg`

devuelve el [algoritmo de firma](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16) del certificado del servidor para una conexión SSL establecida.

#### NOTE
La variable solo es compatible cuando se utiliza OpenSSL versión 3.5 o superior. Con versiones anteriores, el valor de la variable será una cadena vacía.

#### NOTE
La variable solo está disponible para nuevas sesiones.