diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 131 |
1 files changed, 131 insertions, 0 deletions
@@ -1,3 +1,134 @@ +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... + + _ _ ____ _ ___| | | | _ \| | / __| | | | |_) | | |