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.13.x) includs the following communication capabilities:
- Delayed TLS handshake using Scott Gifford's STARTTLS extensions,
- certificate chaining support,
- SubAltName recognition for FQDN verification, and
- CIDR support for the cdb to filter IPv4/IPv6 connections.
- IPv6/IPv4 communication and DNS resolution is based on fehQlibs.
- Version 0.10.8 employs now the dual-stack operation for sslserver in case the pseudo-IP address :0 is given as hostname. IPv4 CIDR evaluation is based on a more robust scheme now.
- Version 0.10.9 uses a refactored IPv4/IPv6 CIDR evaluation module and supports LibreSSL 2.9.x providing TLS 1.3 capabilities.
- Version 0.10.10 supports DSA/ECDSA additionally to RSA signed X.509 certs.
- Version 0.10.11 improves interoperability with different versions of OpenSSL and LibreSSL; includes SNI for sslclient and allows selection of Ciphers for TLS 1.3 and it's predecessors.
- Version 0.12.x is based on fehQlibs-19 (or higher) to support natively GCC-10, includes for sslserver to limit connections for a single IP and already respects the most up-to-date OpenSSL and LibreSSL releases.
- Version 0.13.x has dropped support for pre-TLS 1.3 OpenSSL/LibreSS version (APIs removed).
Version history
ucspi-ssl posses the following family tree:
- ucspi-ssl-0.6x was the orginal version of provided initially by SuperScript (William Baxter).
- ucspi-ssl-0.7x is the latest version (now available on GitHub).
- ucspi-ssl-0.8x is my fork including Scott Gifford's extensions for STARTTTLS and other enhancements.
- ucspi-ssl-0.9x includes IPv6 capabilites streamlined with ucspi-tcp6-0.9.x.
- ucspi-ssl-0.10.x appplies significant code refactoring while using the fehQlibs(-10).
- usspi-ssl-0.11.x should be used with the fehQlibs-15.
- usspi-ssl-0.12.x requires at least fehQlibs-19.
- usspi-ssl-0.13.x requires at least fehQlibs-25.
The Changelog should give you an idea about the ongoing improvements.
Compatibility
- Support of LibreSSL's API.
- Native TLS 1.3 is provided by means of OpenSSL 1.1.1. and LibreSSL 2.9.1.
- However ucspi-ssl makes only use of the current *SSL APIs as by OpenSSL 1.1.1/3.x and LibreSSL > 3.7.
- Employing LD_LIBRARY_PATH, ucspi-ssl successfully will use *SSL libraries outside your default settings.
Note: Starting with ucspi-ssl-0.10.11, compability has been tested and adjusted to a variety of *SSL versions.
Dependencies
- Required: fehQlibs. Doesn't compile without it.
- Required for Linux: libssl-dev libraries (separate package).
- Optional but indispensible: ucspi-tcp6
to build the cdb to control incoming connections for
sslserver using
tcprules coming with
the ucspi-tcp6
package. Older versions of ucspi-tcp can be used as well,
but don't provide neither IPv4 CIDR nor IPv6 capabilities.
The generated cdb however, is binary compatible among all versions.
https@ and sslconnect depend on routines from ucspi-tcp6 (or earlier versions).
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:
- The standard way is to use the *SSL installation coming with your OS by dynamically linking it.
- The alternative way is to use a different *SSL library (perhaps more recent) while linking it statically with this.
The libssl may be however dynamically linked. Use ldd sslserver to check for dynamically linked libraries.
Sources
Version & Download | Description | fehQlibs compatiblity | Verification |
---|---|---|---|
ucspi-ssl 0.13.03 | Possesses seamless compatibility with OpenSSL 3.2/3.3/3.4 LibreSSL 3.7/3.8/3.9 and does only support the 'modern' *SSL APIs and provides better verbose error messages. Allows now addtionally to provide the passphrase for a protected keyfiley as file and not just on FD3. | fehQlibs-25 | MD5: 255d6478f26b10fb2a29210a759a8ae4 Build: 20240923144535 |
ucspi-ssl 0.12.10 | Posseses compatibility with OpenSSL 3.2 and LibreSSL 3.8. This version solves the 'stuck in polling' hanging sessions finally. Added new X.509 certificates based on ECC. Improvements to better cope with DoS and DDoS attacks. | fehQlibs-19+; better: fehQlibs-22 | MD5: 1c7a1e31d721c8b188a0e94a138edcfd Build: 20231204180637 |
ucspi-ssl 0.11.6a | The current 'head' version of ucspi-ssl and including a mitigation for the occassionaly seen 'stuck in polling' phenomen for TLS connections introducing a poll limit on call for sslserver and sslhandle in addition with convenience fixes in particular for GCC-10. Since under Linux the PERL module notoriously fails to install, it is now optinal to install. | fehQlibs-16 and fehQlibs-15 | MD5: 69f68861c3c59ca4c97398402ae4ce70 Build: 20200920115945 |
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-10/ 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.
Tickets, Change Requests, communication
An EZMLM mailing list keeps you updated with current developments, bug fixes, and features discussed. This list also can be used to file
- Defects (bug reports) and
- Change Requests (enhancements).
To inscribe use: ucspi mailing list
This list is also used for ucspi-tcp6, As usual, I can't guarantee a certain response level; but reasonable issues will be answered.
Documentation of the programs
sslserver
ucspi-ssl's main program is sslserver and provides TCP connection features identical to tcpserver but now with additional TLS capabilities. For more details see: sslserver.
Exceptions:
- sslserver does currently not support the use of a CRL Certificate Revocation List.
- sslserver does not provide OCSP lookups.
- Server Name Indication SNI can be 'emulated' by sslserver on a client base.
Man pages
Server apps | Client apps | Miscellaneous |
---|---|---|
sslserver sslhandle |
https@ sslcat sslclient sslconnect |
ucspi-tls |
General information
- My SMTP and Transport Layer Security (TLS) tutorial (outdated).
- The original ucspi-ssl source created by W.E. Baxter.
- Scott Gifford's STARTTLS UCSPI-SSL extension (unavailable).
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:
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,
- protecting large parts of the handshake material, in particular the X.509 certificates,
- providing by the same token a much faster handshake,
- using D.J. Bernstein's ChaCha20 and Poly1305 for message encryption and authentication based on the AEAD model instead of AES in broken CBC-mode and with awful hashsums (hash-then-encrypt),
- while requiring for the handshake to be always ephemeral Diffie-Hellman (ECDHE) based on Elliptic Curves.
In short, TLS 1.3 is 21st century cryptography.
Elliptic Curve Diffie-Hellman
ucspi-ssl may use one of the following curves:
- x25519 (the Bernstein Curve)
- secp256r1
- secp384r1
- secp521r1
- x448
You can verify the ECC curves, your OpenSSL version offers with the following command:
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:
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:
- Install the updated version of *SSL from you *NIX repository -- or --
- install *SSL from the source. Make sure to use the same path as your original installation. Typically, the required header files are expected in /usr/include/openssl.
- Check for your ucspi-ssl source directory; usually /package/host/superscript/net/ucspi-ssl-x.yz.
- Remove the directory ./compile and re-run package/install. This will link ucspi-ssl with the new *SSL version.
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:
- OpenSSL 1.1.1
- OpenSSL 3.0
- OpenSSL 3.1
- OpenSSL 3.2
- OpenSSL 3.3
- OpenSSL 3.4.0-alpha1
- LibreSSSL 3.7.
- LibreSSSL 3.8.
- LibreSSSL 3.9.
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
- conf-ssl including the path to header files and
- conf-ssllibs using the argument -L for determine the path of the libraries 'libssl' and 'libcrypto'.
- Use LD_LIBRARY_PATH to entitle i.e. sslserver to bind to a *SSL libraries outside your default lib path.
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
Ubuntu
Here is a recipe to solve the well-known '/usr/bin/ld: cannot find -lperl' problem:
Thanks Mike W.!
NetBSD
NetBSD includes the ucspi-ssl package (outdated).
MacOS X (Outdated)
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:
You can add that statement into the conf-cc file prior of compilation.
Continue with:
because MacOS X is missing the environ facility.
RasPi/Raspbian Linux
ucspi-ssl supports Raspbian Linux and the ARM architecture out-of-the box.
Within the src directory of ucspi-ssl use
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:
ucspi-ssl installs and works seamlessly well using clang under FreeBSD 14 for the ARM64 architecture but now in 64 bit mode!
Enjoy the ucspi-ssl package!