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