path: root/README

libgnurl is a fork of libcurl with the following major changes:

Compilation requirements:
* libgnurl must be compiled so that it supports only HTTP and HTTPS
  (remove Gopher, SSH, IMAP, etc.)
* libgnurl must be compiled so that it supports only GnuTLS
  (remove CaySSL, QsoSSL, GSKit, etc.)
* removed support for NTLM, GSSAPI, SPNEGO, LDAP, metalink, HTTP2

Changes to the code:
* renamed the library binary from 'libcurl' to 'lignurl'
* adjustments to the testsuite, deleted tests/data/test1139

Usage notes:
* exported symbols were NOT renamed, so they still all have the
  curl prefix; you should be able to start using libgnurl simply
  by changing -lcurl to -lgnurl.

Note that the compilation requirements were not hard-coded, but
are rather socially enforced: if you compile libgnurl, please
use the following options to configure:

./configure --enable-ipv6 --with-gnutls --without-libssh2 \
--without-libmetalink --without-winidn --without-librtmp \
--without-nghttp2 --without-nss --without-cyassl \
--without-polarssl --without-ssl --without-winssl \
--without-darwinssl --disable-sspi --disable-ntlm-wb --disable-ldap \
--disable-rtsp --disable-dict --disable-telnet --disable-tftp \
--disable-pop3 --disable-imap --disable-smtp --disable-gopher \
--disable-file --disable-ftp --disable-smb

Naturally, you're free to specify additional options, such as
"--prefix".  The result should have support only for HTTP, HTTPS (via
GnuTLS), IDN, zlib and TLS-SRP.



Motivation:

cURL supports a bunch of 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

At this point, developers that don't want to rebuild an entire
distribution from scratch get grumpy. Grumpy developers do silly
things, like forking code to fix it. I called the fork gnurl (to be
pronounced with a grumpy voice and an emphasis on the R) as it is bits
of cURL, a bit more GNUish, for GnuNet, and gnurl can be pronounced to
indicate the grumpy origins.

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.


Summary:

I want to note that the main motiviations for this fork are technical
The goal of the cURL project is clearly to support many crypto
backends and many protocols. That is a worthy goal, and I wish them
luck with it. The goal for 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.


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.  Continue to read the cURL documentation --- as libgnurl
strives for bug-for-bug compatibility with the HTTP/HTTPS/GnuTLS
subset of cURL.  However, we're happy to add new features relating to
this core subset and might be easier to convince than the cURL
developers. ;-)

Now, on to the cURL documentation...


                                  _   _ ____  _
                              ___| | | |  _ \| |
                             / __| | | | |_) | |
                            | (__| |_| |  _ <| |___
                             \___|\___/|_| \_\_____|

README

  Curl is a command line tool for transferring data specified with URL
  syntax. Find out how to use curl by reading the curl.1 man page or the
  MANUAL document. Find out how to install Curl by reading the INSTALL
  document.

  libcurl is the library curl is using to do its job. It is readily
  available to be used by your software. Read the libcurl.3 man page to
  learn how!

  You find answers to the most frequent questions we get in the FAQ document.

  Study the COPYING file for distribution terms and similar. If you distribute
  curl binaries or other binaries that involve libcurl, you might enjoy the
  LICENSE-MIXING document.

CONTACT

  If you have problems, questions, ideas or suggestions, please contact us
  by posting to a suitable mailing list. See https://curl.haxx.se/mail/

  All contributors to the project are listed in the THANKS document.

WEB SITE

  Visit the curl web site for the latest news and downloads:

        https://curl.haxx.se/

GIT

  To download the very latest source off the GIT server do this:

    git clone https://github.com/curl/curl.git

  (you'll get a directory named curl created, filled with the source code)

NOTICE

  Curl contains pieces of source code that is Copyright (c) 1998, 1999
  Kungliga Tekniska Högskolan. This notice is included here to comply with the
  distribution terms.