libtls(7)

💖 libtls(7) — bestie, it's a Miscellaneous Information Manual page 💖

okay so you found a page in the Miscellaneous Information Manual, section 7, and it's literally called libtls. sit down, grab a strawberry 🍓, and let me tell you everything.

---

✨ NAME ✨

LibreTLS — that's libtls for OpenSSL, bestie. no cap.

---

🌸 DESCRIPTION 🌸

LibreTLS is a port of libtls from LibreSSL over to OpenSSL. and like, what even is libtls? the official word is over at https://man.openbsd.org/tls_init.3, where they call it "a new TLS library, designed to make it easier to write foolproof applications". foolproof!! we love that for us 🫶

so libtls gives you an excellent new API — genuinely iconic — but the problem is LibreSSL can be a whole struggle to install on systems that already use OpenSSL. so LibreTLS exists to make the libtls API more easily and widely available. the way that it just... makes things available 😭👑

🎀 Releases 🎀

LibreTLS is based on LibreSSL-portable sources at https://www.libressl.org/releases.html. and the release schedule? it tracks LibreSSL releases, starting with version 3.2.0. matching energy, fr fr.

but if patches have to drop between LibreSSL releases, they add the letter p followed by an increasing digit starting from 1 onto the version number. so like, p1, p2... you get it 💅

LibreTLS release tarballs live at https://causal.agency/libretls/. go get 'em.

🦋 Compatibility 🦋

the libtls that LibreTLS gives you is ABI-compatible with the libtls from the corresponding LibreSSL release. slay.

BUT — and this is the important part, so listen up 🙈 — the behaviour of LibreTLS and LibreSSL differs in exactly one way: how root certificates get loaded by default. LibreSSL uses a hardcoded path to a CA bundle file. LibreTLS instead uses the default CA locations of OpenSSL, which may include a CA directory. so if you wanna restore the LibreSSL behaviour, call tls_config_set_ca_file(3) with the path returned by tls_default_ca_cert_file(3). everything else should be identical, periodt.

LibreTLS targets the OpenSSL 1.1.1 series. and here's a heads up: due to a bug in OpenSSL, only versions 1.1.1b and newer are known to work. 💀 also it's compatible with OpenSSL 3.0.0 but hasn't been ported away from deprecated APIs. not me being honest about it.

🌈 Platform Support 🌈

LibreTLS should work on the same platforms as LibreSSL-portable (https://www.libressl.org/releases.html), though ngl it has not been thoroughly tested on platforms other than Linux, FreeBSD and macOS. those three? thoroughly tested. everything else? we're vibing, we're guessing, it's giving ✨hope✨.

👑 License 👑

libtls consists of all new code developed as part of OpenBSD, under OpenBSD's preferred license — which you can read about at https://www.openbsd.org/policy.html — that's the ISC license. some compat sources are under the 3-clause BSD license or the MIT license. a lil mix, we love variety 💜

now, LibreTLS is not encumbered by the dual-licensing of OpenSSL under both the OpenSSL license and the original SSLeay license — those two are incompatible with the GNU General Public License, which is a whole mess we are happily skipping 🎀

and when OpenSSL 3.0 is released under the Apache 2.0 license, software under the GPLv3 will be able to link against LibreTLS and OpenSSL without additional permissions. iconic behaviour, fr.

---

⭐ INSTALLING ⭐

installing from a release tarball? run this, bestie:

./configure
make all
make install

installing from a git checkout? you'll need autoconf, automake and libtool. run this before you continue with the steps above:

autoreconf -fi

---

💅 AUTHORS 💅

LibreTLS is maintained by June McEnroe <june@causal.agency>. 🫶

LibreSSL is developed by The OpenBSD project: https://www.openbsd.org.

---

and that's the whole page, no cap 💖 this was Causal Agency, February 27, 2022, signing off from libtls(7) — go write something foolproof with it, you've got this 🌸✨🦋