README

   1 GnuTLS README -- Important introductory notes.
   2 Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007,
   3               2008, 2009, 2010  Free Software Foundation, Inc.
   4 See the end of this document for copying conditions.
   5
   6 GnuTLS implements the TLS/SSL (Transport Layer Security aka Secure
   7 Sockets Layer) protocol.  GnuTLS is a GNU project.  Additional
   8 information can be found at <http://www.gnu.org/software/gnutls/>
   9 and <http://www.gnutls.org/>.
  10
  11
  12 README
  13 ------
  14 This README is targeted for users of the library who build from
  15 sources but do not necessarily develop.  If you are interested
  16 in developing and contributing to the GnuTLS project, please
  17 see README-alpha and visit
  18 http://www.gnu.org/software/gnutls/manual/html_node/Contributing.html.
  19
  20
  21 COMPILATION
  22 -----------
  23 A typical command sequence for building the library is shown below.
  24 A complete list of options available for configure can be found
  25 by running './configure --help'.
  26
  27     cd gnutls-2.10.3
  28     ./configure --prefix=/usr
  29     make
  30     sudo make install
  31
  32 The commands above build and install the static archives (libgnutls.a
  33 and libgnutls-extra.a), the shared object (libgnutls.so  and
  34 libgnutls-extra.so), and additional binaries such as certtool and
  35 gnutls-cli.
  36
  37 The library depends on libnettle OR libgcrypt (but never both), as well
  38 as p11-kit.  GnuTLS currently uses libnettle as the default cryptographic
  39 library.  Versions 2.10.3 and prior used libgcrypt as the default
  40 cryptographic library. Nettle can be found at http://www.gnu.org/software/nettle/,
  41 while libgcrypt can be found at <ftp://ftp.gnupg.org/pub/gcrypt/libgcrypt/>.
  42 p11-kit can be found at <http://p11-glue.freedesktop.org/p11-kit.html>.
  43
  44
  45 To configure libnettle for installation and use by GnuTLS, a typical
  46 command sequence would be:
  47
  48     cd nettle-2.2
  49     ./configure --prefix=/usr --disable-openssl --enable-shared
  50     make
  51     sudo make install
  52
  53 For the Nettle project, --enable-shared will instruct automake and
  54 friends to build and install both the static archive (libnettle.a)
  55 and the shared object (libnettle.so).
  56
  57 In case you are compiling for an embedded system, you can disable
  58 unneeded features of GnuTLS.  In general, it is usually best not to
  59 disable anything (for future mailing list questions and possible bugs).
  60
  61 Depending on your installation, additional libraries, such as libtasn1
  62 and zlib, may be required.
  63
  64
  65 DOCUMENTATION
  66 -------------
  67 See the documentation in doc/ and online at
  68 http://www.gnu.org/software/gnutls/manual/html_node/index.htm.
  69
  70
  71 EXAMPLES
  72 --------
  73 See the examples in doc/examples/ and online at 'How To Use GnuTLS in
  74 Applications' at http://www.gnu.org/software/gnutls/manual/html_node/How-
  75 to-use-GnuTLS-in-applications.html#How-to-use-GnuTLS-in-applications.
  76 The examples include client, server, and multi-threaded examples.
  77
  78
  79 SECURITY ADVISORIES
  80 -------------------
  81 The project collects and publishes information on past security
  82 incidents and vulnerabilities.  Open information exchange, including
  83 information which is [sometimes] suppressed in non-open or non-free
  84 projects, is one of the goals of the GnuTLS project.  Please visit
  85 http://www.gnu.org/software/gnutls/security.html.
  86
  87
  88 MAILING LISTS
  89 -------------
  90 The GnuTLS project maintains mailing lists for users, developers, and
  91 commits.  Please see http://www.gnu.org/software/gnutls/lists.html.
  92
  93
  94 LICENSING
  95 ---------
  96 Since version 0.4.2, the GnuTLS library has been released under the GNU
  97 Lesser General Public License (LGPL).  Previous versions were licensed
  98 under the GNU General Public License (GPL).
  99
 100 We changed the license for most of the GnuTLS components because other
 101 free libraries exist and offer similar functionality with lax licenses.
 102 We want GnuTLS to be usable in the same places as those other libraries.
 103 We kept some parts of GnuTLS under the GPL because they are unique, and
 104 the terms of the license under GPL provides free software projects (which
 105 deserve our help) an advantage over non-free projects (which do not
 106 deserve our help, since they refuse to share with us).  For information, see
 107 http://www.gnu.org/philosophy/why-not-lgpl.html.
 108
 109 The GNU LPGL applies to the main gnutls library, while
 110 the gnutls-extra library is under the GPL.  The gnutls-extra library
 111 contains the code for "GnuTLS Inner Application" support and the
 112 OpenSSL compatibility layer.  The gnutls library is located in the
 113 lib/ directory, while the gnutls-extra library is at libextra/.
 114
 115
 116 BUGS
 117 ----
 118 Currently GnuTLS needs testing.  Thorough testing is very important and
 119 expensive.  Often times, the developers do not have access to a particular
 120 piece of hardware or configuration to reproduce a scenario.  Notifying
 121 the developers about a possible bug will greatly help the project.
 122
 123 If you believe you have found a bug, please report it to bug-gnutls@gnu.org
 124 together with any applicable information.  A web interface for the system
 125 is available at http://savannah.gnu.org/support/?group=gnutls.
 126
 127 Applicable information would include why the issue is a GnuTLS bug (if
 128 not readily apparent), output from 'uname -a', the version of the library or
 129 tool being used, a stack trace if available ('bt full' if under gdb), and
 130 perhaps a network trace.  Vague queries or piecemeal messages are difficult
 131 to act upon and don't help the development effort.
 132
 133 Additional information can be found at the project's Bug Report page at
 134 http://www.gnu.org/software/gnutls/manual/html_node/Bug-Reports.html.
 135
 136
 137 PATCHES
 138 -------
 139 Patches are welcome and encouraged.  Details of contributing can be found
 140 at http://www.gnu.org/software/gnutls/manual/html_node/Contributing.html.
 141
 142 Patches are submitted through the bug tracking system or to the
 143 mailing list.  When submitting patches, please be sure to use sources
 144 from the git repository, and preferrably from the master branch.  To
 145 create a patch for the project from a local git repository, please use
 146 the following commands.  'gnutls' should be the local directory of a
 147 previous git clone.
 148
 149     cd gnutls
 150     git add the-file-you-modified.c another-file.c
 151     git commit the-file-you-modified.c another-file.c
 152     git format-patch
 153
 154 For more information on use of Git, visit http://git-scm.com/
 155
 156 ----------------------------------------------------------------------
 157 Copying and distribution of this file, with or without modification,
 158 are permitted in any medium without royalty provided the copyright
 159 notice and this notice are preserved.