diff options
| -rw-r--r-- | README.7 | 152 |
1 files changed, 152 insertions, 0 deletions
diff --git a/README.7 b/README.7 new file mode 100644 index 0000000..4df90b1 --- /dev/null +++ b/README.7 @@ -0,0 +1,152 @@ +.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. +. +.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 |