doc: Add README

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