summaryrefslogtreecommitdiff
path: root/template/gnurl.html.j2
blob: 80fbd4aad730db6e7f45f245e2715817fc8879b0 (plain)
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
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
{% extends "common/base.j2" %}
{% block body_content %}
<div class="container-fluid">
  <article>
    <h1>{{ _("gnurl (libgnurl)") }}</h1>
    <p>
      {% trans %}
      libgnurl is a micro fork of libcurl. The goal of libgnurl
      is to support only HTTP and HTTPS (and only HTTP 1.x) with
      a single crypto backend (GnuTLS) to ensure a small footprint
      and uniform experience for developers regardless of how
      libcurl was compiled.<br>
      Our main usecase is for GNUnet, but it might be usable for
      others, hence we're releasing the code
      to the general public.<br>
      libgnurl is released under the same
      license as libcurl. Please read the README for instructions, as you
      must supply the correct options to configure to get a proper build of
      libgnurl.
      {% endtrans %}
    </p>
    <h3>{{_("Motivation") }}</h3>
    <p>
      {% trans %}
      cURL supports many crypto backends. GNUnet requires the use of
      GnuTLS, but other variants are used by some distributions. Supporting
      other crypto backends would again expose us to a wider array of
      security issues, may create licensing issues and most importantly
      introduce new bugs as some crypto backends are known to introduce
      subtle runtime issues. While it is possible to have two versions of
      libcurl installed on the same system, this is error-prone, especially
      as if we are linked against the wrong version, the bugs that arise
      might be rather subtle.
      {% endtrans %}
    </p>
    <p>
        {% trans %}
	For GNUnet, we also need a particularly modern version of
	GnuTLS. Thus, it would anyway be necessary to recompile cURL for
	GNUnet. But what happens if one links cURL against this version of
	GnuTLS? Well, first one would install GnuTLS by hand in the
	system. Then, we build cURL. cURL will build against it just fine, but
	the linker will eventually complain bitterly. The reason is that cURL
	also links against a bunch of other system libraries (gssapi, ldap,
	ssh2, rtmp, krb5, sasl2, see discussion on obscure protocols above),
	which --- as they are part of the distribution --- were linked against
	an older version of GnuTLS. As a result, the same binary would be
	linked against two different versions of GnuTLS. That is typically a
	recipe for disaster. Thus, in order to avoid updating a dozen system
	libraries (and having two versions of those installed), it is
	necessary to disable all of those cURL features that GNUnet does not
	use, and there are many of those. For GNUnet, the more obscure
	protocols supported by cURL are close to dead code --- mostly
	harmless, but not useful. However, as some application may use one of
	those features, distributions are typically forced to enable all of
	those features, and thus including security issues that might arise
	from that code.
        {% endtrans %}
      </p>
      <p>
        {% trans %}
	So to use a modern version of GnuTLS, a sane approach is to disable
	all of the "optional" features of cURL that drag in system libraries
	that link against the older GnuTLS. That works, except that one should
	then NEVER install that version of libcurl in say /usr or /usr/local,
	as that may break other parts of the system that might depend on these
	features that we just disabled. Libtool versioning doesn't help here,
	as it is not intended to deal with libraries that have optional
	features. Naturally, installing cURL somewhere else is also
	problematic, as we now need to be really careful that the linker will
	link GNUnet against the right version. Note that none of this can
	really be trivially fixed by the cURL developers.
        {% endtrans %}
      </p>
      <h3>{{_("Rename to fix") }}</h3>
    <p>
    {% trans %}
    How does forking fix it? Easy. First, we can get rid of all of the
    compatibility issues --- if you use libgnurl, you state that you don't
    need anything but HTTP/HTTPS. Those applications that need more,
    should stick with the original cURL. Those that do not, can choose to
    move to something simpler. As the library gets a new name, we do not
    have to worry about tons of packages breaking as soon as one rebuilds
    it. So renaming itself and saying that "libgnurl = libcurl with only
    HTTP/HTTPS support and GnuTLS" fixes 99%% of the problems that darkened
    my mood. Note that this pretty much CANNOT be done without a fork, as
    renaming is an essential part of the fix. Now, there might be creative
    solutions to achieve the same thing within the standard cURL build
    system, but I'm not happy to wait for a decade for Daniel to review
    the patches. The changes libgnurl makes to curl are miniscule and can
    easily be applied again and again whenever libcurl makes a new
    release.
      {% endtrans %}
    </p>
    <h3>{{_("Using libgnurl") }}</h3>
    <p>
      {% trans %}
      Projects that use cURL only for HTTP/HTTPS and that would work
      with GnuTLS should be able to switch to libgnurl by changing
      "-lcurl" to "-lgnurl". That's it. No changes to the source code
      should be required,
      as libgnurl strives for bug-for-bug compatibility with the
      HTTP/HTTPS/GnuTLS subset of cURL.
      We might add new features relating to this core subset if they
      are proposed, but so far we have kept our changes minimal and
      no additions to the original curl source have been written.
      {% endtrans %}
    </p>
    <h4>{{_("Gotchas") }}</h4>
    <p>
      {% trans %}
      libgnurl and gnurl are not intended to be used as a replacement
      for curl for users. Since no conflicts in filenames should occur
      you are not expected to remove curl to make use of gnurl and
      viceversa.
      {% endtrans %}
    </p>
  </article>
</div>

<div class="container adorn_h3_bracket">
  <div class="row">
    <div class="col-lg-6">
      <h3>{{ _("Source Code") }}</h3>
      <p>
        {% trans %}
	You can get the Gnurl Git repository using:
	<code>git clone https://git.taler.net/gnurl.git</code>
	The versions are checked in as signed git tags.
        {% endtrans %}
      </p>
    </div>
    <div class="col-lg-6">
      <h3>{{ _("Downloads") }}</h3>
      <p>
        {% trans %}
	Releases are published on <a href="https://ftp.gnu.org/gnu/gnunet/">ftp.gnu.org/gnu/gnunet</a>.
	gnURL is available from within a variety of distributions and package managers.
	Package Managers which include gnurl are:
        <a href="https://gnu.org/s/guix">GNU Guix</a> (available as "gnurl"),
	<a href="https://gentoo.org">Gentoo</a> through the collaborative ebuild collection
	<a href="https://git.gnunet.org/youbroketheinternet-overlay.git/">youbroketheinternet</a>,
        <a href=https://nixos.org/nix">Nix</a>, and <a href="http://pkgsrc.org">pkgsrc</a>.
        {% endtrans %}
      </p>
    </div>
  </div>
  <div class="row">
    <div class="col-lg-6">
      <h3>{{ _("Reporting Bugs") }}</h3>
      <p>
        {% trans %}
	You can report bugs on our bug tracker:
	<a href="https://bugs.gnunet.org/">bugs.gnunet.org</a>. Alternatively
	you can use our bug mailinglist, but we prefer to track bugs
	on the bugtracker.
        {% endtrans %}
      </p>
    </div>
    <div class="col-lg-6">
      <h3>{{ _("Maintainer and Cryptographic signatures") }}</h3>
      <p>
        {% trans %}
	gnur/libgnurl is maintained by ng0.
	Releases are signed
	with the OpenPG Key <b>A88C8ADD129828D7EAC02E52E22F9BBFEE348588</b>,
	with the key fingerprint <b>A88C 8ADD 1298 28D7 EAC0  2E52 E22F 9BBF EE34 8588</b>.
        {% endtrans %}
      </p>
    </div>
  </div>
</div>

</div> <!-- /container -->
{% endblock body_content %}