gnurl ===== gnurl / libgnurl is a fork of curl/libcurl with the following major changes: * Enforced 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 * We recommend to build GnuTLS with DANE support, provided by 'unbound'. This is optional. * Changes to the code: * renamed the library binary from 'libcurl' to 'lignurl' * renamed files to ensure a system-wide installation of libgnurl does not result in namespace collisions with libcurl * adjustments to the testsuite to address the gnurl specific build * dropped auto-generation of ngroff man page in favor of mdoc page, with the endgoal to drop the build-time dependency on groff and to provide a more appropriate documentation for gnurl. * enforced setting of built-in manual which is assembled at compile time through plain text dump of ngroff page. * some build-system additions: * python is detected through autotools instead of env(1). Usage notes ----------- * exported symbols were NOT renamed, so they all still have the curl prefix; you should be able to start using libgnurl simply by changing -lcurl to -lgnurl (and adjusting the header location). 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. Installation, Building ---------------------- Note that the compilation requirements are still not fully hardcoded, but work on this is in progress. The method which is applied at the moment after iterating through a couple of other methods, is to hard fail when unsupported switches are encountered. If you wan a shortcut, read (or install!) net/gnurl from pkgsrc (http://pkgsrc.org). The configure-gnurl file I included here which usually is up to date might serve as reference too. If you compile libgnurl, please pass '--disable-ntlm-wb' to the configure script. If you are a package maintainer: Do not enable the latest features curl likes to add, do not add libnghttp2 or libpsl support. Naturally, you're free to specify additional options, such as "--prefix". Please keep in mind that you might have to pass "--with-ca-bundle=/etc/ssl/certs/ca-certificates.crt" or similar paths and options for gnurl to pick up certificates, just like curl. The result should have support only for HTTP, HTTPS (via GnuTLS), IDN, zlib and TLS-SRP. The output of the result from ./gnurl --version should look like this: curl 7.58.0-DEV (x86_64-unknown-linux-gnu) libcurl/7.58.0-DEV GnuTLS/3.5.13 zlib/1.2.11 libidn2/2.0.4 Release-Date: [unreleased] Protocols: http https Features: AsynchDNS IDN IPv6 Largefile NTLM NTLM_WB SSL libz TLS-SRP UnixSockets HTTPS-proxy In previous versions (gnURL < 7.56.1-2) we used to socially enforce the following configuration, which was almost never done right on system distribution side: ./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 --disable-ares Initial 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. THANKS: gnURL was started within the GNUnet developer community, initiated by Christian Grothoff, with contributions by Jeff Burdges and Florian Dold. Maintenance and development since 7.52.0 (released 2016-12-21) is done by ng0. The developers of gnURL express their thanks to the cURL developer community. 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) SECURITY PROBLEMS Report suspected security problems via our HackerOne page and not in public! https://hackerone.com/curl 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.