TLS Connection Classes

gxsTLSConnection is the encrypted connection used by every DataReel protocol. gxsTLSServer accepts TLS clients.

Contents

Overview
gxsTLSConnection Client Functions
gxsTLSConnection Server Functions
gxsTLSConnection Data Functions
gxsTLSServer Functions

Overview

A gxsTLSConnection is a TCP connection plus a gxSSL object. Clients either start TLS at once (Connect() with implicit_tls true, as for HTTPS or SMTP on port 465) or connect in plain text and call StartTLS() after the protocol's STARTTLS, STLS or AUTH TLS command. After the handshake the server's certificate chain and host name are checked unless SetVerifyPeer(false) was called.

Data is read through an internal buffer, so text protocols can mix ReadLine() with block reads. Every read waits at most the timeout set with SetTimeout() (60 seconds by default). Functions that return int return 0 on success and -1 on failure; Error() describes the failure.

gxsTLSServer loads a certificate and key, listens on a port (IPv6 and IPv4), and runs the TLS handshake for each accepted client. Each accepted connection can be handed to a thread, for example with ThreadPool.

gxsTLSServer server;
if(server.Listen(8443, "server.pem", "server.key") != 0) return 1;
for(;;) {
  auto conn = std::make_shared<gxsTLSConnection>();
  if(server.Accept(*conn) != 0) continue;     // A failed handshake skips only that client
  pool.Submit([conn] {
    std::string line;
    while(conn->ReadLine(line)) conn->SendLine(line);   // Echo
  });
}

gxsTLSConnection Client Functions

void gxsTLSConnection::SetTimeout(int seconds)

Sets the connect and read timeout. The default is 60 seconds.

void gxsTLSConnection::SetCAFile(const std::string &fname)

Trusts the CA certificates in fname instead of the system store.

void gxsTLSConnection::SetClientCert(const std::string &cert_fname, const std::string &key_fname, const std::string &passphrase = std::string())

Presents a client certificate to servers that ask for one.

void gxsTLSConnection::SetVerifyPeer(bool on)

Turns server certificate checking on (the default) or off.

void gxsTLSConnection::SetProtocol(gxSSLMethod m)

Limits the TLS version: gxSSL_TLS (1.2 or 1.3, the default), gxSSL_TLSv1_2 or gxSSL_TLSv1_3.

int gxsTLSConnection::Connect(const std::string &host, int port, bool implicit_tls = true)

Opens a TCP connection and, with implicit_tls, runs the TLS handshake.

int gxsTLSConnection::StartTLS()

Starts TLS on an open plain connection. Data received before the handshake is discarded.

int gxsTLSConnection::AttachClient(gxSocket &&s, const std::string &host, gxsTLSConnection *session_from = 0)

Starts TLS as a client on a connected socket. With session_from the TLS session of that connection is reused, as FTPS servers require for data connections.

gxsTLSConnection Server Functions

int gxsTLSConnection::AttachServer(gxSocket &&client, gxSSL_CTX_t *server_ctx)

Takes an accepted client socket and runs the TLS server handshake with a server context. gxsTLSServer::Accept() calls this.

gxsTLSConnection Data Functions

int gxsTLSConnection::Send(const void *buf, int bytes)

Sends every byte. Returns bytes or -1. Send(std::string_view) sends a string.

int gxsTLSConnection::SendLine(std::string_view s)

Sends s followed by CR LF.

int gxsTLSConnection::ReadSome(void *buf, int bytes)

Reads up to bytes. Returns the number read, 0 if the peer closed the connection, or -1 on an error or timeout.

int gxsTLSConnection::Read(std::string &s, std::size_t bytes)

Reads exactly bytes into s unless the connection closes or fails. Returns the number read.

bool gxsTLSConnection::ReadLine(std::string &line, std::size_t max_len = 65536)

Reads one line without its CR LF. Returns false if the connection closed, failed, timed out, or the line is longer than max_len.

bool gxsTLSConnection::ReadAll(std::string &s, std::size_t max_len = std::string::npos)

Reads until the peer closes the connection.

void gxsTLSConnection::Close()

Sends the TLS close notify and closes the socket.

bool gxsTLSConnection::IsSecure() const

True after the TLS handshake.

const std::string &gxsTLSConnection::Error() const

Describes the last failure, including certificate errors.

gxSocket &gxsTLSConnection::Socket()

The underlying socket, for PeerAddress() and similar calls. TLS() returns the gxSSL object.

gxsTLSServer Functions

int gxsTLSServer::Listen(int port, const std::string &cert_fname, const std::string &key_fname, const std::string &passphrase = std::string(), const std::string &bind_address = std::string())

Loads the certificate chain and private key and listens on port. Returns 0 if successful.

int gxsTLSServer::Accept(gxsTLSConnection &conn)

Waits for a client, accepts it and runs the handshake. Returns 0 if successful; a failed handshake closes only that client.

int gxsTLSServer::Port() const

The port being listened on (useful with port 0).

const std::string &gxsTLSServer::Error() const

Describes the last failure.