aboutsummaryrefslogtreecommitdiff
path: root/template/gnurl.html.j2
diff options
context:
space:
mode:
Diffstat (limited to 'template/gnurl.html.j2')
-rw-r--r--template/gnurl.html.j2463
1 files changed, 312 insertions, 151 deletions
diff --git a/template/gnurl.html.j2 b/template/gnurl.html.j2
index 73d62c8b..a193ae4d 100644
--- a/template/gnurl.html.j2
+++ b/template/gnurl.html.j2
@@ -1,181 +1,342 @@
1{% extends "common/base.j2" %} 1{% extends "common/base.j2" %}
2{% block body_content %} 2{% block body_content %}
3<article class="container"> 3 <article class="container">
4 4
5 <header> 5 <header>
6 <h1>gnurl (libgnurl)</h1> 6 <h1>gnurl (libgnurl)</h1>
7 </header> 7 </header>
8 8
9 <div class="container"> 9 <div class="container">
10 <p> 10 <p>
11 {% trans %}
12 libgnurl is a micro fork of libcurl. The goal of libgnurl
13 is to support only HTTP and HTTPS (and only HTTP 1.x) with
14 a single crypto backend (GnuTLS) to ensure a small footprint
15 and uniform experience for developers regardless of how
16 libcurl was compiled.<br>
17 Our main usecase is for GNUnet, but it might be usable for
18 others, hence we're releasing the code
19 to the general public.<br>
20 libgnurl is released under the same
21 license as libcurl. Please read the README for instructions, as you
22 must supply the correct options to configure to get a proper build of
23 libgnurl.
24 {% endtrans %}
25 </p>
26 <h3>{{_("Motivation") }}</h3>
27 <p>
28 {% trans %}
29 cURL supports many crypto backends. GNUnet requires the use of
30 GnuTLS, but other variants are used by some distributions. Supporting
31 other crypto backends would again expose us to a wider array of
32 security issues, may create licensing issues and most importantly
33 introduce new bugs as some crypto backends are known to introduce
34 subtle runtime issues. While it is possible to have two versions of
35 libcurl installed on the same system, this is error-prone, especially
36 as if we are linked against the wrong version, the bugs that arise
37 might be rather subtle.
38 {% endtrans %}
39 </p>
40 <p>
41 {% trans %} 11 {% trans %}
42 For GNUnet, we also need a particularly modern version of 12 libgnurl is a micro fork of libcurl. The goal of libgnurl
43 GnuTLS. Thus, it would anyway be necessary to recompile cURL for 13 is to support only HTTP and HTTPS (and only HTTP 1.x) with
44 GNUnet. But what happens if one links cURL against this version of 14 a single crypto backend (GnuTLS) to ensure a small footprint
45 GnuTLS? Well, first one would install GnuTLS by hand in the 15 and uniform experience for developers regardless of how
46 system. Then, we build cURL. cURL will build against it just fine, but 16 libcurl was compiled.<br>
47 the linker will eventually complain bitterly. The reason is that cURL 17 Our main usecase is for GNUnet, but it might be usable for
48 also links against a bunch of other system libraries (gssapi, ldap, 18 others, hence we're releasing the code
49 ssh2, rtmp, krb5, sasl2, see discussion on obscure protocols above), 19 to the general public.<br>
50 which --- as they are part of the distribution --- were linked against 20 libgnurl is released under the same
51 an older version of GnuTLS. As a result, the same binary would be 21 license as libcurl. Please read the README for instructions, as you
52 linked against two different versions of GnuTLS. That is typically a 22 must supply the correct options to configure to get a proper build of
53 recipe for disaster. Thus, in order to avoid updating a dozen system 23 libgnurl.
54 libraries (and having two versions of those installed), it is
55 necessary to disable all of those cURL features that GNUnet does not
56 use, and there are many of those. For GNUnet, the more obscure
57 protocols supported by cURL are close to dead code --- mostly
58 harmless, but not useful. However, as some application may use one of
59 those features, distributions are typically forced to enable all of
60 those features, and thus including security issues that might arise
61 from that code.
62 {% endtrans %} 24 {% endtrans %}
63 </p> 25 </p>
26 <h3>{{_("Motivation") }}</h3>
64 <p> 27 <p>
65 {% trans %} 28 {% trans %}
66 So to use a modern version of GnuTLS, a sane approach is to disable 29 cURL supports many crypto backends. GNUnet requires the use of
67 all of the "optional" features of cURL that drag in system libraries 30 GnuTLS, but other variants are used by some distributions. Supporting
68 that link against the older GnuTLS. That works, except that one should 31 other crypto backends would again expose us to a wider array of
69 then NEVER install that version of libcurl in say /usr or /usr/local, 32 security issues, may create licensing issues and most importantly
70 as that may break other parts of the system that might depend on these 33 introduce new bugs as some crypto backends are known to introduce
71 features that we just disabled. Libtool versioning doesn't help here, 34 subtle runtime issues. While it is possible to have two versions of
72 as it is not intended to deal with libraries that have optional 35 libcurl installed on the same system, this is error-prone, especially
73 features. Naturally, installing cURL somewhere else is also 36 as if we are linked against the wrong version, the bugs that arise
74 problematic, as we now need to be really careful that the linker will 37 might be rather subtle.
75 link GNUnet against the right version. Note that none of this can
76 really be trivially fixed by the cURL developers.
77 {% endtrans %} 38 {% endtrans %}
78 </p> 39 </p>
79 <h3>{{_("Rename to fix") }}</h3>
80 <p>
81 {% trans %}
82 How does forking fix it? Easy. First, we can get rid of all of the
83 compatibility issues --- if you use libgnurl, you state that you don't
84 need anything but HTTP/HTTPS. Those applications that need more,
85 should stick with the original cURL. Those that do not, can choose to
86 move to something simpler. As the library gets a new name, we do not
87 have to worry about tons of packages breaking as soon as one rebuilds
88 it. So renaming itself and saying that "libgnurl = libcurl with only
89 HTTP/HTTPS support and GnuTLS" fixes 99%% of the problems that darkened
90 my mood. Note that this pretty much CANNOT be done without a fork, as
91 renaming is an essential part of the fix. Now, there might be creative
92 solutions to achieve the same thing within the standard cURL build
93 system, but I'm not happy to wait for a decade for Daniel to review
94 the patches. The changes libgnurl makes to curl are miniscule and can
95 easily be applied again and again whenever libcurl makes a new
96 release.
97 {% endtrans %}
98 </p>
99 <h3>{{_("Using libgnurl") }}</h3>
100 <p>
101 {% trans %}
102 Projects that use cURL only for HTTP/HTTPS and that would work
103 with GnuTLS should be able to switch to libgnurl by changing
104 "-lcurl" to "-lgnurl". That's it. No changes to the source code
105 should be required,
106 as libgnurl strives for bug-for-bug compatibility with the
107 HTTP/HTTPS/GnuTLS subset of cURL.
108 We might add new features relating to this core subset if they
109 are proposed, but so far we have kept our changes minimal and
110 no additions to the original curl source have been written.
111 {% endtrans %}
112 </p>
113 <h4>{{_("Gotchas") }}</h4>
114 <p>
115 {% trans %}
116 libgnurl and gnurl are not intended to be used as a replacement
117 for curl for users. Since no conflicts in filenames should occur
118 you are not expected to remove curl to make use of gnurl and
119 viceversa.
120 {% endtrans %}
121 </p>
122 </div>
123
124 <div class="row container">
125 <div class="col-md">
126 <h3>{{ _("Source Code") }}</h3>
127 <p> 40 <p>
128 {% trans %} 41 {% trans %}
129 You can get the Gnurl Git repository using: 42 For GNUnet, we also need a particularly modern version of
130 <!-- 43 GnuTLS. Thus, it would anyway be necessary to recompile cURL for
131 https://bugs.gnunet.org/view.php?id=5483 ! 44 GNUnet. But what happens if one links cURL against this version of
132 <code>git clone https://git.taler.net/gnurl.git</code> 45 GnuTLS? Well, first one would install GnuTLS by hand in the
133 --> 46 system. Then, we build cURL. cURL will build against it just fine, but
134 <code>git clone git://git.taler.net/gnurl.git</code> 47 the linker will eventually complain bitterly. The reason is that cURL
135 The versions are checked in as signed git tags. 48 also links against a bunch of other system libraries (gssapi, ldap,
49 ssh2, rtmp, krb5, sasl2, see discussion on obscure protocols above),
50 which --- as they are part of the distribution --- were linked against
51 an older version of GnuTLS. As a result, the same binary would be
52 linked against two different versions of GnuTLS. That is typically a
53 recipe for disaster. Thus, in order to avoid updating a dozen system
54 libraries (and having two versions of those installed), it is
55 necessary to disable all of those cURL features that GNUnet does not
56 use, and there are many of those. For GNUnet, the more obscure
57 protocols supported by cURL are close to dead code --- mostly
58 harmless, but not useful. However, as some application may use one of
59 those features, distributions are typically forced to enable all of
60 those features, and thus including security issues that might arise
61 from that code.
136 {% endtrans %} 62 {% endtrans %}
137 </p> 63 </p>
138 </div>
139 <div class="col-md">
140 <h3>{{ _("Downloads") }}</h3>
141 <p> 64 <p>
142 {% trans %} 65 {% trans %}
143 Releases are published on <a href="https://ftp.gnu.org/gnu/gnunet/">ftp.gnu.org/gnu/gnunet</a>. 66 So to use a modern version of GnuTLS, a sane approach is to disable
144 gnURL is available from within a variety of distributions and package managers. 67 all of the "optional" features of cURL that drag in system libraries
145 Package Managers which include gnurl are: 68 that link against the older GnuTLS. That works, except that one should
146 <a href="https://www.gnu.org/software/guix/">GNU Guix</a> (available as "gnurl"), 69 then NEVER install that version of libcurl in say /usr or /usr/local,
147 <a href="https://gentoo.org">Gentoo</a> through the collaborative ebuild collection 70 as that may break other parts of the system that might depend on these
148 <a href="https://git.gnunet.org/youbroketheinternet-overlay.git/">youbroketheinternet</a>, 71 features that we just disabled. Libtool versioning doesn't help here,
149 <a href="https://nixos.org/nix/">Nix</a>, and <a href="http://pkgsrc.org">pkgsrc</a>. 72 as it is not intended to deal with libraries that have optional
73 features. Naturally, installing cURL somewhere else is also
74 problematic, as we now need to be really careful that the linker will
75 link GNUnet against the right version. Note that none of this can
76 really be trivially fixed by the cURL developers.
150 {% endtrans %} 77 {% endtrans %}
151 </p> 78 </p>
152 </div> 79 <h3>{{_("Rename to fix") }}</h3>
153 </div>
154
155 <div class="row container">
156 <div class="col-md">
157 <h3>{{ _("Reporting Bugs") }}</h3>
158 <p> 80 <p>
159 {% trans %} 81 {% trans %}
160 You can report bugs on our bug tracker: 82 How does forking fix it? Easy. First, we can get rid of all of the
161 <a href="https://bugs.gnunet.org/">bugs.gnunet.org</a>. Alternatively 83 compatibility issues --- if you use libgnurl, you state that you don't
162 you can use our bug mailinglist, but we prefer to track bugs 84 need anything but HTTP/HTTPS. Those applications that need more,
163 on the bugtracker. 85 should stick with the original cURL. Those that do not, can choose to
86 move to something simpler. As the library gets a new name, we do not
87 have to worry about tons of packages breaking as soon as one rebuilds
88 it. So renaming itself and saying that "libgnurl = libcurl with only
89 HTTP/HTTPS support and GnuTLS" fixes 99%% of the problems that darkened
90 my mood. Note that this pretty much CANNOT be done without a fork, as
91 renaming is an essential part of the fix. Now, there might be creative
92 solutions to achieve the same thing within the standard cURL build
93 system, but I'm not happy to wait for a decade for Daniel to review
94 the patches. The changes libgnurl makes to curl are miniscule and can
95 easily be applied again and again whenever libcurl makes a new
96 release.
164 {% endtrans %} 97 {% endtrans %}
165 </p> 98 </p>
166 </div> 99 <h3>{{_("Using libgnurl") }}</h3>
167 <div class="col-md"> 100 <p>
168 <h3>{{ _("Maintainer and Cryptographic signatures") }}</h3> 101 {% trans %}
102 Projects that use cURL only for HTTP/HTTPS and that would work
103 with GnuTLS should be able to switch to libgnurl by changing
104 "-lcurl" to "-lgnurl". That's it. No changes to the source code
105 should be required,
106 as libgnurl strives for bug-for-bug compatibility with the
107 HTTP/HTTPS/GnuTLS subset of cURL.
108 We might add new features relating to this core subset if they
109 are proposed, but so far we have kept our changes minimal and
110 no additions to the original curl source have been written.
111 {% endtrans %}
112 </p>
113 <h4>{{_("Gotchas") }}</h4>
169 <p> 114 <p>
170 {% trans %} 115 {% trans %}
171 gnurl/libgnurl is maintained by ng0. 116 libgnurl and gnurl are not intended to be used as a replacement
172 Releases are signed 117 for curl for users. Since no conflicts in filenames should occur
173 with the OpenPGP Key <b>A88C8ADD129828D7EAC02E52E22F9BBFEE348588</b>, 118 you are not expected to remove curl to make use of gnurl and
174 with the key fingerprint <b>A88C 8ADD 1298 28D7 EAC0 2E52 E22F 9BBF EE34 8588</b>. 119 viceversa.
175 {% endtrans %} 120 {% endtrans %}
176 </p> 121 </p>
177 </div> 122 </div>
178 </div>
179 123
180</article> <!-- /container --> 124 <div class="row container">
125 <div class="col-md">
126 <h3>{{ _("Source Code") }}</h3>
127 <p>
128 {% trans %}
129 You can get the gnurl git repository using:
130 {% endtrans %}
131 </p>
132 <ul>
133 <li>
134 <code>git clone https://git.taler.net/gnurl.git</code>
135 </li>
136 <li>
137 <code>git clone git://git.taler.net/gnurl.git</code>
138 </li>
139 </ul>
140 <p>
141 {% trans %}
142 The versions are checked in as (signed) git tags.
143 {% endtrans %}
144 </p>
145 </div>
146 <div class="col-md">
147 <h3>{{ _("Downloads") }}</h3>
148 <p>
149 {% trans %}
150 Releases are published on <a href="https://ftpmirror.gnu.org/gnu/gnunet/">ftpmirror.gnu.org/gnu/gnunet</a>.
151 gnurl is available from within a variety of distributions and package managers.
152 Package Managers which include gnurl are:
153 <a href="https://www.gnu.org/software/guix/">GNU Guix</a> (available as "gnurl"),
154 <a href="https://gentoo.org">Gentoo</a> through the collaborative ebuild collection
155 <a href="https://git.gnunet.org/youbroketheinternet-overlay.git/">youbroketheinternet</a>,
156 <a href="https://nixos.org/nix/">Nix</a>, and as www/gnurl in
157 <a href="https://pkgsrc.org">pkgsrc</a>.
158 {% endtrans %}
159 </p>
160 </div>
161 </div>
162
163 <div class="row container">
164 <div class="col-md">
165 <h3>{{ _("Building gnurl") }}</h3>
166 <p>
167 {% trans %}
168 We suggest to closely follow release announcements, as they
169 might indicate changes in how gnurl is to be build.
170 <br>
171 If your package manager provides a binary build or build
172 instructions to build gnurl from source automated and
173 integrated with your environment, we strongly suggest to use
174 this binary build.
175 <br>
176 There are two ways to build gnurl. The first one builds from
177 the most recent git tag, the second one uses the distributed
178 tarball. Distributors generally are supposed to build from
179 the tarball, but we describe both methods here. Both methods
180 are written with a NetBSD 9 userland in mind, substitute tools
181 as necessary.
182 <br>
183 You should <b>avoid</b> building gnurl from the tip of the
184 default git branch, as only tags are considered to be stable
185 and approved builds.
186 {% endtrans %}
187 </p>
188 <h4>{{ _("Building from the distributed tarball (prefered method)") }}</h4>
189 <p>
190 {% trans %}
191 If you want to verify the signature, install an OpenPGP compatible tool such
192 as security/gnupgp2 (and set it up). Assuming you use pkgin:
193 {% endtrans %}
194 </p>
195 <ul>
196 <li>
197 pkgin update
198 </li>
199 <li>
200 pkgin install gnupg2
201 </li>
202 </ul>
203 <p>
204 {% trans %}
205 Fetch the signature key from
206 {% endtrans %}
207 <a href="https://keys.openpgp.org/search?q=ng0%40n0.is">keys.openpgp.org</a>
208 {% trans %}
209 or via commandline with gnupg2.
210 {% endtrans %}
211 </p>
212 <p>
213 {% trans %}
214 Fetch the release, the signature, the checksum file as well as its signature:
215 {% endtrans %}
216 </p>
217 <ul>
218 <li>
219 ftp https://ftpmirror.gnu.org/gnu/gnunet/gnurl-7.65.3.tar.Z
220 </li>
221 <li>
222 ftp https://ftpmirror.gnu.org/gnu/gnunet/gnurl-7.65.3.tar.Z.sig
223 </li>
224 <li>
225 ftp https://ftpmirror.gnu.org/gnu.org/gnunet/gnurl-7.65.3.sum.txt
226 </li>
227 <li>
228 ftp https://ftpmirror.gnu.org/gnu.org/gnunet/gnurl-7.65.3.sum.txt.sig
229 </li>
230 </ul>
231 <p>
232 {% trans %}
233 verify the signatures, and verify the checksums against the
234 checksums in the .sum.txt file.
235 {% endtrans %}
236 </p>
237 <p>
238 {% trans %}
239 unpack the tarball:
240 {% endtrans %}
241 </p>
242 <ul>
243 <li>
244 tar -zxf gnurl-7.65.3.tar.Z
245 </li>
246 </ul>
247 <p>
248 {% trans %}
249 Change into the directory
250 {% endtrans %}
251 </p>
252 <ul>
253 <li>
254 cd gnurl-7.65.3
255 </li>
256 </ul>
257 <p>
258 {% trans %}
259 Now you can either run
260 {% endtrans %}
261 </p>
262 <ul>
263 <li>
264 ./configure
265 </li>
266 </ul>
267 <p>
268 {% trans %}
269 directly (and read configure-gnurl before you do so) or invoke
270 {% endtrans %}
271 </p>
272 <ul>
273 <li>
274 ./configure-gnurl
275 </li>
276 </ul>
277 <p>
278 {% trans %}
279 and pass additional parameters such as a custom PREFIX location.
280 Further reference can be the
281 {% endtrans %}
282 <a href="http://pkgsrc.se/www/gnurl">www/gnurl</a> Makefile.
283 {% trans %}
284 Now run
285 {% endtrans %}
286 </p>
287 <ul>
288 <li>
289 make
290 </li>
291 <li>
292 make check
293 {% trans %}
294 (this is optional)
295 {% endtrans %}
296 </li>
297 <li>
298 make install
299 </li>
300 </ul>
301 <p>
302 {% trans %}
303 and you are done.
304 {% endtrans %}
305 </p>
306 <h4>{{ _("Building from a tagged git commit") }}</h4>
307 <p>
308 {% trans %}
309 Follow the steps above, but instead of downloading the tarball,
310 clone the git tag you want to build from.
311 {% endtrans %}
312 </p>
313 </div>
314 </div>
315
316 <div class="row container">
317 <div class="col-md">
318 <h3>{{ _("Reporting Bugs") }}</h3>
319 <p>
320 {% trans %}
321 You can report bugs on our bug tracker:
322 <a href="https://bugs.gnunet.org/">bugs.gnunet.org</a>. Alternatively
323 you can use our bug mailinglist, but we prefer to track bugs
324 on the bugtracker.
325 {% endtrans %}
326 </p>
327 </div>
328 <div class="col-md">
329 <h3>{{ _("Maintainer and Cryptographic signatures") }}</h3>
330 <p>
331 {% trans %}
332 gnurl/libgnurl is maintained by ng0.
333 Releases are signed
334 with the OpenPGP Key <b>A88C8ADD129828D7EAC02E52E22F9BBFEE348588</b>,
335 with the key fingerprint <b>A88C 8ADD 1298 28D7 EAC0 2E52 E22F 9BBF EE34 8588</b>.
336 {% endtrans %}
337 </p>
338 </div>
339 </div>
340
341 </article> <!-- /container -->
181{% endblock body_content %} 342{% endblock body_content %}
generated by cgit v1.2.3 (git 2.39.1) at 2024-04-19 16:17:35 +0000