README(7)               Miscellaneous Information Manual             README(7)

NAME
       LibreTLS — libtls for OpenSSL

DESCRIPTION
       LibreTLS  is  a  port  of  libtls  from  LibreSSL  to OpenSSL.  libtls:
       https://man.openbsd.org/tls_init.3 is “a new TLS library,  designed  to
       make it easier to write foolproof applications”.

       libtls  provides an excellent new API, but LibreSSL can be difficult to
       install on systems which already use OpenSSL.  LibreTLS  aims  to  make
       the libtls API more easily and widely available.

   Releases
       LibreTLS         is         based         on         LibreSSL-portable:
       https://www.libressl.org/releases.html  sources.    LibreTLS   releases
       track  LibreSSL releases, starting with version 3.2.0.  If patches must
       be released between LibreSSL releases, the letter ‘p’  followed  by  an
       increasing digit starting from 1 will be added to the version number.

       LibreTLS       release       tarballs      are      available      from
       https://causal.agency/libretls/.

   Compatibility
       The libtls provided by LibreTLS is ABI-compatible with the libtls  pro‐
       vided by the corresponding LibreSSL release.

       The behaviour of LibreTLS and LibreSSL differs in how the root certifi‐
       cates  are  loaded  by default.  LibreSSL uses a hardcoded path to a CA
       bundle file, while LibreTLS uses the default CA locations  of  OpenSSL,
       which  may  include  a  CA  directory.  To restore the behaviour of Li‐
       breSSL,  call  tls_config_set_ca_file(3)  with  the  path  returned  by
       tls_default_ca_cert_file(3).  All other behaviour should be identical.

       LibreTLS  targets  the  OpenSSL 1.1.1 series.  Due to a bug in OpenSSL,
       only versions 1.1.1b and newer are known to work.  LibreTLS is compati‐
       ble with OpenSSL 3.0.0 but hasn't  been  ported  away  from  deprecated
       APIs.

   Platform Support
       LibreTLS  should  work  on  the  same  platforms  as LibreSSL-portable:
       https://www.libressl.org/releases.html, though it has  not  been  thor‐
       oughly tested on platforms other than Linux, FreeBSD and macOS.

   License
       libtls  consists  of  all  new  code developed as part of OpenBSD under
       OpenBSD's  preferred  license:  https://www.openbsd.org/policy.html  of
       ISC.  Some compat sources are under the 3-clause BSD license or the MIT
       license.

       LibreTLS  is not encumbered by the dual-licensing of OpenSSL under both
       the OpenSSL license and the original SSLeay license, which  are  incom‐
       patible  with  the GNU General Public License.  When OpenSSL 3.0 is re‐
       leased under the Apache 2.0 license, software under the GPLv3  will  be
       able  to  link  against LibreTLS and OpenSSL without additional permis‐
       sions.

INSTALLING
       To install from a release tarball, run the following:

             ./configure
             make all
             make install

       To install from a git checkout, autoconf, automake and libtool are  re‐
       quired.  Run the following before continuing 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.

Causal Agency                  February 27, 2022                     README(7)
