Documentation updates. Separated big gnutls.texi to chapter to allow easier

maintainance.

1 files changed, 257 insertions, 0 deletions

diff --git a/doc/cha-preface.texi b/doc/cha-preface.texi
new file mode 100644
index 0000000000..1c4058bf45
--- /dev/null
+++ b/doc/cha-preface.texi
@@ -0,0 +1,257 @@
+@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