.Dd August  3, 2020
.Dt README 7
.Os "Causal Agency"
.\" To view this file, run: man ./README.7
.
.Sh NAME
.Nm LibreTLS
.Nd libtls for OpenSSL
.
.Sh DESCRIPTION
.Nm
is a port of
.Sy libtls
from LibreSSL
to OpenSSL.
.Lk https://man.openbsd.org/tls_init.3 libtls
is
.Do
a new TLS library, designed to make it easier to write foolproof applications
.Dc .
.
.Pp
.Sy libtls
provides an excellent new API,
but LibreSSL can be difficult to install
on systems which already use OpenSSL.
.Nm
aims to make the
.Sy libtls
API more easily and widely available.
.
.Ss Releases
.Nm
is based on
.Lk https://www.libressl.org/releases.html LibreSSL-portable
sources.
.Nm
releases track LibreSSL releases,
starting with version 3.2.0.
If patches must be released
between LibreSSL releases,
the letter
.Sq p
followed by an increasing digit
starting from 1
will be added to the version number.
.
.Pp
.Nm
release tarballs are available from
.Lk https://causal.agency/libretls/ .
.
.Ss Compatibility
The
.Sy libtls
provided by
.Nm
is ABI-compatible with the
.Sy libtls
provided by the corresponding LibreSSL release.
.
.Pp
The behaviour of
.Nm
and LibreSSL
differs in how the root certificates
are loaded by default.
LibreSSL uses a hardcoded path to a CA bundle file,
while
.Nm
uses the default CA locations of OpenSSL,
which may include a CA directory.
To restore the behaviour of LibreSSL,
call
.Xr tls_config_set_ca_file 3
with the path returned by
.Xr tls_default_ca_cert_file 3 .
All other behaviour should be identical.
.
.Pp
.Nm
targets the OpenSSL 1.1.1 series.
Due to a bug in OpenSSL,
only versions 1.1.1b and newer
are known to work.
.
.Ss Platform Support
.Nm
should work on the same platforms as
.Lk https://www.libressl.org/releases.html LibreSSL-portable ,
though it has not been thoroughly tested
on platforms other than
Linux,
.Fx
and macOS.
.
.Ss License
.Sy libtls
consists of all new code
developed as part of
.Ox
under
.Lk https://www.openbsd.org/policy.html "OpenBSD's preferred license"
of ISC.
Some
.Pa compat
sources are under the 3-clause BSD license
or the MIT license.
.
.Pp
.Nm
is not encumbered by the dual-licensing of OpenSSL
under both the OpenSSL license
and the original SSLeay license,
which are incompatible 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
.Nm
and OpenSSL
without additional permissions.
.
.Sh INSTALLING
To install from a release tarball,
run the following:
.Bd -literal -offset indent
\&./configure
make all
make install
.Ed
.
.Pp
To install from a git checkout,
.Sy autoconf ,
.Sy automake
and
.Sy libtool
are required.
Run the following before continuing
with the steps above:
.Bd -literal -offset indent
autoreconf -fi
.Ed
.
.Sh AUTHORS
.Nm
is maintained by
.An June Bug Aq Mt june@causal.agency .
.Pp
LibreSSL is developed by
.Lk https://www.openbsd.org "The OpenBSD project" .
.
.\" To view this file, run: man ./README.7