1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
.Dd February 27, 2022
.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.
.Nm
is compatible with OpenSSL 3.0.0
but hasn't been ported
away from deprecated APIs.
.
.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 McEnroe 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
|