* Authentication methods::
* More on certificate authentication::
* How to use TLS in application protocols::
+* How to use GnuTLS in applications::
* Included programs::
* Function reference::
-* Error codes and descriptions::
+* Certificate to XML convertion functions::
+* All the supported ciphersuites in GnuTLS::
* Copying This Manual::
* Index::
@end menu
@node Preface
@chapter Preface
-@section Introduction
-
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
@url{http://www.cs.auckland.ac.nz/~pgut001/pubs/pkitutorial.pdf}} is a
good introduction to Public Key Infrastructure.
-@section Availability
+@anchor{Availability}
Updated versions of the @acronym{GnuTLS} software and this document
will be available from @url{http://www.gnutls.org/} and
@acronym{GnuTLS} library can be disabled at compile time. That way a
small library, with the required features, can be generated.
+@menu
+* General Idea::
+* Error handling::
+* Memory handling::
+* Callback functions::
+@end menu
+
+@node General Idea
@section General Idea
A brief description of how @acronym{GnuTLS} works internally is shown
the stored session will be retrieved, and the new session will be a
resumed one, and will share the same session ID with the previous one.
+@node Error handling
@section Error handling
In @acronym{GnuTLS} most functions return an integer type as a result. In
a function, these error codes will be documented in the function's
reference. @xref{Error Codes}, for all the error codes.
+@node Memory handling
@section Memory handling
@acronym{GnuTLS} internally handles heap allocated objects
secure. See the documentation of @acronym{Libgcrypt} for more
information.
+@node Callback functions
@section Callback functions
@cindex Callback functions
@end itemize
@node Introduction to TLS
-@chapter Introduction to TLS
+@chapter Introduction to @acronym{TLS}
@acronym{TLS} stands for ``Transport Layer Security'' and is the
successor of SSL, the Secure Sockets Layer protocol@footnote{Described
implemented in @acronym{GnuTLS} since they are not considered secure
today.
+@menu
+* TLS layers::
+* The transport layer::
+* The TLS record protocol::
+* The TLS Alert Protocol::
+* The TLS Handshake Protocol::
+* TLS Extensions::
+@end menu
+
+@node TLS layers
@section TLS layers
@cindex TLS Layers
@image{layers,12cm,8cm}
+@node The transport layer
@section The transport layer
@cindex Transport protocol
work, thus making it easy to add @acronym{TLS} support to existing
TCP/IP servers.
+@node The TLS record protocol
@section The TLS record protocol
@cindex Record protocol
no encryption, and no MAC is used. Encryption and authentication begin
just after the handshake protocol has finished.
+@menu
+* Encryption algorithms used in the record layer::
+* Compression algorithms used in the record layer::
+* Weaknesses and countermeasures::
+@end menu
+
+@node Encryption algorithms used in the record layer
@subsection Encryption algorithms used in the record layer
@cindex Symmetric encryption algorithms
@end itemize
+@node Compression algorithms used in the record layer
@subsection Compression algorithms used in the record layer
@cindex Compression algorithms
@end itemize
+@node Weaknesses and countermeasures
@subsection Weaknesses and countermeasures
Some weaknesses that may affect the security of the Record layer have
in @acronym{GnuTLS}. For a detailed discussion see the archives of the
TLS Working Group mailing list and the paper @cite{CBCATT}.
+@node The TLS Alert Protocol
@section The TLS Alert Protocol
@anchor{The Alert Protocol}
@cindex Alert protocol
@end itemize
+@node The TLS Handshake Protocol
@section The TLS Handshake Protocol
@anchor{The Handshake Protocol}
@cindex Handshake protocol
order to remove them, and save space. The function
@code{gnutls_db_check_entry} is provided for that reason.
+@node TLS Extensions
@section TLS Extensions
@cindex TLS Extensions
@end itemize
+@menu
+* Certificate authentication::
+* Anonymous authentication::
+* Authentication using SRP::
+* Authentication and credentials::
+* Parameters stored in credentials::
+@end menu
+
+@node Certificate authentication
@section Certificate authentication
@subsection Authentication using @acronym{X.509} certificates
@end itemize
+@node Anonymous authentication
@section Anonymous authentication
@cindex Anonymous authentication
@end itemize
+@node Authentication using SRP
@section Authentication using @acronym{SRP}
@cindex @acronym{SRP} authentication
manipulate the required parameters for @acronym{SRP} authentication is
also included. @xref{srptool}, for more information.
+@node Authentication and credentials
@section Authentication and credentials
In @acronym{GnuTLS} every key exchange method is associated with a
@end multitable
+@node Parameters stored in credentials
@section Parameters stored in credentials
Several parameters such as the ones used for Diffie-Hellman
@anchor{Certificate Authentication}
@cindex Certificate authentication
+@menu
+* The X.509 trust model::
+* The OpenPGP trust model::
+@end menu
+
+@node The X.509 trust model
@section The @acronym{X.509} trust model
-@anchor{The X.509 trust model}
@cindex @acronym{X.509} certificates
The @acronym{X.509} protocols rely on a hierarchical trust model. In
handling @acronym{X.509} certificates is described at section
@ref{sec:x509api}. Some examples are listed below.
+@menu
+* X.509 certificates::
+* Verifying X.509 certificate paths::
+* PKCS #10 certificate requests::
+* PKCS #12 structures::
+@end menu
+
+@node X.509 certificates
@subsection @acronym{X.509} certificates
An @acronym{X.509} certificate usually contains information about the
@file{gnutls/x509.h}. An example program to demonstrate the @acronym{X.509}
parsing capabilities can be found at section @ref{ex:x509-info}.
+@node Verifying X.509 certificate paths
@subsection Verifying @acronym{X.509} certificate paths
@cindex Verifying certificate paths
certificate's owner is the one you expect. See @cite{RFC2818} and
section @ref{ex:verify} for an example.
+@node PKCS #10 certificate requests
@subsection @acronym{PKCS} #10 certificate requests
@cindex Certificate requests
@cindex @acronym{PKCS} #10
using the @code{gnutls_x509_crq_t} type. An example of a certificate
request generation can be found at section @ref{ex:crq}.
+@node PKCS #12 structures
@subsection @acronym{PKCS} #12 structures
@cindex @acronym{PKCS} #12
An example of a @acronym{PKCS} #12 structure generation can be found
at section @ref{ex:pkcs12}.
+@node The OpenPGP trust model
@section The @acronym{OpenPGP} trust model
-@anchor{The OpenPGP trust model}
@cindex @acronym{OpenPGP} Keys
The @acronym{OpenPGP} key authentication relies on a distributed trust
@end itemize
@node How to use TLS in application protocols
-@chapter How to use TLS in application protocols
-
-@section Introduction
+@chapter How to use @acronym{TLS} in application protocols
This chapter is intended to provide some hints on how to use the
-@acronym{TLS} over simple custom made application protocols. The discussion
-below mainly refers to the @emph{TCP/IP} transport layer but may be
-extended to other ones too.
+@acronym{TLS} over simple custom made application protocols. The
+discussion below mainly refers to the @emph{TCP/IP} transport layer
+but may be extended to other ones too.
+
+@menu
+* Separate ports::
+* Upward negotiation::
+@end menu
+@node Separate ports
@section Separate ports
Traditionally @acronym{SSL} was used in application protocols by
is a limitation on the available privileged ports, this approach was
soon obsoleted.
+@node Upward negotiation
@section Upward negotiation
Other application protocols@footnote{See LDAP, IMAP etc.} use a
password file@footnote{in @acronym{SRP} authentication}, or anything
else!
+@node How to use GnuTLS in applications
@chapter How to use @acronym{GnuTLS} in applications
@anchor{examples}
@cindex Example programs
+@menu
+* Preparation::
+* Multi-threaded applications::
+* Client examples::
+* Server examples::
+* Miscellaneous examples::
+* Compatibility with the OpenSSL library::
+@end menu
+
+@node Preparation
@section Preparation
To use @acronym{GnuTLS}, you have to perform some changes to your
sources and your build system. The necessary changes are explained in
the following subsections.
+@menu
+* Headers::
+* Version check::
+* Building the source::
+@end menu
+
+@node Headers
@subsection Headers
All the data types and functions of the @acronym{GnuTLS} library are
available by including the header file @file{gnutls/extra.h} in your
programs.
+@node Version check
@subsection Version check
It is often desirable to check that the version of `gnutls' used is
want to check that the version is okay right after program startup.
See the function @code{gnutls_check_version}.
+@node Building the source
@subsection Building the source
If you want to compile a source file including the `gnutls/gnutls.h'
gcc -o foo foo.c `libgnutls-config --cflags --libs`
@end example
+@node Multi-threaded applications
@section Multi-threaded applications
Although the @acronym{GnuTLS} library is thread safe by design, some
@end example
@end itemize
+@node Client examples
@section Client examples
This section contains examples of @acronym{TLS} and @acronym{SSL}
clients, using @acronym{GnuTLS}. Note that these examples contain
little or no error checking.
+@menu
+* Simple client example with anonymous authentication::
+* Simple client example with X.509 certificate support::
+* Obtaining session information::
+* Verifying peer's certificate::
+* Using a callback to select the certificate to use::
+* Client with Resume capability example::
+* Simple client example with SRP authentication::
+@end menu
+
+@node Simple client example with anonymous authentication
@subsection Simple client example with anonymous authentication
The simplest client using TLS is the one that doesn't do any
@verbatiminclude examples/ex-client1.c
+@node Simple client example with X.509 certificate support
@subsection Simple client example with @acronym{X.509} certificate support
Let's assume now that we want to create a TCP client which
@verbatiminclude examples/ex-client2.c
+@node Obtaining session information
@subsection Obtaining session information
Most of the times it is desirable to know the security properties of
@verbatiminclude examples/ex-session-info.c
+@node Verifying peer's certificate
@subsection Verifying peer's certificate
@anchor{ex:verify}
@verbatiminclude examples/ex-verify.c
+@node Using a callback to select the certificate to use
@subsection Using a callback to select the certificate to use
There are cases where a client holds several certificate and key
@verbatiminclude examples/ex-cert-select.c
+@node Client with Resume capability example
@subsection Client with Resume capability example
@anchor{ex:resume-client}
@verbatiminclude examples/ex-client-resume.c
+@node Simple client example with SRP authentication
@subsection Simple client example with @acronym{SRP} authentication
The following client is a very simple @acronym{SRP} @acronym{TLS}
@verbatiminclude examples/ex-client-srp.c
+@node Server examples
@section Server examples
This section contains examples of @acronym{TLS} and @acronym{SSL}
servers, using @acronym{GnuTLS}.
+@menu
+* Echo Server with X.509 authentication::
+* Echo Server with X.509 authentication II::
+* Echo Server with OpenPGP authentication::
+* Echo Server with SRP authentication::
+* Echo Server with anonymous authentication::
+@end menu
+
+@node Echo Server with X.509 authentication
@subsection Echo Server with @acronym{X.509} authentication
This example is a very simple echo server which supports
@verbatiminclude examples/ex-serv1.c
+@node Echo Server with X.509 authentication II
@subsection Echo Server with @acronym{X.509} authentication II
The following example is a server which supports @acronym{X.509}
@verbatiminclude examples/ex-serv-export.c
-@subsection Echo Server with @acronym{OpenPGP}authentication
+@node Echo Server with OpenPGP authentication
+@subsection Echo Server with @acronym{OpenPGP} authentication
@cindex @acronym{OpenPGP} Server
The following example is an echo server which supports
@verbatiminclude examples/ex-serv-pgp.c
+@node Echo Server with SRP authentication
@subsection Echo Server with @acronym{SRP} authentication
This is a server which supports @acronym{SRP} authentication. It is
@verbatiminclude examples/ex-serv-srp.c
+@node Echo Server with anonymous authentication
@subsection Echo Server with anonymous authentication
This example server support anonymous authentication, and could be
@verbatiminclude examples/ex-serv-anon.c
+@node Miscellaneous examples
@section Miscellaneous examples
+@menu
+* Checking for an alert::
+* X.509 certificate parsing example::
+* Certificate request generation::
+* PKCS #12 structure generation::
+@end menu
+
+@node Checking for an alert
@subsection Checking for an alert
This is a function that checks if an alert has been received in the
@verbatiminclude examples/ex-alert.c
+@node X.509 certificate parsing example
@subsection @acronym{X.509} certificate parsing example
@anchor{ex:x509-info}
@verbatiminclude examples/ex-x509-info.c
+@node Certificate request generation
@subsection Certificate request generation
@anchor{ex:crq}
@verbatiminclude examples/ex-crq.c
+@node PKCS #12 structure generation
@subsection @acronym{PKCS} #12 structure generation
@anchor{ex:pkcs12}
@verbatiminclude examples/ex-pkcs12.c
+@node Compatibility with the OpenSSL library
@section Compatibility with the OpenSSL library
@cindex OpenSSL
@node Included programs
@chapter Included programs
+Included with @acronym{GnuTLS} are also a few command line tools that
+let you use the library for common tasks without writing an
+application. The applications are discussed in this chapter.
+
+@menu
+* Invoking srptool::
+* Invoking gnutls-cli::
+* Invoking gnutls-cli-debug::
+* Invoking gnutls-serv::
+* Invoking certtool::
+@end menu
+
+@node Invoking srptool
@section Invoking srptool
-@anchor{Invoking srptool}
@anchor{srptool}
@cindex srptool
@end itemize
+@node Invoking gnutls-cli
@section Invoking gnutls-cli
-@anchor{Invoking gnutls-cli}
@cindex gnutls-cli
Simple client program to set up a TLS connection to some other
--copyright prints the program's license
@end verbatim
+@node Invoking gnutls-cli-debug
@section Invoking gnutls-cli-debug
-@anchor{Invoking gnutls-cli-debug}
@cindex gnutls-cli-debug
This program was created to assist in debugging @acronym{GnuTLS}, but
Checking for OpenPGP authentication support (TLS extension)... no
@end smallexample
+@node Invoking gnutls-serv
@section Invoking gnutls-serv
-@anchor{Invoking gnutls-serv}
@cindex gnutls-serv
Simple server program that listens to incoming TLS connections.
--copyright prints the program's license
@end verbatim
+@node Invoking certtool
@section Invoking certtool
-@anchor{Invoking certtool}
@cindex certtool
This is a program to generate @acronym{X.509} certificates, certificate
@include pgp-api.texi
-@chapter Certificate to XML convertion functions
+@section Error codes and descriptions
+@anchor{Error Codes}
+@cindex Error codes
+
+The error codes used throughout the library are described below. The
+return code @code{GNUTLS_E_SUCCESS} indicate successful operation, and
+is guaranteed to have the value 0, so you can use it in logical
+expressions.
+
+@include error_codes.texi
+
+@node Certificate to XML convertion functions
+@chapter Certificate to @acronym{XML} convertion functions
@cindex Certificate to XML convertion
This appendix contains some example output of the XML convertion
</gnutls:openpgp:key>
@end smallexample
-@include error_codes.texi
-
+@node All the supported ciphersuites in GnuTLS
@chapter All the supported ciphersuites in @acronym{GnuTLS}
@anchor{ciphersuites}
@cindex Ciphersuites
projects / thirdparty / gnutls.git / commitdiff
