Consulting djbware Publications

TLS encryption for Client/Server IPv6/IPv4 communication

What is ucspi-ssl?

sslserver, sslclient, and sslhandle are command-line tools for building SSL client-server applications. They conform to the UNIX Client-Server Program Interface, UCSPI.

sslserver listens for IPv6 and/or IPv4 connections, and runs a program for each connection it accepts. The program environment includes variables that hold the local and remote host names, IP addresses, and port numbers. sslserver offers a concurrency limit on acceptance of new connections, and selective handling of connections based on client identity supporting CIDR IP address notation. sslserver supports STARTTLS and STLS.

sslclient requests a connection to either a IPv6 or IPv4 TCP sockets, and runs a program. The program environment includes the same variables as for sslserver.

sslhandle is a pre-forking sslserver; though without STARTTLS/STLS capabilities.

Features & History

The current verion of ucspi-ssl (0.10.x) includs the following communication capabilities:

Version history

ucspi-ssl posses the following family tree:

Compatibility

Note: Starting with ucspi-ssl-0.10.11, compability has been tested and adjusted to a variety of *SLL versions.

Dependencies

Usage

ucspi-ssl can be considered as high-level programming interface for OpenSSL and/or LibreSSL which is mandatory to achieve TLS support for

This is facilitated by means of the lib ucspissl.a (after compilation; located in ./compile) and the header file ucspissl.h.

ucspi-ssl can be build on top of OpenSSL or LibreSSL with two options:

  1. The standard way is to use the *SSL installation coming with your OS by dynamically linking it.
  2. The alternative way is to use a different *SSL library (perhaps more recent) while linking it statically with this.

Sources

Version & Download Description fehQlibs compatiblity Verification
ucspi-ssl 0.11.1 The current 'head' version of ucspi-ssl with minor OpenSSL compatility enhancements while including all features of ucspi-ssl 0.10.11. fehQlibs-13(a) MD5: 0cde0d55031ff2dce6a5562617639bd0
Build: 20191107172118
ucspi-ssl 0.10.11 The sixth carefully checked version of ucspi-ssl (0.10.x) employing cutting edge TLS 1.3 and X.509 capabilities together with full-featured dual-stack servers. fehQlibs-10a/ fehQlibs-12x MD5: 5211e0d4e56dc555eb0acbc63a8310be
Build: 20190803131811
ucspi-ssl 0.99e IPv6 enabled ucspi-ssl supporting OpenSSL 1.1 together with LibreSSL; though outdated not required MD5: d6d1269606834f0e1a3cfd28c142fb36
Build: 20180711223427

The source code of the current ucspi-ssl is provided in doxygen.

How to install ucspi-ssl

ucspi-ssl uses D.J. Bernstein's /package conventions for installation. Typically, un-tar the archive under /package, change to host/superscript.com/net/ucspi-ssl-<version> and calling package/install would be enough.
ucspi-ssl is pre-packaged to suite the AMD64 environment.
Depending on your Perl settings, you rather succeed with package/install base and package/man for the additional man-pages.

Note: The additional sslperl module may not succeed on every Unix plattform.

Documentation of the programs

Man pages:

Server apps Client apps Miscellaneous
sslserver
sslhandle
https@
sslcat
sslclient
sslconnect
ucspi-tls

General information

Translations (outdated):

Note: These sites may refer to outdated versions of ucspi-ssl.

TLS environment & security

ucspi-ssl's sslserver will display the current Cipher settings, in case the flag -V is provided. Sample of the output using multilog:

2018-10-12 13:02:14 sslserver: tls 16518 accept TLSv1.3:TLS_AES_256_GCM_SHA384 2018-10-12 13:02:19 qmail-smtpd: pid 16518 Reject::AUTH::login P:ESMTPSA S:93.174.93.228:unknown H:User ?~ 'test@fehcom.net' 2018-10-12 13:02:19 sslserver: ended by 16513 status 0 2018-10-12 13:11:40 sslserver: tls 17356 accept TLSv1.2:ECDHE-RSA-CHACHA20-POLY1305 2018-10-12 13:11:41 qmail-smtpd: pid 17356 Accept::RCPT::Recipients_Pam P:ESMTPS S:195.4.92.91:mout1.freenet.de H:mout1.freenet.de ... 2018-10-12 13:11:55 sslserver: ended by 17351 status 0

In the first case AES_256_GCM_SHA384 is the negotiated Cipher in use together with TLS 1.3 as chosen protocol, which requires ECDH as key exchange protocol.
In the second case, TLS 1.2 is used but now with the most recent CHACHA20_POLY1305 stream cipher+authentication provided by Dan Bernstein.
Of course, this will only work with most recent versions of OpenSSL (see below), which - as can be seen - is also availalbe for unwanted visitors from the Seychelles (using IP 93.174.93.228).

TLS 1.3 with OpenSSL 1.1.1x/LibreSSL 2.9.x

TLS 1.3 is a very different protocol in comparison with it's predecessors,

In short, TLS 1.3 is 21st century cryptography.

Elliptic Curve Diffie-Hellman

ucspi-ssl may use one of the following curves from OpenSSL 1.1.1:

You can verify the ECC curves, your OpenSSL version offers with the following command:

openssl ecparam -list_curves

Unlike DH with the Discrete Logarithm, there is no particular DHPRAM file to generate because the ECC parms are taken from internal defaults.

Further information about OpenSSL and it's usage can be found here:

Cipher Selection

OpenSSL uses for TLS 1.3 the API SSL_set_ciphersuites since in this version the cipher suites are much more restricted. In fact, some common cipher setting nouns like DEFAULT and HIGH are not supported here; and of course make no sense.

Starting with ucspi-ssl-0.10.11 legacy and current cipher settings are supported.

In OpenSSL TLS 1.3 the standard cipher is TLS_AES256_GCM_SHA384 providing hardware acceleration on most platforms. Rather, from a security point of view, I prefer CHACHA20_POLY1305. You can enforce this usage by setting the cipher suite on the client side to:

TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384

I feel a little unhappy combing AES256 with GCM, since it GCM uses a Galois Field GF(128) and thus is well suited for AES128.

*SSL dependencies and updates

Since ucspi-ssl depends on either OpenSSL or LibreSSL, it is inherently affected by bugs and flaws in here. Thus, please check for CVEs. In case you need to upgrade the *SSL libs, proceed as follows:

Note: Though ucspi-ssl did suffer from the Heartbleed bug in OpenSSL it is very unlikely that this could have exploited for security relevant information. sslserver in particular raises a new address space (and containing the vulnerable SSL context) for each new connection and IP. In this sense, sslserver mitigates your risks.

The latest version of ucspi-ssl supports:

Under normal circumstances, ucspi-ssl detects the respective *SSL versions and will compile and work without manual intervention.

However, you may use the most current OpenSSL (and LibreSSL) versions on your system in a 'none-destructive' mode for ucspi-ssl while adjusting

Checking your installation

Once installed, your TLS (1.3) capabilities can be checked using this nice testssl.sh script from Dirk Wetter.

*ix specific installation instructions

Gentoo

Gentoo includes a ready-to-use package for ucspi-ssl. However, this package is outdated.

NetBSD

NetBSD includes the ucspi-ssl package (outdated).

MacOS X

ucspi-ssl will compile with clang in case Xcode is installed. You need to adjust conf-cc. The following include solved the situation under MacOS X 'El Capitan' in my case for conf-cc:

clang -O2 -g -Wall -I /Developer/SDKs/MacOSX10.6.sdk/usr/include

You can add that statement into the conf-cc file prior of compilation.

Continue with:

package/compile base

because MacOS X is missing the environ facility.

OmniOS (Illumos)

The usual loader option -m64 does not work and is erroneously detected. After package/compile edit within the compile directory the file load and remove that option. Issue the command make as usual.

Since manpath is not supported, you need to include the man-path manually in conf-man.

Proceed with package/install.

RasPi/Raspbian Linux

ucspi-ssl supports Raspbian Linux and the ARM architecture out-of-the box.

Within the src directory of ucspi-ssl use

sh ./find-systype.sh

to display the given SW and HW architecture. Taking some compiler flags from gcc ARM options you can fine-tune settings to your ARM system within conf-cc and conf-ld.

Together with most Linux systems, you need to install the OpenSSL development environment. On a standard Debian system (like Raspbian) you succeed with the following:

agt-get update apt-get install libssl-dev

ucspi-ssl installs and works seamlessly well using clang under FreeBSD 12 for the ARM64 architecture but now in 64 bit mode!

Enjoy the ucspi-ssl package!