#include <x/gnutls/session.H> x::fd filedesc=x::netaddr::create("www.example.com", "https", SOCK_STREAM)->connect(); x::gnutls::session sess(x::gnutls::session::create(GNUTLS_CLIENT, filedesc)); sess->credentials_set(clientCred); sess->set_default_priority(); sess->handshake(); sess->verify_peer("www.example.com");
x::gnutls::session
is a reference to a
reference-counted object that
represents a TLS session that's attached to
an existing file descriptor.
Its
create()
method
takes a reference to an existing file descriptor
object, and a parameter that specifies whether the file descriptor
should be a TLS client or a server.
There are several additional formalities before the TLS
session is ready.
First, the authentication credentials must be specified by using
credentials_set() to set the authentication
credentials for the session.
Then, the list of acceptable ciphers must be set.
set_default_priority specifies the default cipher
list.
Finally, handshake() performs the initial
TLS handshake with the peer, and establishes a
TLS session.
An exception gets thrown if handshake() fails to
establish a TLS session.
TLS clients should also use
verify_peer() to authenticate the server's
certificate's identity.
This is an important detail, see
the section called “Certificate credentials” for a brief discussion on the purpose of
certificate authentication.
#include <x/gnutls/session.H> x::gnutls::session sess(x::gnutls::session::base::client("imap.example.com", 993));
client() is a single function that creates a
new file descriptor, creates a new socket and connects to a server,
creates a new TLS session objects, and installs
a default credentials objects loaded
with the default authentication configuration and loads the default
system list of trusted certificate authorities, invokes
handshake() followed by
verify_peer() to validate the server's certificate.
The end result is a reference to a session object representing an
established TLS session, ready to be used.
#include <x/gnutls/sessioncache.H> auto cache=x::gnutls::sessioncache::create(); // ... sess->session_cache(cache); sess->handshake(); if (sess->session_resumed()) // ...
A TLS client may reuse the same TLS session parameters with a TLS
server for additional connections, in order to create the additional
connections faster. This optional feature requires
some support from the server. The server constructs a
x::gnutls::sessioncache,
then installs it before handshaking each established connection.
The same session cache object should be installed in every client
connection session.
After a handshake, session_resumed() indicates
whether the new connection uses cached session parameters.
The default x::gnutls::sessioncache caches
TLS sessions in memory. The
x::gnutls::session_cache::size
application property sets the
TLS session cache size. The most recent sessions, up to the value of
this property are cached.
It is possible to implement custom TLS session caching by subclassing
x::gnutls::sessioncacheObj
and implementing the
store(),
remove(), and
retr() methods.
The x::gnutls::session_cache::expiration
application property sets how long
TLS sessions remain cacheable, and defaults to one hour.
This is slightly different than
x::gnutls::session_cache::size; this
setting controls the maximum size of the default implementation of the
TLS session cache.
x::gnutls::session_cache::expiration
specifies that TLS sessions can no longer be reused after an hour,
by default, irrespective of the size of the TLS session cache.
sess->handshake(); x::gnutls::datum_t session_data=sess->get_session_data(); // ... sess2->set_session_data(session_data); sess->handshake(); if (sess->session_resumed()) // ...
After a handshake, a TLS client obtains the session's parameters
from
get_session_data(), which returns an
opaque blob representing the session parameters.
For subsequent session, the TLS client uses
set_session_data() before the handshake.
After a handshake, session_resumed() indicates
whether the new connection uses same, cached session parameters.