@node Preface
@chapter Preface

This document tries to demonstrate and explain the @acronym{GnuTLS}
library API.  A brief introduction to the protocols and the technology
involved, is also included so that an application programmer can
better understand the @acronym{GnuTLS} purpose and actual offerings.
Even if @acronym{GnuTLS} is a typical library software, it operates
over several security and cryptographic protocols, which require the
programmer to make careful and correct usage of them, otherwise he
risks to offer just a false sense of security. Security and the
network security terms are very general terms even for computer
software thus cannot be easily restricted to a single cryptographic
library.  For that reason, do not consider a program secure just
because it uses @acronym{GnuTLS}; there are several ways to compromise
a program or a communication line and @acronym{GnuTLS} only helps with
some of them.

Although this document tries to be self contained, basic network
programming and PKI knowlegde is assumed in most of it. A good
introduction to networking can be found in @xcite{STEVENS} and for
Public Key Infrastructure in @xcite{GUTPKI}.

@anchor{Availability}

Updated versions of the @acronym{GnuTLS} software and this document
will be available from @url{http://www.gnutls.org/} and
@url{http://www.gnu.org/software/gnutls/}.

@menu
* Getting help::
* Commercial Support::
* Downloading and Installing::
* Bug Reports::
* Contributing::
@end menu

@node Getting help
@section Getting Help

A mailing list where users may help each other exists, and you can
reach it by sending e-mail to @email{help-gnutls@@gnu.org}.  Archives
of the mailing list discussions, and an interface to manage
subscriptions, is available through the World Wide Web at
@url{http://lists.gnu.org/mailman/listinfo/help-gnutls}.

A mailing list for developers are also available, see
@url{http://www.gnu.org/software/gnutls/lists.html}.

Bug reports should be sent to @email{bug-gnutls@@gnu.org}, see
@xref{Bug Reports}.

@node Commercial Support
@section Commercial Support

Commercial support is available for users of GnuTLS.  The kind of
support that can be purchased may include:

@itemize

@item Implement new features.
Such as a new TLS extension.

@item Port GnuTLS to new platforms.
This could include porting to an embedded platforms that may need
memory or size optimization.

@item Integrating TLS as a security environment in your existing project.

@item System design of components related to TLS.

@end itemize

If you are interested, please write to:

@verbatim
Simon Josefsson Datakonsult
Hagagatan 24
113 47 Stockholm
Sweden

E-mail: simon@josefsson.org
@end verbatim

If your company provides support related to GnuTLS and would like to
be mentioned here, contact the author (@pxref{Bug Reports}).

@node Downloading and Installing
@section Downloading and Installing
@cindex Installation
@cindex Download

GnuTLS is available for download from the following URL:

@url{http://www.gnutls.org/download.html}

The latest version is stored in a file, e.g.,
@samp{gnutls-@value{VERSION}.tar.gz} where the @samp{@value{VERSION}}
value is the highest version number in the directory.

GnuTLS uses a Linux-like development cycle: even minor version numbers
indicate a stable release and a odd minor version number indicates a
development release.  For example, GnuTLS 1.6.3 denote a stable
release since 6 is even, and GnuTLS 1.7.11 denote a development
release since 7 is odd.

GnuTLS depends on Libgcrypt,
and you will need to install Libgcrypt
before installing GnuTLS.  Libgcrypt is available from
@url{ftp://ftp.gnupg.org/gcrypt/libgcrypt}.  Libgcrypt needs another
library, libgpg-error, and you need to install libgpg-error before
installing Libgcrypt.  Libgpg-error is available from
@url{ftp://ftp.gnupg.org/gcrypt/libgpg-error}.

Don't forget to verify the cryptographic signature after downloading
source code packages.

The package is then extracted, configured and built like many other
packages that use Autoconf.  For detailed information on configuring
and building it, refer to the @file{INSTALL} file that is part of the
distribution archive.  Typically you invoke @code{./configure} and
then @code{make check install}.  There are a number of compile-time
parameters, as discussed below.

The compression libraries (libz and lzo) are optional dependencies.
You can get libz from @url{http://www.zlib.net/}.  You can get lzo
from @url{http://www.oberhumer.com/opensource/lzo/}.

The X.509 part of GnuTLS needs ASN.1 functionality, from a library
called libtasn1.  A copy of libtasn1 is included in GnuTLS.  If you
want to install it separately (e.g., to make it possibly to use
libtasn1 in other programs), you can get it from
@url{http://www.gnu.org/software/gnutls/download.html}.

The OpenPGP part of GnuTLS uses a stripped down version of OpenCDK for
parsing OpenPGP packets.  It is included GnuTLS.  Use parameter
@code{--disable-openpgp-authentication} to disable the OpenPGP
functionality in GnuTLS.  Unfortunately, we didn't have resources to
maintain the code in a separate library.

Regarding the Guile bindings, there are additional installation
considerations, see @xref{Guile Preparations}.

A few @code{configure} options may be relevant, summarized in the
table.

@table @code

@item --disable-srp-authentication
@itemx --disable-psk-authentication
@itemx --disable-anon-authentication
@itemx --disable-extra-pki
@itemx --disable-openpgp-authentication
@itemx --disable-openssl-compatibility
Disable or enable particular features.  Generally not recommended.

@end table

For the complete list, refer to the output from @code{configure
--help}.

@node Bug Reports
@section Bug Reports
@cindex Reporting Bugs

If you think you have found a bug in GnuTLS, please investigate it and
report it.

@itemize @bullet

@item Please make sure that the bug is really in GnuTLS, and
preferably also check that it hasn't already been fixed in the latest
version.

@item You have to send us a test case that makes it possible for us to
reproduce the bug.

@item You also have to explain what is wrong; if you get a crash, or
if the results printed are not good and in that case, in what way.
Make sure that the bug report includes all information you would need
to fix this kind of bug for someone else.

@end itemize

Please make an effort to produce a self-contained report, with
something definite that can be tested or debugged.  Vague queries or
piecemeal messages are difficult to act on and don't help the
development effort.

If your bug report is good, we will do our best to help you to get a
corrected version of the software; if the bug report is poor, we won't
do anything about it (apart from asking you to send better bug
reports).

If you think something in this manual is unclear, or downright
incorrect, or if the language needs to be improved, please also send a
note.

Send your bug report to:

@center @samp{bug-gnutls@@gnu.org}

@node Contributing
@section Contributing
@cindex Contributing
@cindex Hacking

If you want to submit a patch for inclusion -- from solve a typo you
discovered, up to adding support for a new feature -- you should
submit it as a bug report (@pxref{Bug Reports}).  There are some
things that you can do to increase the chances for it to be included
in the official package.

Unless your patch is very small (say, under 10 lines) we require that
you assign the copyright of your work to the Free Software Foundation.
This is to protect the freedom of the project.  If you have not
already signed papers, we will send you the necessary information when
you submit your contribution.

For contributions that doesn't consist of actual programming code, the
only guidelines are common sense.  Use it.

For code contributions, a number of style guides will help you:

@itemize @bullet

@item Coding Style.
Follow the GNU Standards document (@pxref{top, GNU Coding Standards,,
standards}).

If you normally code using another coding standard, there is no
problem, but you should use @samp{indent} to reformat the code
(@pxref{top, GNU Indent,, indent}) before submitting your work.

@item Use the unified diff format @samp{diff -u}.

@item Return errors.
No reason whatsoever should abort the execution of the library.  Even
memory allocation errors, e.g. when malloc return NULL, should work
although result in an error code.

@item Design with thread safety in mind.
Don't use global variables.  Don't even write to per-handle global
variables unless the documented behaviour of the function you write is
to write to the per-handle global variable.

@item Avoid using the C math library.
It causes problems for embedded implementations, and in most
situations it is very easy to avoid using it.

@item Document your functions.
Use comments before each function headers, that, if properly
formatted, are extracted into Texinfo manuals and GTK-DOC web pages.

@item Supply a ChangeLog and NEWS entries, where appropriate.

@end itemize