<!-- review: finished -->

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

# SSL Configuration

To configure an HTTPS server, the [ssl](https://en.angie.software//angie/docs/configuration/modules/http/index.md#listen) parameter must be enabled
on listening sockets in the [server](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server) block, and the locations of the server
certificate and private key files should be specified:

```nginx
server {
    listen              443 ssl;
    server_name         www.example.com;
    ssl_certificate     www.example.com.crt;
    ssl_certificate_key www.example.com.key;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;
#...
}
```

The server certificate is a public entity. It is sent to every client that
connects to the server. The private key is a secure entity and should be stored
in a file with restricted access; however, it must be readable by Angie's
master process. The private key may alternately be stored in the same file as
the certificate.

```nginx
ssl_certificate     www.example.com.cert;
ssl_certificate_key www.example.com.cert;
```

In which case the file access rights should also be restricted. Although the
certificate and the key are stored in one file, only the certificate is sent to
a client.

The directives [ssl_protocols](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-protocols) and [ssl_ciphers](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-ciphers) can be used to limit
connections to include only the strong versions and ciphers of SSL/TLS. By
default, Angie uses:

```nginx
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
```

So configuring them explicitly is generally not needed.

<a id="https-optimization"></a>

## HTTPS Server Optimization

SSL operations consume extra CPU resources. On multi-processor systems, several
[worker processes](https://en.angie.software//angie/docs/configuration/modules/core.md#worker-processes) should be run, no less than the
number of available CPU cores. The most CPU-intensive operation is the SSL
handshake. There are two ways to minimize the number of these operations per
client: the first is by enabling [keepalive](https://en.angie.software//angie/docs/configuration/modules/http/index.md#keepalive-timeout)
connections to send several requests via one connection, and the second is to
reuse SSL session parameters to avoid SSL handshakes for parallel and subsequent
connections. The sessions are stored in an SSL session cache shared between
workers and configured by the [ssl_session_cache](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-session-cache) directive. One megabyte
of the cache contains about 4000 sessions. The default cache timeout is 5
minutes. It can be increased by using the [ssl_session_timeout](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-session-timeout) directive.
Here is a sample configuration optimized for a multi-core system with a
10-megabyte shared session cache:

```nginx
worker_processes auto;

http {
    ssl_session_cache   shared:SSL:10m;
    ssl_session_timeout 10m;

    server {
        listen              443 ssl;
        server_name         www.example.com;
        keepalive_timeout   70;

        ssl_certificate     www.example.com.crt;
        ssl_certificate_key www.example.com.key;
        ssl_protocols       TLSv1.2 TLSv1.3;
        ssl_ciphers         HIGH:!aNULL:!MD5;
    #...
```

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

## SSL Certificate Chains

Some browsers may complain about a certificate signed by a well-known
certificate authority, while other browsers may accept the certificate without
issues. This occurs because the issuing authority has signed the server
certificate using an intermediate certificate that is not present in the
certificate base of well-known trusted certificate authorities distributed with
a particular browser. In this case, the authority provides a bundle of chained
certificates which should be concatenated to the signed server certificate. The
server certificate must appear before the chained certificates in the combined
file:

```console
$ cat www.example.com.crt bundle.crt > www.example.com.chained.crt
```

The resulting file should be used with the [ssl_certificate](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-certificate) directive:

```nginx
server {
    listen              443 ssl;
    server_name         www.example.com;
    ssl_certificate     www.example.com.chained.crt;
    ssl_certificate_key www.example.com.key;
#...
}
```

If the server certificate and the bundle were concatenated in the wrong order,
Angie fails to start and displays an error message:

> SSL_CTX_use_PrivateKey_file(" ... /www.example.com.key") failed
> : (SSL: error:0B080074:x509 certificate routines:
>   X509_check_private_key:key values mismatch)

Because Angie tried to use the private key with the bundle's first
certificate instead of the server certificate.

Browsers usually store intermediate certificates that they receive, signed by
trusted authorities, so browsers that are actually used may already have the
required intermediate certificates and may not complain about a certificate
being sent without a chained bundle. To ensure the server sends the complete
certificate chain, the **openssl** command-line utility may be used, for
example:

```console
$ openssl s_client -connect www.godaddy.com:443

Certificate chain
 0 s:/C=US/ST=Arizona/L=Scottsdale/1.3.6.1.4.1.311.60.2.1.3=US
     /1.3.6.1.4.1.311.60.2.1.2=AZ/O=GoDaddy.com, Inc
     /OU=MIS Department/CN=www.GoDaddy.com
     /serialNumber=0796928-7/2.5.4.15=V1.0, Clause 5.(b)
   i:/C=US/ST=Arizona/L=Scottsdale/O=GoDaddy.com, Inc.
     /OU=http://certificates.godaddy.com/repository
     /CN=Go Daddy Secure Certification Authority
     /serialNumber=07969287
 1 s:/C=US/ST=Arizona/L=Scottsdale/O=GoDaddy.com, Inc.
     /OU=http://certificates.godaddy.com/repository
     /CN=Go Daddy Secure Certification Authority
     /serialNumber=07969287
   i:/C=US/O=The Go Daddy Group, Inc.
     /OU=Go Daddy Class 2 Certification Authority
 2 s:/C=US/O=The Go Daddy Group, Inc.
     /OU=Go Daddy Class 2 Certification Authority
   i:/L=ValiCert Validation Network/O=ValiCert, Inc.
     /OU=ValiCert Class 2 Policy Validation Authority
     /CN=http://www.valicert.com//emailAddress=info@valicert.com
```

In this example, the subject ("s") of the www.GoDaddy.com server certificate #0
is signed by an issuer ("i") which itself is the subject of the certificate #1,
which is signed by an issuer which itself is the subject of the certificate #2,
which is signed by the well-known issuer ValiCert, Inc. whose certificate is
stored in the browsers' built-in certificate base.

If a certificate bundle has not been added, only the server certificate #0 will
be shown.

<a id="compact-server"></a>

## A Single HTTP/HTTPS Server

It is possible to configure a single server that handles both HTTP and HTTPS
requests:

```nginx
server {
    listen              80;
    listen              443 ssl;
    server_name         www.example.com;
    ssl_certificate     www.example.com.crt;
    ssl_certificate_key www.example.com.key;
#...
}
```

<a id="name-based-https-servers"></a>

## Name-Based HTTPS Servers

A common issue arises when configuring two or more HTTPS servers listening on a
single IP address:

```nginx
server {
    listen          443 ssl;
    server_name     www.example.com;
    ssl_certificate www.example.com.crt;
#...
}

server {
    listen          443 ssl;
    server_name     www.example.org;
    ssl_certificate www.example.org.crt;
#...
}
```

With this configuration, a browser receives the default server's certificate,
i.e. www.example.com, regardless of the requested server name. This is caused
by SSL protocol behavior. The SSL connection is established before the browser
sends an HTTP request, and Angie does not know the name of the requested
server. Therefore, it may only offer the default server's certificate.

<a id="https-separate-ips"></a>

The oldest and most robust method to resolve the issue is to assign a separate
IP address for every HTTPS server:

```nginx
server {
    listen          192.168.1.1:443 ssl;
    server_name     www.example.com;
    ssl_certificate www.example.com.crt;
#...
}

server {
    listen          192.168.1.2:443 ssl;
    server_name     www.example.org;
    ssl_certificate www.example.org.crt;
#...
}
```

<a id="an-ssl-certificate-with-multiple-names"></a>

## An SSL Certificate with Multiple Names

There are other ways that allow sharing a single IP address between several
HTTPS servers. However, all of them have their drawbacks. One way is to use a
certificate with several names in the `SubjectAltName` certificate field, for
example, `www.example.com` and `www.example.org`. However, the `SubjectAltName`
field length is limited.

Another way is to use a certificate with a wildcard name, for example,
`*.example.org`. A wildcard certificate secures all subdomains of the
specified domain, but only on one level. This certificate matches
`www.example.org` but does not match `example.org` and
`www.sub.example.org`. These two methods can also be combined. A
certificate may contain exact and wildcard names in the `SubjectAltName`
field, for example, `example.org` and `*.example.org`.

It is better to place a certificate file with several names and its private key
file at the `http` level of configuration to inherit their single memory
copy in all servers:

```nginx
ssl_certificate     common.crt;
ssl_certificate_key common.key;

server {
    listen          443 ssl;
    server_name     www.example.com;
#...
}

server {
    listen          443 ssl;
    server_name     www.example.org;
#...
}
```

<a id="sni"></a>

## Server Name Indication

A more generic solution for running several HTTPS servers on a single IP address
is TLS Server Name Indication extension (SNI, [RFC 6066](https://datatracker.ietf.org/doc/html/rfc6066.html)), which allows a browser
to pass a requested server name during the SSL handshake, and therefore, the
server will know which certificate it should use for the connection. SNI is
currently supported by most modern browsers, though may not be used by some old
or special clients.

If Angie was built with SNI support, then Angie will show this when run with the
`-V` switch:

```console
$ angie -V
...
TLS SNI support enabled
...
```

However, if the SNI-enabled Angie is linked dynamically to an OpenSSL
library without SNI support, Angie displays a warning:

> Angie was built with SNI support, however, now it is linked
> dynamically to an OpenSSL library which has no tlsext support,
> therefore SNI is not available