Networking Model

DataReel 7 networking is TLS first: every protocol client and server except telnet and ping is encrypted.

Contents

Layers

The networking classes are built in three layers:

gxSocket is a thin, IPv4 and IPv6 TCP/UDP socket class. Host names are resolved with getaddrinfo(), so the same code works with either protocol. It is used directly only for plain-text protocols (telnet) and as the transport under TLS.
gxSSL wraps the TLS library: OpenSSL on Linux (and optionally on Windows) or the Windows Schannel library. TLS 1.2 is the lowest version allowed.
gxsTLSConnection and gxsTLSServer combine the two into the object every protocol uses: a connection that is encrypted from the start (implicit TLS) or upgraded after a STARTTLS style command, checks the server certificate and host name by default, and reads lines or blocks with a timeout.

The protocol classes sit on top of gxsTLSConnection:

gxsHTTPClient: HTTPS client (http:// URLs are refused). gxsHTTPMessage and its read/write functions are also used to write HTTPS servers.
gxsSMTPClient: send mail over implicit TLS (port 465) or STARTTLS (port 587).
gxsPOP3Client: read mail over implicit TLS (port 995) or STLS (port 110).
gxsFTPClient: FTPS with encrypted data connections.
gxStream: the DataReel database block protocol over TLS.

Two diagnostic tools stay plain text because their protocols cannot be encrypted: gxsTelnetClient and gxsPing (ICMP). Use telnet only on trusted networks.

Certificates

Clients verify the server's certificate chain and host name (or IP address) by default. The trusted certificates are the system store (the OpenSSL default paths on Linux, the Windows certificate store with Schannel, and with OpenSSL 3.2 or later on Windows), or the CA file given with SetCAFile(). SetVerifyPeer(false) turns verification off and should only be used against test servers with self-signed certificates.

Servers load a certificate chain and private key in PEM format. With Schannel the certificate can also be a .pfx/.p12 file. A test certificate authority and server certificate can be made with the openssl command line program:

openssl req -x509 -newkey rsa:3072 -nodes -keyout ca.key -out ca.pem -days 365 -subj "/CN=Test CA"
openssl req -newkey rsa:3072 -nodes -keyout server.key -out server.csr -subj "/CN=localhost"
printf "subjectAltName=DNS:localhost,IP:127.0.0.1,IP:::1\n" > san.ext
openssl x509 -req -in server.csr -CA ca.pem -CAkey ca.key -CAcreateserial \
  -out server.pem -days 365 -extfile san.ext

Example

A complete TLS client in a few lines. See examples/tls for servers, HTTPS, mail, FTPS and gxStream programs.

#include "gxstls.h"

int main()
{
  gxsTLSConnection conn;
  conn.SetTimeout(30);
  if(conn.Connect("example.com", 443) != 0) {   // TLS handshake + cert check
    std::cerr << conn.Error() << "\n";
    return 1;
  }
  conn.Send("HEAD / HTTP/1.1\r\nHost: example.com\r\nConnection: close\r\n\r\n");
  std::string line;
  while(conn.ReadLine(line) && !line.empty()) std::cout << line << "\n";
  return 0;
}