E-MailRelay
Public Types | Public Member Functions | Static Public Member Functions | List of all members
GSsl::Protocol Class Reference

A TLS protocol class. More...

#include <gssl.h>

Public Types

enum class  Result {
  ok , read , write , error ,
  more
}
 

Public Member Functions

 Protocol (const Profile &, const std::string &peer_certificate_name={}, const std::string &peer_host_name={})
 Constructor. More...
 
 ~Protocol ()
 Destructor.
 
Result connect (G::ReadWrite &io)
 Starts the protocol actively (as a client). More...
 
Result accept (G::ReadWrite &io)
 Starts the protocol passively (as a server). More...
 
Result shutdown ()
 Initiates the protocol shutdown by sending a "close notify shutdown alert" and does a socket shutdown once the alert is fully sent. More...
 
Result read (char *buffer, std::size_t buffer_size_in, ssize_t &data_size_out)
 Reads user data into the supplied buffer. More...
 
Result write (const char *buffer, std::size_t data_size_in, ssize_t &data_size_out)
 Writes user data. More...
 
std::string peerCertificate () const
 Returns the peer certificate in PEM format. More...
 
std::string cipher () const
 Returns the cipher name, or the empty string if not yet available. More...
 
std::string protocol () const
 Returns the protocol version like "TLSv1.2" or the empty string. More...
 
bool verified () const
 Returns true if the peer certificate has been verified. More...
 
std::string peerCertificateChain () const
 Returns the peer certificate chain in PEM format, starting with the peer certificate and progressing towards the root CA. More...
 
 Protocol (const Protocol &)=delete
 
 Protocol (Protocol &&)=delete
 
Protocoloperator= (const Protocol &)=delete
 
Protocoloperator= (Protocol &&)=delete
 

Static Public Member Functions

static std::string str (Result result)
 Converts a result enumeration into a printable string. More...
 

Detailed Description

A TLS protocol class.

A protocol object should be constructed for each secure socket. The Protocol::connect() and Protocol::accept() methods are used to link the connection's i/o methods with the Protocol object. Event handling for the connection is performed by the client code according to the result codes from read(), write(), connect() and accept().

Client code will generally need separate states to reflect an incomplete read(), write(), connect(), accept() or shutdown() in order that they can be retried. The distinction between a return code of Result::read or Result::write should dictate whether the connection is put into the event loop's read list or write list but it should not influence the resulting state; in each state socket read events and write events can be handled identically, by retrying the incomplete function call.

The protocol is half-duplex in the sense that it is not possible to read() data while a write() is incomplete or write() data while a read() is incomplete. (Nor is it allowed to issue a second call while the first is still incomplete.)

Definition at line 67 of file gssl.h.

Member Enumeration Documentation

◆ Result

enum class GSsl::Protocol::Result
strong

Definition at line 70 of file gssl.h.

Constructor & Destructor Documentation

◆ Protocol()

GSsl::Protocol::Protocol ( const Profile profile,
const std::string &  peer_certificate_name = {},
const std::string &  peer_host_name = {} 
)
explicit

Constructor.

The optional "peer-certificate-name" parameter is used as an additional check on the peer certificate. In the simplest case a client passes the server's domain name and this is checked for an exact match against the certificate's subject CNAME (eg. "CN=*.example.com"). A valid CA database is required. If the peer-certificate-name parameter is empty then a default value is taken from the profile (see Library::addProfile()).

The optional "peer-host-name" parameter is included in the TLS handshake to indicate the required peer hostname. This is typcially used by clients for server-name-identification (SNI) when connecting to virtual hosts, allowing servers to assume the appropriate identity. If the peer-host-name parameter is empty then a default value is taken from the profile (see Library::addProfile()).

Some underlying libraries treat peer-certificate-name and peer-host-name to be the same, using wildcard matching of the certificate CNAME against the peer-host-name.

Definition at line 145 of file gssl.cpp.

Member Function Documentation

◆ accept()

GSsl::Protocol::Result GSsl::Protocol::accept ( G::ReadWrite io)

Starts the protocol passively (as a server).

Definition at line 196 of file gssl.cpp.

◆ cipher()

std::string GSsl::Protocol::cipher ( ) const

Returns the cipher name, or the empty string if not yet available.

Definition at line 170 of file gssl.cpp.

◆ connect()

GSsl::Protocol::Result GSsl::Protocol::connect ( G::ReadWrite io)

Starts the protocol actively (as a client).

Definition at line 191 of file gssl.cpp.

◆ peerCertificate()

std::string GSsl::Protocol::peerCertificate ( ) const

Returns the peer certificate in PEM format.

This can be interpreted using "openssl x509 -in ... -noout -text".

Definition at line 153 of file gssl.cpp.

◆ peerCertificateChain()

std::string GSsl::Protocol::peerCertificateChain ( ) const

Returns the peer certificate chain in PEM format, starting with the peer certificate and progressing towards the root CA.

This is not supported by all underlying TLS libraries; the returned string may be just the peerCertificate().

Definition at line 159 of file gssl.cpp.

◆ protocol()

std::string GSsl::Protocol::protocol ( ) const

Returns the protocol version like "TLSv1.2" or the empty string.

Definition at line 165 of file gssl.cpp.

◆ read()

GSsl::Protocol::Result GSsl::Protocol::read ( char *  buffer,
std::size_t  buffer_size_in,
ssize_t &  data_size_out 
)

Reads user data into the supplied buffer.

Returns Result::read if there is not enough transport data to complete the internal TLS data packet. In this case the file descriptor should remain in the select() read list and the Protocol::read() should be retried using the same parameters once the file descriptor is ready to be read.

Returns Result::write if the TLS layer tried to write to the file descriptor and had flow control asserted. In this case the file descriptor should be added to the select() write list and the Protocol::read() should be retried using the same parameters once the file descriptor is ready to be written.

Returns Result::ok if the internal TLS data packet is complete and it has been completely deposited in the supplied buffer.

Returns Result::more if the internal TLS data packet is complete and the supplied buffer was too small to take it all. In this case there will be no read event to trigger more read()s so call read() again imediately.

Returns Result::error if the transport connnection was lost or if the TLS session was shut down by the peer or if there was an error.

Definition at line 201 of file gssl.cpp.

◆ shutdown()

GSsl::Protocol::Result GSsl::Protocol::shutdown ( )

Initiates the protocol shutdown by sending a "close notify shutdown alert" and does a socket shutdown once the alert is fully sent.

Definition at line 211 of file gssl.cpp.

◆ str()

std::string GSsl::Protocol::str ( Protocol::Result  result)
static

Converts a result enumeration into a printable string.

Used in logging and diagnostics.

Definition at line 182 of file gssl.cpp.

◆ verified()

bool GSsl::Protocol::verified ( ) const

Returns true if the peer certificate has been verified.

Definition at line 176 of file gssl.cpp.

◆ write()

GSsl::Protocol::Result GSsl::Protocol::write ( const char *  buffer,
std::size_t  data_size_in,
ssize_t &  data_size_out 
)

Writes user data.

Returns Result::ok if fully sent.

Returns Result::read if the TLS layer needs more transport data (eg. for a renegotiation). The write() should be repeated using the same parameters on the file descriptor's next readable event.

Returns Result::write if the TLS layer was blocked in writing transport data. The write() should be repeated using the same parameters on the file descriptor's next writable event.

Never returns Result::more.

Returns Result::error if the transport connnection was lost or if the TLS session was shut down by the peer or on error.

Definition at line 206 of file gssl.cpp.


The documentation for this class was generated from the following files: