Index
Creating a TLS session requires a sequence of steps. In this context, “session” is just a technical name for an encrypted connection.
The first step is to create the underlying network connection. The classes described in this chapter, with the sole exception of a handful of convenience functions, take an existing connection and put an encryption layer on it, creating a TLS session. Many types of encrypted connections, such as secure HTTP connections, are encrypted from start to finish, so a TLS session is prepared immediately after the creation of the underlying network connections. Other protocols may not necessarily be encrypted at first, and a TLS session gets established after an initial protocol-specific handshake.
The underlying network connection is traditionally created by creating
an x::fd reference,
representing a file descriptor, then using its methods to connect to
a server, or listen on a port and accept a connection from a client.
The next step is to create a reference to a credentials object.
x::gnutls::credentials::certificate
is a reference to a
reference-counted object that represents
the authentication information for a TLS session.
A TLS session has a client side and a server side. There are slight differences in the steps for setting up the credentials object depending on whether it will be used for the client side or the server side.
The client side requires the credentials
object to be loaded with a list of trusted certificate authorities.
set_x509_trust_default loads the system-wide default
list of trusted certificate authorities:
#include <x/gnutls/credentials.H> x::gnutls::credentials::certificate clientCert(x::gnutls::credentials::certificate::create()); clientCert->set_x509_trust_default();
The trusted certificate authority list may also be optionally loaded when setting up the server side of a TLS session. This is done if the TLS session uses client certificates. This is an optional part of a TLS session: the server verifying a client's certificate, which must be be signed by a trusted certificate authority.
A TLS session is not just about encryption. Authentication is an essential component of encryption. The whole purpose of encryption is to prevent unauthorized interception of a connection between a client and a server; that is, an intermediate party cannot listen in and make a copy or a log of the client/server connection.
However, if a hostile party has the means of passively listening in on a connection between the client and the server, it would also have the means to intercept it completely. Without authentication, once the ability to passively listen on a connection is there, intercepting the connection completely is just a minor incremental step. Without any kind of authentication in place, the client would be unaware that it's connected to an interloper, instead of the expected party. The interloper could proceed and establish a separate connection to the server, then manually exchange the traffic across the two separate connections, while intercepting the exchanged traffic surreptitiously.
As such, authentication is an integral part of an encrypted TLS session. The client authenticates the server, and requires that the server's certificate be signed by a certificate authority that's on the client's list of trusted certificate authorities. The client may also authenticate itself to the server, this part is optional, and depends on the individual client/server configuration. In TLS, authentication is implemented with X.509 certificates and trusted certificate authorities. This documentation does not include a full discussion of these topics, beyond this brief introduction, as it falls outside the scope of this documentation.
The x::gnutls::credentials::certificate
reference object stores the following authentication-related
configuration parameters:
The private key and the certificate (or a certificate chain) that are used to authenticate this side of the TLS session. This is required for TLS servers, and optional for TLS clients.
A list of trusted certificate authorities to authenticate the other side of the TLS session, the peer's TLS certificate.
In some situations, TLS servers must create a temporary key to effect the initial key exchange between the client and the server. This is called an “ephemeral DH keypair”, which is also called a temporary public key parameter.
The requirement for a temporary public key parameter may be satisfied in two ways. First by explicitly installing an emphemeral DH keypair that was created in advance. A second way, is to import the global DH parameters that are periodically regenerated by the system.
To meet these requirements, convenience functions are created that
prepare a credentials object with suitable default settings.
An earlier example prepares a stock client-side credentials object,
that uses set_x509_trust_default()
to load the default system list of
trusted certificate authorities.
The following example prepares a stock server-side credentials object:
#include <x/gnutls/credentials.H> x::gnutls::credentials::certificate serverCert(x::gnutls::credentials::certificate::create("certificate.crt", "certificate.key", GNUTLS_X509_FMT_PEM));
This example creates a default server-side credentials object, loading the server's certificate an private key from PEM-formatted files (pass the same filename twice if the certificate and the key are in the same file).
See the class reference for more information, including examples of advanced usage with a callback selecting one of several private keys and certificates, instead of using a fixed certificate for all TLS sessions. This is used in situations where a certificate must be selected individually for each session.
Multiple TLS sessions may use the same certificate object, and the same authentication configuration. This saves some time from having to initialize the same authentication configuration for each session. Instead, the authentication parameters are loaded once, and attached directly to each instantiated TLS session.