gnurl (libgnurl)

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.

Our main usecase is for GNUnet and Taler, but it might be usable for others, hence we're releasing the code to the general public.

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.

About gnurl

Large parts of the following 6 paragraphs are old and need to be rewritten.

Motivation

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.

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.

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.

Rename to fix

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 this was deemed to be too much work when gnurl was originally started. The changes libgnurl makes to curl are miniscule and can easily be applied again and again whenever libcurl makes a new release.

Using libgnurl

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.

Gotchas

libgnurl and gnurl are not intended to be used as a replacement for curl for users:
This does not mean there is no confidence in the work done with gnurl, it means that tools which expect curl or libcurl will not make use of a different named binary and library. If you know what you are doing, you should be able to use gnurl as part of your tooling in place of curl. We do not recommend to do so however, as the only usage it is tested for so far is as part of Taler's and GNunet's build-system.
Since no conflicts in filenames occur you are not expected to remove curl to make use of gnurl and viceversa.

Source Code

You can get the gnurl git repository using:

• git clone https://git.taler.net/gnurl.git
• git clone git://git.taler.net/gnurl.git

The versions are checked in as (signed) git tags.

Downloads

Releases are published on ftpmirror.gnu.org/gnu/gnunet. gnurl is available from within a variety of distributions and package managers. Some Package Managers which include gnurl are: GNU Guix (available as "gnurl"), Gentoo through the collaborative ebuild collection youbroketheinternet, Nix, and as www/gnurl in pkgsrc.

Building gnurl

We suggest to closely follow release announcements, as they might indicate changes in how gnurl is to be build.
If your package manager provides a binary build or build instructions to build gnurl from source automated and integrated with your environment, we strongly suggest to use this binary build.
There are two ways to build gnurl. The first one builds from the most recent git tag, the second one uses the distributed tarball. Distributors generally are supposed to build from the tarball, but we describe both methods here. Both methods are written with a NetBSD 9 userland in mind, substitute tools as necessary.
You should avoid building gnurl from the tip of the default git branch, as only tags are considered to be stable and approved builds.

Building from the distributed tarball (prefered method)

If you want to verify the signature, install an OpenPGP compatible tool such as security/gnupgp2 (and set it up). Assuming you use pkgin:

• pkgin update
• pkgin install gnupg2

Fetch the signature key from keys.openpgp.org or via commandline with gnupg2.

Fetch the release, the signature, the checksum file as well as its signature:

• ftp https://ftpmirror.gnu.org/gnu/gnunet/gnurl-7.65.3.tar.Z
• ftp https://ftpmirror.gnu.org/gnu/gnunet/gnurl-7.65.3.tar.Z.sig
• ftp https://ftpmirror.gnu.org/gnu.org/gnunet/gnurl-7.65.3.sum.txt
• ftp https://ftpmirror.gnu.org/gnu.org/gnunet/gnurl-7.65.3.sum.txt.sig

verify the signatures, and verify the checksums against the checksums in the .sum.txt file.

unpack the tarball:

• tar -zxf gnurl-7.65.3.tar.Z

Change into the directory

• cd gnurl-7.65.3

Now you can either run

• ./configure

directly (and read configure-gnurl before you do so) or invoke

• ./configure-gnurl

and pass additional parameters such as a custom PREFIX location. Further reference can be the www/gnurl Makefile. Now run

• make
• make check (this is optional)
• make install

and you are done.

Building from a tagged git commit

Follow the steps above, but instead of downloading the tarball, clone the git tag you want to build from.

Reporting Bugs

You can report bugs on our bug tracker: bugs.gnunet.org. Alternatively you can use our bug mailinglist, but we prefer to track bugs on the bugtracker.

Maintainer and Cryptographic signatures

gnurl/libgnurl is looking for a new maintainer. Releases after version 7.69.1 and up to version 7.72.0 were signed with the OpenPGP Key 0xD6B570842F7E7F8D (keys.openpgp.org), with the key fingerprint 6115 012D EA30 26F6 2A98 A556 D6B5 7084 2F7E 7F8D.