[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1. Preface

This document tries to demonstrate and explain the 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 GnuTLS purpose and actual offerings. Even if 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 GnuTLS; there are several ways to compromise a program or a communication line and 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 [STEVENS] (see section Bibliography) and for Public Key Infrastructure in [GUTPKI] (see section Bibliography).

Updated versions of the GnuTLS software and this document will be available from http://www.gnutls.oa> and http://www.gnu.org/software/gnuta>.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.1 Getting Help

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

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

Bug reports should be sent to bug-gnutls@gnu.org, see See section Bug Reports.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2 Commercial Support

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

If you are interested, please write to:

Simon Josefsson Datakonsult
Hagagatan 24
113 47 Stockholm

E-mail: simon@josefsson.org

If your company provide support related to GnuTLS and would like to be mentioned here, contact the author (see section Bug Reports).

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3 Downloading and Installing

GnuTLS is available for download from the following URL:


The latest version is stored in a file, e.g., `gnutls-2.6.6.tar.gz' where the `2.6.6' 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 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 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 `INSTALL' file that is part of the distribution archive. Typically you invoke ./configure and then 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 http://www.zlib.na>. You can get lzo from http://www.oberhumer.com/opensource/la>.

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 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 --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 See section Guile Preparations.

A few configure options may be relevant, summarized in the table.


Disable or enable particular features. Generally not recommended.

For the complete list, refer to the output from configure --help.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4 Bug Reports

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

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:


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5 Contributing

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 (see section 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:

[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated on July, 20 2009 using texi2html 1.76.