summaryrefslogtreecommitdiff
path: root/README
blob: 36c3f7808c3d519f3d393086fca37d4e6bc2a12c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
GnuTLS README -- Important introductory notes.
Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007,
              2008, 2009, 2010  Free Software Foundation, Inc.
See the end of this document for copying conditions.

GnuTLS implements the TLS/SSL (Transport Layer Security aka Secure
Sockets Layer) protocol.  GnuTLS is a GNU project.  Additional
information can be found at <http://www.gnu.org/software/gnutls/>
and <http://www.gnutls.org/>.


README
------
This README is targeted for users of the library who build from
sources but do not necessarily develop.  If you are interested
in developing and contributing to the GnuTLS project, please
see README-alpha and visit
http://www.gnu.org/software/gnutls/manual/html_node/Contributing.html.


COMPILATION
-----------
A typical command sequence for building the library is shown below.
A complete list of options available for configure can be found
by running './configure --help'.

    cd gnutls-2.10.3
    ./configure --prefix=/usr
    make
    sudo make install

The commands above build and install the static archives (libgnutls.a
and libgnutls-extra.a), the shared object (libgnutls.so  and
libgnutls-extra.so), and additional binaries such as certtool and
gnutls-cli.

The library depends on libnettle OR libgcrypt (but never both).  GnuTLS
currently uses libnettle as the default cryptographic library.  Versions
2.10.3 and prior used libgcrypt as the default cryptographic library.
Nettle can be found at http://www.gnu.org/software/nettle/, while
libgcrypt can be found at <ftp://ftp.gnupg.org/pub/gcrypt/libgcrypt/>.

To configure libnettle for installation and use by GnuTLS, a typical
command sequence would be:

    cd nettle-2.1
    ./configure --prefix=/usr --disable-openssl --enable-shared
    make
    sudo make install

For the Nettle project, --enable-shared will instruct automake and
friends to build and install both the static archive (libnettle.a)
and the shared object (libnettle.so).

In case you are compiling for an embedded system, you can disable
unneeded features of GnuTLS.  In general, it is usually best not to
disable anything (for future mailing list questions and possible bugs).

Depending on your installation, additional libraries, such as libtasn1
and zlib, may be required.


DOCUMENTATION
-------------
See the documentation in doc/ and online at
http://www.gnu.org/software/gnutls/manual/html_node/index.htm.


EXAMPLES
--------
See the examples in doc/examples/ and online at 'How To Use GnuTLS in
Applications' at http://www.gnu.org/software/gnutls/manual/html_node/How-
to-use-GnuTLS-in-applications.html#How-to-use-GnuTLS-in-applications.
The examples include client, server, and multi-threaded examples.


SECURITY ADVISORIES
-------------------
The project collects and publishes information on past security
incidents and vulnerabilities.  Open information exchange, including
information which is [sometimes] suppressed in non-open or non-free
projects, is one of the goals of the GnuTLS project.  Please visit
http://www.gnu.org/software/gnutls/security.html.


MAILING LISTS
-------------
The GnuTLS project maintains mailing lists for users, developers, and
commits.  Please see http://www.gnu.org/software/gnutls/lists.html.


LICENSING
---------
Since version 0.4.2, the GnuTLS library has been released under the GNU
Lesser General Public License (LGPL).  Previous versions were licensed
under the GNU General Public License (GPL).

We changed the license for most of the GnuTLS components because other
free libraries exist and offer similar functionality with lax licenses.
We want GnuTLS to be usable in the same places as those other libraries.
We kept some parts of GnuTLS under the GPL because they are unique, and
the terms of the license under GPL provides free software projects (which
deserve our help) an advantage over non-free projects (which do not
deserve our help, since they refuse to share with us).  For information, see
http://www.gnu.org/philosophy/why-not-lgpl.html.

The GNU LPGL applies to the main gnutls library, while
the gnutls-extra library is under the GPL.  The gnutls-extra library
contains the code for "GnuTLS Inner Application" support and the
OpenSSL compatibility layer.  The gnutls library is located in the
lib/ directory, while the gnutls-extra library is at libextra/.


BUGS
----
Currently GnuTLS needs testing.  Thorough testing is very important and
expensive.  Often times, the developers do not have access to a particular
piece of hardware or configuration to reproduce a scenario.  Notifying
the developers about a possible bug will greatly help the project.  

If you believe you have found a bug, please report it to bug-gnutls@gnu.org
together with any applicable information.  A web interface for the system
is available at http://savannah.gnu.org/support/?group=gnutls.

Applicable information would include why the issue is a GnuTLS bug (if
not readily apparent), output from 'uname -a', the version of the library or
tool being used, a stack trace if available ('bt full' if under gdb), and
perhaps a network trace.  Vague queries or piecemeal messages are difficult
to act upon and don't help the development effort.

Additional information can be found at the project's Bug Report page at
http://www.gnu.org/software/gnutls/manual/html_node/Bug-Reports.html.


PATCHES
-------
Patches are welcome and encouraged.  Details of contributing can be found
at http://www.gnu.org/software/gnutls/manual/html_node/Contributing.html.

Patches are submitted through the bug tracking system or to the
mailing list.  When submitting patches, please be sure to use sources
from the git repository, and preferrably from the master branch.  To
create a patch for the project from a local git repository, please use
the following commands.  'gnutls' should be the local directory of a
previous git clone.

    cd gnutls
    git add the-file-you-modified.c another-file.c
    git commit the-file-you-modified.c another-file.c
    git format-patch

For more information on use of Git, visit http://git-scm.com/

----------------------------------------------------------------------
Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved.