doc/cha-preface.texi

   1 @node Preface
   2 @chapter Preface
   3
   4 This document tries to demonstrate and explain the @acronym{GnuTLS}
   5 library API.  A brief introduction to the protocols and the technology
   6 involved, is also included so that an application programmer can
   7 better understand the @acronym{GnuTLS} purpose and actual offerings.
   8 Even if @acronym{GnuTLS} is a typical library software, it operates
   9 over several security and cryptographic protocols, which require the
  10 programmer to make careful and correct usage of them, otherwise he
  11 risks to offer just a false sense of security. Security and the
  12 network security terms are very general terms even for computer
  13 software thus cannot be easily restricted to a single cryptographic
  14 library.  For that reason, do not consider a program secure just
  15 because it uses @acronym{GnuTLS}; there are several ways to compromise
  16 a program or a communication line and @acronym{GnuTLS} only helps with
  17 some of them.
  18
  19 Although this document tries to be self contained, basic network
  20 programming and PKI knowlegde is assumed in most of it. A good
  21 introduction to networking can be found in @xcite{STEVENS} and for
  22 Public Key Infrastructure in @xcite{GUTPKI}.
  23
  24 @anchor{Availability}
  25
  26 Updated versions of the @acronym{GnuTLS} software and this document
  27 will be available from @url{http://www.gnutls.org/} and
  28 @url{http://www.gnu.org/software/gnutls/}.
  29
  30 @menu
  31 * Getting help::
  32 * Commercial Support::
  33 * Downloading and Installing::
  34 * Bug Reports::
  35 * Contributing::
  36 @end menu
  37
  38 @node Getting help
  39 @section Getting Help
  40
  41 A mailing list where users may help each other exists, and you can
  42 reach it by sending e-mail to @email{help-gnutls@@gnu.org}.  Archives
  43 of the mailing list discussions, and an interface to manage
  44 subscriptions, is available through the World Wide Web at
  45 @url{http://lists.gnu.org/mailman/listinfo/help-gnutls}.
  46
  47 A mailing list for developers are also available, see
  48 @url{http://www.gnu.org/software/gnutls/lists.html}.
  49
  50 Bug reports should be sent to @email{bug-gnutls@@gnu.org}, see
  51 @xref{Bug Reports}.
  52
  53 @node Commercial Support
  54 @section Commercial Support
  55
  56 Commercial support is available for users of GnuTLS.  The kind of
  57 support that can be purchased may include:
  58
  59 @itemize
  60
  61 @item Implement new features.
  62 Such as a new TLS extension.
  63
  64 @item Port GnuTLS to new platforms.
  65 This could include porting to an embedded platforms that may need
  66 memory or size optimization.
  67
  68 @item Integrating TLS as a security environment in your existing project.
  69
  70 @item System design of components related to TLS.
  71
  72 @end itemize
  73
  74 If you are interested, please write to:
  75
  76 @verbatim
  77 Simon Josefsson Datakonsult
  78 Hagagatan 24
  79 113 47 Stockholm
  80 Sweden
  81
  82 E-mail: simon@josefsson.org
  83 @end verbatim
  84
  85 If your company provides support related to GnuTLS and would like to
  86 be mentioned here, contact the author (@pxref{Bug Reports}).
  87
  88 @node Downloading and Installing
  89 @section Downloading and Installing
  90 @cindex Installation
  91 @cindex Download
  92
  93 GnuTLS is available for download from the following URL:
  94
  95 @url{http://www.gnutls.org/download.html}
  96
  97 The latest version is stored in a file, e.g.,
  98 @samp{gnutls-@value{VERSION}.tar.gz} where the @samp{@value{VERSION}}
  99 value is the highest version number in the directory.
 100
 101 GnuTLS uses a Linux-like development cycle: even minor version numbers
 102 indicate a stable release and a odd minor version number indicates a
 103 development release.  For example, GnuTLS 1.6.3 denote a stable
 104 release since 6 is even, and GnuTLS 1.7.11 denote a development
 105 release since 7 is odd.
 106
 107 GnuTLS depends on Libgcrypt,
 108 and you will need to install Libgcrypt
 109 before installing GnuTLS.  Libgcrypt is available from
 110 @url{ftp://ftp.gnupg.org/gcrypt/libgcrypt}.  Libgcrypt needs another
 111 library, libgpg-error, and you need to install libgpg-error before
 112 installing Libgcrypt.  Libgpg-error is available from
 113 @url{ftp://ftp.gnupg.org/gcrypt/libgpg-error}.
 114
 115 Don't forget to verify the cryptographic signature after downloading
 116 source code packages.
 117
 118 The package is then extracted, configured and built like many other
 119 packages that use Autoconf.  For detailed information on configuring
 120 and building it, refer to the @file{INSTALL} file that is part of the
 121 distribution archive.  Typically you invoke @code{./configure} and
 122 then @code{make check install}.  There are a number of compile-time
 123 parameters, as discussed below.
 124
 125 The compression libraries (libz and lzo) are optional dependencies.
 126 You can get libz from @url{http://www.zlib.net/}.  You can get lzo
 127 from @url{http://www.oberhumer.com/opensource/lzo/}.
 128
 129 The X.509 part of GnuTLS needs ASN.1 functionality, from a library
 130 called libtasn1.  A copy of libtasn1 is included in GnuTLS.  If you
 131 want to install it separately (e.g., to make it possibly to use
 132 libtasn1 in other programs), you can get it from
 133 @url{http://www.gnu.org/software/gnutls/download.html}.
 134
 135 The OpenPGP part of GnuTLS uses a stripped down version of OpenCDK for
 136 parsing OpenPGP packets.  It is included GnuTLS.  Use parameter
 137 @code{--disable-openpgp-authentication} to disable the OpenPGP
 138 functionality in GnuTLS.  Unfortunately, we didn't have resources to
 139 maintain the code in a separate library.
 140
 141 Regarding the Guile bindings, there are additional installation
 142 considerations, see @xref{Guile Preparations}.
 143
 144 A few @code{configure} options may be relevant, summarized in the
 145 table.
 146
 147 @table @code
 148
 149 @item --disable-srp-authentication
 150 @itemx --disable-psk-authentication
 151 @itemx --disable-anon-authentication
 152 @itemx --disable-extra-pki
 153 @itemx --disable-openpgp-authentication
 154 @itemx --disable-openssl-compatibility
 155 Disable or enable particular features.  Generally not recommended.
 156
 157 @end table
 158
 159 For the complete list, refer to the output from @code{configure
 160 --help}.
 161
 162 @node Bug Reports
 163 @section Bug Reports
 164 @cindex Reporting Bugs
 165
 166 If you think you have found a bug in GnuTLS, please investigate it and
 167 report it.
 168
 169 @itemize @bullet
 170
 171 @item Please make sure that the bug is really in GnuTLS, and
 172 preferably also check that it hasn't already been fixed in the latest
 173 version.
 174
 175 @item You have to send us a test case that makes it possible for us to
 176 reproduce the bug.
 177
 178 @item You also have to explain what is wrong; if you get a crash, or
 179 if the results printed are not good and in that case, in what way.
 180 Make sure that the bug report includes all information you would need
 181 to fix this kind of bug for someone else.
 182
 183 @end itemize
 184
 185 Please make an effort to produce a self-contained report, with
 186 something definite that can be tested or debugged.  Vague queries or
 187 piecemeal messages are difficult to act on and don't help the
 188 development effort.
 189
 190 If your bug report is good, we will do our best to help you to get a
 191 corrected version of the software; if the bug report is poor, we won't
 192 do anything about it (apart from asking you to send better bug
 193 reports).
 194
 195 If you think something in this manual is unclear, or downright
 196 incorrect, or if the language needs to be improved, please also send a
 197 note.
 198
 199 Send your bug report to:
 200
 201 @center @samp{bug-gnutls@@gnu.org}
 202
 203 @node Contributing
 204 @section Contributing
 205 @cindex Contributing
 206 @cindex Hacking
 207
 208 If you want to submit a patch for inclusion -- from solve a typo you
 209 discovered, up to adding support for a new feature -- you should
 210 submit it as a bug report (@pxref{Bug Reports}).  There are some
 211 things that you can do to increase the chances for it to be included
 212 in the official package.
 213
 214 Unless your patch is very small (say, under 10 lines) we require that
 215 you assign the copyright of your work to the Free Software Foundation.
 216 This is to protect the freedom of the project.  If you have not
 217 already signed papers, we will send you the necessary information when
 218 you submit your contribution.
 219
 220 For contributions that doesn't consist of actual programming code, the
 221 only guidelines are common sense.  Use it.
 222
 223 For code contributions, a number of style guides will help you:
 224
 225 @itemize @bullet
 226
 227 @item Coding Style.
 228 Follow the GNU Standards document.
 229 @c (@pxref{top, GNU Coding Standards,,standards}).
 230
 231 If you normally code using another coding standard, there is no
 232 problem, but you should use @samp{indent} to reformat the code
 233 @c (@pxref{top, GNU Indent,, indent})
 234 before submitting your work.
 235
 236 @item Use the unified diff format @samp{diff -u}.
 237
 238 @item Return errors.
 239 No reason whatsoever should abort the execution of the library.  Even
 240 memory allocation errors, e.g. when malloc return NULL, should work
 241 although result in an error code.
 242
 243 @item Design with thread safety in mind.
 244 Don't use global variables.  Don't even write to per-handle global
 245 variables unless the documented behaviour of the function you write is
 246 to write to the per-handle global variable.
 247
 248 @item Avoid using the C math library.
 249 It causes problems for embedded implementations, and in most
 250 situations it is very easy to avoid using it.
 251
 252 @item Document your functions.
 253 Use comments before each function headers, that, if properly
 254 formatted, are extracted into Texinfo manuals and GTK-DOC web pages.
 255
 256 @item Supply a ChangeLog and NEWS entries, where appropriate.
 257
 258 @end itemize