Using the session

After the handshake, the session object's recv() and send() methods may be used to securely exchange raw data with the peer. bye() performs an orderly shutdown of the TLS, after which the underlying network connection can be closed. The network connection can, of course, be closed without formally invoking bye(), however a formal TLS shutdown process serves a purpose. An unexpected connection teardown may be interpreted as an attack on the TLS session.

The session object also implements the file descriptor transport interface, so pubread() and pubwrite() may be used instead of recv() and send(). If a handshake was not previously completed, the first call to recv() and send() transparently calls handshake() first, before attempting to read or write. If the underlying file descriptor is non-blocking and the handshake is incomplete due to pending I/O, its status gets returned, and the next call to recv() and send() invokes handshake() again.

pubread() and pubwrite() will also invoke handshake() if one is needed; however the file descriptor must be a blocking file descriptor. In a non-blocking context, the semantics of bi-directional non-blocking I/O required by handshake cannot be implemented by pubread() and pubwrite(), so an exception gets thrown if that situation.

The file descriptor transport interface's getiostream() may be used in place of send() and recv() also, but only if the underlying file descriptor blocks:

x::iostream ios(sess->getiostream());

(*ios) << "GET / HTTP/1.0\r\n" << std::flush;

Alternatively, a file descriptor timeout may be initialized on top of a non-blocking file descriptor, and the TLS session object attached to the timeout object. This implements a timeout on the transport level. The TLS session object will propagate the timeout exception, when one gets thrown by the timeout object, passed along to the TLS library as an I/O error, and once the error code gets propagated back up to this library, it gets detected and rethrown.

See the session object class reference for more information on other session object methods. Note that most of them are allowed only before a handshake occurs.

Several x::gnutls::session methods are available that retrieve miscellaneous metadata, such as lists of ciphers, compression methods, and other algorithms that are implemented in the underlying GnuTLS library.