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 re‐
       leased between LibreSSL releases, the letter ‘p’ followed by an increas‐
       ing 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 LibreSSL,
       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 li‐
       cense.

       LibreTLS is not encumbered by the dual-licensing of OpenSSL  under  both
       the OpenSSL license and the original SSLeay license, which are incompat‐
       ible  with the GNU General Public License.  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.

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)
