SSL/TLS Class

gxSSL wraps OpenSSL or Windows Schannel. Most programs use it through gxsTLSConnection.

Contents

Overview
Context Functions
Connection Functions
Key and Certificate Functions (OpenSSL)

Overview

gxSSL holds a TLS context (certificates, keys, trusted CAs) and one TLS connection on a socket. On Linux it is built on the system OpenSSL (1.1.1 or later). On Windows it is built on Schannel by default (CMake option DATAREEL_SSL=SCHANNEL), which needs no extra libraries, or on OpenSSL (DATAREEL_SSL=OPENSSL).

DataReel 7 changes from 6.x:

TLS 1.2 is the lowest version allowed. gxSSLMethod is now gxSSL_TLS (TLS 1.2 or 1.3), gxSSL_TLSv1_2, gxSSL_TLSv1_3 or gxSSL_DTLS (OpenSSL only). The SSL 2, SSL 3, TLS 1.0 and TLS 1.1 values were removed.
The system certificate store is loaded when no CA list is set, and VerifyCert() checks the subject alternative names (with wildcards) or IP address instead of only the common name. Clients verify by default (HasVerifyCert() is true).
MakeDHParms(), LoadDHParms(), MakeRSAEphKey() and the gxRandom class were removed; TLS 1.2 and 1.3 do not need them. MakeRSAPrivateKey() makes 3072-bit keys by default and refuses fewer than 2048 bits.
A context passed to gxSSL(gxSSL_CTX_t *) or SetCTX() is no longer freed by that object, so one server context can be shared by many connections.

Functions that return int return 0 (gxSSL_NO_ERROR) on success. SSLExceptionMessage() describes the last error.

Context Functions

gxSSL_CTX_t *gxSSL::InitCTX()

Creates the context using the settings below. MakeClient() or MakeServer() should be called first. Returns null on an error.

gxSSL_CTX_t *gxSSL::InitCTX(const char *cert_fname, const char *key_fname, const char *key_passphrase)

Sets the certificate, key and passphrase and creates the context.

void gxSSL::SetSSLProto(gxSSLMethod m)

Selects the TLS versions.

void gxSSL::SetCertFile(const char *s)

Certificate chain file (PEM, or DER with SetCertType(gxSSL_ASN1); PFX with Schannel).

void gxSSL::SetKeyFile(const char *s)

Private key file.

void gxSSL::SetPasswd(const char *s)

Key passphrase.

void gxSSL::SetCAList(const char *s)

Trusted CA certificate file. When not set the system store is used.

int gxSSL::MakeClient() / int gxSSL::MakeServer()

Selects the client or server side.

void gxSSL::SetCTX(gxSSL_CTX_t *p)

Uses a context owned by another gxSSL object.

Connection Functions

int gxSSL::OpenSSLSocket(gxsSocket_t s)

Creates the TLS connection object on a connected socket.

void gxSSL::SetHostName(const char *s)

Server name sent with SNI and used by Schannel for certificate checks.

int gxSSL::ConnectSSLSocket()

Runs the client handshake.

int gxSSL::AcceptSSLSocket()

Runs the server handshake.

int gxSSL::VerifyCert(const char *hostname, long *X509_return_code = 0)

Checks the peer certificate chain against the trusted CAs and that it was issued for hostname or the IP address. Returns 0 if it is valid. CertVerifyErrorString() describes the returned code.

int gxSSL::GetPeerCertInfo(std::string &subject, std::string &issuer)

Passes back the peer certificate subject and issuer.

int gxSSL::SendSSLSocket(const void *buf, int bytes)

Sends every byte. Returns bytes or -1.

int gxSSL::ReadSomeSSLSocket(void *buf, int bytes, int timeout_ms = -1)

Reads up to bytes of decrypted data. Returns bytes, 0 when the peer closed the connection, or -1.

int gxSSL::RecvSSLSocket(void *buf, int bytes, int seconds, int useconds)

Reads exactly bytes or until the timeout.

int gxSSL::CloseSSLSocket(int destroy_ssl = 1)

Sends the close notify alert.

Key and Certificate Functions (OpenSSL)

int gxSSL::MakeRSAPrivateKey(const char *key_fname, int key_len = 3072, KeyGenCallbackFunc cb_func = 0, void *cb_arg = 0)

Writes a new RSA private key. Not available with Schannel.

int gxSSL::MakeCertReq(const char *key_fname, gxCertIssuerInfo &ci, const char *req_fname)

Writes a certificate request (or self-signed certificate) for the key. Not available with Schannel.