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