[/
    Copyright (c) 2025 Mohammad Nejati

    Distributed under the Boost Software License, Version 1.0. (See accompanying
    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

    Official repository: https://github.com/boostorg/beast
]


[section SSL/TLS Certificate]

[/-----------------------------------------------------------------------------]

[heading Certificate Authority]

A Certificate Authority (CA) is a trusted entity that signs digital
certificates, enabling users to verify their authenticity. Rather than storing
every individual certificate for each server (which would be impractical due to
the sheer volume and frequent renewals), users can store a limited set of root
certificates to authenticate server certificates as needed.

Boost.Asio provides various methods for loading certificate authority
certificates:

* [@boost:/doc/html/boost_asio/reference/ssl__context/add_certificate_authority.html `net::ssl::context::add_certificate_authority`]
* [@boost:/doc/html/boost_asio/reference/ssl__context/add_verify_path.html `net::ssl::context::add_verify_path`]
* [@boost:/doc/html/boost_asio/reference/ssl__context/load_verify_file.html `net::ssl::context::load_verify_file`]
* [@boost:/doc/html/boost_asio/reference/ssl__context/set_default_verify_paths.html `net::ssl::context::set_default_verify_paths`]

It is important to set up peer verification so that the TLS/SSL handshake fails
if certificate verification is unsuccessful:

[snippet_core_6]

A client must also verify that the hostname or IP address in the certificate
matches the expected one. The
[@boost:/doc/html/boost_asio/reference/ssl__host_name_verification.html
`net::ssl::host_name_verification`] helper function object can perform this
verification according to the rules described in RFC 6125:

[snippet_core_7]

A server can also request and verify a client certificate to authenticate the
client:

[snippet_core_8]

[/-----------------------------------------------------------------------------]

[heading Server Certificate]

A Server Certificate is a digital certificate that confirms a server's identity
as the legitimate destination for a client. It contains a verifiable signature
that ensures it was issued by a trusted certificate authority (CA).

When a server certificate is issued by an intermediate certificate authority,
and the client lacks those intermediate certificates, the server should provide
all the relevant certificates to the client. This allows the client to verify
the final certificate in the chain against the root certificate.

The following Boost.Asio methods can be used for loading a certificate or a
certificate chain:

* [@boost:/doc/html/boost_asio/reference/ssl__context/use_certificate.html `net::ssl::context::use_certificate`]
* [@boost:/doc/html/boost_asio/reference/ssl__context/use_certificate_file.html `net::ssl::context::use_certificate_file`]
* [@boost:/doc/html/boost_asio/reference/ssl__context/use_certificate_chain.html `net::ssl::context::use_certificate_chain`]
* [@boost:/doc/html/boost_asio/reference/ssl__context/use_certificate_chain_file.html `net::ssl::context::use_certificate_chain_file`]

[/-----------------------------------------------------------------------------]

[heading Client Certificate]

A server can authenticate clients by requiring and verifying their certificates,
preventing access for those without a valid certificate and private key. The
server enforces this by modifying peer verification settings:

[snippet_core_8]

If used, the necessary CA certificates must be loaded into the server's SSL
context to enable verification of the client's certificate.

[/-----------------------------------------------------------------------------]

[heading Common Name and Subject Alternative Name]

The Subject Alternative Name (SAN) is an extension in X.509 certificates that
allows multiple domain names, subdomains, or IP addresses to be associated with
a single SSL/TLS certificate. Before that it was the Common Name field in the
certificate subject which could contain a single hostname.

[@https://datatracker.ietf.org/doc/html/rfc6125#appendix-B.2 RFC 6125]
recommends that if a certificate includes a SAN dNSName field, the client must
ignore the subject CN field. Some modern browsers, such as Google Chrome, check
only the SAN section in an SSL/TLS certificate and reject certificates that
contain only the CN field.

[/-----------------------------------------------------------------------------]

[heading Private Key]

The private key of a certificate is required during the SSL/TLS handshake to
prove that the certificate's provider is its rightful owner

The following Boost.Asio methods can be used for loading a private key:

* [@boost:/doc/html/boost_asio/reference/ssl__context/use_private_key.html `net::ssl::context::use_private_key`]
* [@boost:/doc/html/boost_asio/reference/ssl__context/use_private_key_file.html `net::ssl::context::use_private_key_file`]
* [@boost:/doc/html/boost_asio/reference/ssl__context/use_rsa_private_key.html `net::ssl::context::use_rsa_private_key`]
* [@boost:/doc/html/boost_asio/reference/ssl__context/use_rsa_private_key_file.html `net::ssl::context::use_rsa_private_key_file`]

If the private key is secured with a password, the
[@boost:/doc/html/boost_asio/reference/ssl__context/set_password_callback.html
net::ssl::context::set_password_callback] allows specifying a callable object to
retrieve the password.

[/-----------------------------------------------------------------------------]

[heading Self-Signed and Self-Issued Certificates]

A self-issued certificate is a certificate where the issuer and subject are the
same entity.

A self-signed certificate is a self-issued certificate in which the digital
signature can be verified using the public key within the certificate.

[warning
    Installing an untrusted, self-issued, or self-signed CA certificate poses a
    significant security risk, as there are no restrictions on the domains for
    which it can issue certificates. This allows attackers to generate
    fraudulent certificates for any public domain, enabling man-in-the-middle
    attacks if they gain access to your network.
]

[/-----------------------------------------------------------------------------]

[heading Diffie-Hellman (DH) Parameters]

Diffie-Hellman (DH) key exchange is a cryptographic protocol that allows two
parties to securely establish a shared secret over an insecure communication
channel. The key exchange process involves both parties agreeing on a set of
parameters, known as Diffie-Hellman parameters, which include a large prime
number `p` and a generator `g`. Since generating these parameters is a
computationally expensive task, a user might prefer to provide a precomputed
value at startup.

The following Boost.Asio methods can be used for loading DH parameters:

* [@boost:/doc/html/boost_asio/reference/ssl__context/use_tmp_dh.html `net::ssl::context::use_tmp_dh`]
* [@boost:/doc/html/boost_asio/reference/ssl__context/use_tmp_dh_file.html `net::ssl::context::use_tmp_dh_file`]

If no DH parameter is provided, OpenSSL will refuse to perform any handshake
that uses DHE-based cipher suites but will still work with other cipher suites,
such as those based on ECDHE.

[/-----------------------------------------------------------------------------]

[heading A Self-Issued Certificate Example]

In the following example, we will generate a self-signed CA certificate and use
it to issue both server and client certificates.

* Generate a CA certificate:

```
openssl req -new -newkey rsa:4096 -keyout ca.key -x509 -out ca.crt -subj "/CN=localhost" -days 365
```


* Generate a Server CSR:

```
openssl req -new -newkey rsa:4096 -keyout server.key -out server.csr -subj "/CN=localhost" -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"
```


* Sign the Server CSR using our CA: 

```
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -copy_extensions copy -days 365 -out server.crt 
```


* Generate a Client CSR:

```
openssl req -new -newkey rsa:4096 -keyout client.key -out client.csr -subj "/CN=client.1"
```


* Sign the Client CSR using our CA: 

```
openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key -days 365 -out client.crt 
```

* Generate a DH parameters file:

```
openssl dhparam -out dh4096.pem 4096
```

Server example: [path_link example/doc/ssl/server.cpp server.cpp]

Note that the server is configured in such a way that it requests and verifies
the client certificate. You can disable this by commenting out the related line
in the example.

You can test the server using this cURL command:

```
curl https://localhost:8080 --cacert ca.crt --cert client.crt --key client.key
```

Also, you can use the client example: [path_link example/doc/ssl/client.cpp client.cpp]

[endsect]
