@contents
@ifnottex
-@node Top, Preface, (dir), (dir)
+@node Top
@top GNU TLS
@insertcopying
@end ifnottex
@menu
-* Preface::
-* The Library::
-* Introduction to TLS::
-* Authentication methods::
-* More on certificate authentication::
-* How to use TLS in application protocols::
-* How to use GnuTLS in applications::
-* Included programs::
-* Function reference::
-* Certificate to XML convertion functions::
-* All the supported ciphersuites in GnuTLS::
-* Guile Bindings::
-* Internal architecture of GnuTLS::
-* Copying Information::
-* Concept Index::
+* Preface::
+* The Library::
+* Introduction to TLS::
+* Authentication methods::
+* More on certificate authentication::
+* How to use TLS in application protocols::
+* How to use GnuTLS in applications::
+* Included programs::
+* Function reference::
+* Certificate to XML convertion functions::
+* All the supported ciphersuites in GnuTLS::
+* Guile Bindings::
+* Internal architecture of GnuTLS::
+* Copying Information::
+* Concept Index::
* Function and Data Index::
@c * @mybibnode{}::
-* Bibliography::
+* Bibliography::
@end menu
-@node Preface, The Library, Top, Top
+@node Preface
@chapter Preface
This document tries to demonstrate and explain the @acronym{GnuTLS}
will be available from @url{http://www.gnutls.org/} and
@url{http://www.gnu.org/software/gnutls/}.
-@node The Library, Introduction to TLS, Preface, Top
+@node The Library
@chapter The Library
In brief @acronym{GnuTLS} can be described as a library which offers an API
* Callback functions::
@end menu
-@node General Idea, Error handling, The Library, The Library
+@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, Memory handling, General Idea, The Library
+@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, Callback functions, Error handling, The Library
+@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, , Memory handling, The Library
+@node Callback functions
@section Callback functions
@cindex Callback functions
@end itemize
-@node Introduction to TLS, Authentication methods, The Library, Top
+@node Introduction to TLS
@chapter Introduction to @acronym{TLS}
@acronym{TLS} stands for ``Transport Layer Security'' and is the
* On SSL 2 and older protocols::
@end menu
-@node TLS layers, The transport layer, Introduction to TLS, Introduction to TLS
+@node TLS layers
@section TLS layers
@cindex TLS Layers
@image{layers,12cm,8cm}
-@node The transport layer, The TLS record protocol, TLS layers, Introduction to TLS
+@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, The TLS Alert Protocol, The transport layer, Introduction to TLS
+@node The TLS record protocol
@section The TLS record protocol
@cindex Record protocol
* Weaknesses and countermeasures::
@end menu
-@node Encryption algorithms used in the record layer, Compression algorithms used in the record layer, The TLS record protocol, The TLS record protocol
+@node Encryption algorithms used in the record layer
@subsection Encryption algorithms used in the record layer
@cindex Symmetric encryption algorithms
@end table
-@node Compression algorithms used in the record layer, Weaknesses and countermeasures, Encryption algorithms used in the record layer, The TLS record protocol
+@node Compression algorithms used in the record layer
@subsection Compression algorithms used in the record layer
@cindex Compression algorithms
@end table
-@node Weaknesses and countermeasures, , Compression algorithms used in the record layer, The TLS record protocol
+@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 @xcite{CBCATT}.
-@node The TLS Alert Protocol, The TLS Handshake Protocol, The TLS record protocol, Introduction to TLS
+@node The TLS Alert Protocol
@section The TLS Alert Protocol
@anchor{The Alert Protocol}
@cindex Alert protocol
@end table
-@node The TLS Handshake Protocol, TLS Extensions, The TLS Alert Protocol, Introduction to TLS
+@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
@ref{gnutls_db_check_entry} is provided for that reason.
-@node TLS Extensions, On SSL 2 and older protocols, The TLS Handshake Protocol, Introduction to TLS
+@node TLS Extensions
@section TLS Extensions
@cindex TLS Extensions
used to enable this extension, or to retrieve the name sent by a
client.
-@node On SSL 2 and older protocols, , TLS Extensions, Introduction to TLS
+@node On SSL 2 and older protocols
@section On SSL 2 and older protocols
@cindex SSL 2
2 were not implemented because they were also abandoned and deprecated
by @acronym{SSL} 3.0 and later @acronym{TLS} 1.0.
-@node Authentication methods, More on certificate authentication, Introduction to TLS, Top
+@node Authentication methods
@chapter Authentication methods
The @acronym{TLS} protocol provides confidentiality and encryption,
* Parameters stored in credentials::
@end menu
-@node Certificate authentication, Anonymous authentication, Authentication methods, Authentication methods
+@node Certificate authentication
@section Certificate authentication
@subsection Authentication using @acronym{X.509} certificates
@end table
-@node Anonymous authentication, Authentication using SRP, Certificate authentication, Authentication methods
+@node Anonymous authentication
@section Anonymous authentication
@cindex Anonymous authentication
@end table
-@node Authentication using SRP, Authentication using PSK, Anonymous authentication, Authentication methods
+@node Authentication using SRP
@section Authentication using @acronym{SRP}
@cindex @acronym{SRP} authentication
also included. @xref{srptool}, for more information.
-@node Authentication using PSK, Authentication and credentials, Authentication using SRP, Authentication methods
+@node Authentication using PSK
@section Authentication using @acronym{PSK}
@cindex @acronym{PSK} authentication
maintain @acronym{PSK} keys.
-@node Authentication and credentials, Parameters stored in credentials, Authentication using PSK, Authentication methods
+@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, , Authentication and credentials, Authentication methods
+@node Parameters stored in credentials
@section Parameters stored in credentials
Several parameters such as the ones used for Diffie-Hellman
@}
@end example
-@node More on certificate authentication, How to use TLS in application protocols, Authentication methods, Top
+@node More on certificate authentication
@chapter More on certificate authentication
@anchor{Certificate Authentication}
@cindex Certificate authentication
* Digital signatures::
@end menu
-@node The X.509 trust model, The OpenPGP trust model, More on certificate authentication, More on certificate authentication
+@node The X.509 trust model
@section The @acronym{X.509} trust model
@cindex @acronym{X.509} certificates
* PKCS #12 structures::
@end menu
-@node X.509 certificates, Verifying X.509 certificate paths, The X.509 trust model, The X.509 trust model
+@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, PKCS #10 certificate requests, X.509 certificates, The X.509 trust model
+@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. For more information consult @xcite{RFC2818}
and section @ref{ex:verify} for an example.
-@node PKCS #10 certificate requests, PKCS #12 structures, Verifying X.509 certificate paths, The X.509 trust model
+@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, , PKCS #10 certificate requests, The X.509 trust model
+@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, Digital signatures, The X.509 trust model, More on certificate authentication
+@node The OpenPGP trust model
@section The @acronym{OpenPGP} trust model
@cindex @acronym{OpenPGP} Keys
@end table
-@node Digital signatures, , The OpenPGP trust model, More on certificate authentication
+@node Digital signatures
@section Digital signatures
@cindex Digital signatures
@include signatures.texi
-@node How to use TLS in application protocols, How to use GnuTLS in applications, More on certificate authentication, Top
+@node How to use TLS in application protocols
@chapter How to use @acronym{TLS} in application protocols
This chapter is intended to provide some hints on how to use the
* Upward negotiation::
@end menu
-@node Separate ports, Upward negotiation, How to use TLS in application protocols, How to use TLS in application protocols
+@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, , Separate ports, How to use TLS in application protocols
+@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, Included programs, How to use TLS in application protocols, Top
+@node How to use GnuTLS in applications
@chapter How to use @acronym{GnuTLS} in applications
@anchor{examples}
@cindex Example programs
* Compatibility with the OpenSSL library::
@end menu
-@node Preparation, Multi-threaded applications, How to use GnuTLS in applications, How to use GnuTLS in applications
+@node Preparation
@section Preparation
To use @acronym{GnuTLS}, you have to perform some changes to your
* Building the source::
@end menu
-@node Headers, Version check, Preparation, Preparation
+@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, Building the source, Headers, Preparation
+@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 @ref{gnutls_check_version}.
-@node Building the source, , Version check, Preparation
+@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, Client examples, Preparation, How to use GnuTLS in applications
+@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, Server examples, Multi-threaded applications, How to use GnuTLS in applications
+@node Client examples
@section Client examples
This section contains examples of @acronym{TLS} and @acronym{SSL}
* Helper function for TCP connections::
@end menu
-@node Simple client example with anonymous authentication, Simple client example with X.509 certificate support, Client examples, Client examples
+@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, Obtaining session information, Simple client example with anonymous authentication, Client examples
+@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, Verifying peer's certificate, Simple client example with X.509 certificate support, Client examples
+@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, Using a callback to select the certificate to use, Obtaining session information, Client examples
+@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, Client with Resume capability example, Verifying peer's certificate, Client examples
+@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, Simple client example with SRP authentication, Using a callback to select the certificate to use, Client examples
+@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, Simple client example with TLS/IA support, Client with Resume capability example, Client examples
+@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 Simple client example with TLS/IA support, Simple client example with authorization support, Simple client example with SRP authentication, Client examples
+@node Simple client example with TLS/IA support
@subsection Simple client example with @acronym{TLS/IA} support
The following client is a simple client which uses the
@verbatiminclude examples/ex-client-tlsia.c
-@node Simple client example with authorization support, Helper function for TCP connections, Simple client example with TLS/IA support, Client examples
+@node Simple client example with authorization support
@subsection Simple client example with authorization support
The following client require that the server sends authorization data,
@verbatiminclude examples/ex-client-authz.c
-@node Helper function for TCP connections, , Simple client example with authorization support, Client examples
+@node Helper function for TCP connections
@subsection Helper function for TCP connections
This helper function abstracts away TCP connection handling from the
@verbatiminclude examples/tcp.c
-@node Server examples, Miscellaneous examples, Client examples, How to use GnuTLS in applications
+@node Server examples
@section Server examples
This section contains examples of @acronym{TLS} and @acronym{SSL}
* Echo Server with authorization support::
@end menu
-@node Echo Server with X.509 authentication, Echo Server with X.509 authentication II, Server examples, Server examples
+@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, Echo Server with OpenPGP authentication, Echo Server with X.509 authentication, Server examples
+@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
-@node Echo Server with OpenPGP authentication, Echo Server with SRP authentication, Echo Server with X.509 authentication II, Server examples
+@node Echo Server with OpenPGP authentication
@subsection Echo Server with @acronym{OpenPGP} authentication
@cindex @acronym{OpenPGP} Server
@verbatiminclude examples/ex-serv-pgp.c
-@node Echo Server with SRP authentication, Echo Server with anonymous authentication, Echo Server with OpenPGP authentication, Server examples
+@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, Echo Server with authorization support, Echo Server with SRP authentication, Server examples
+@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 Echo Server with authorization support, , Echo Server with anonymous authentication, Server examples
+@node Echo Server with authorization support
@subsection Echo Server with authorization support
This example server support authorization data, and can be used to
@verbatiminclude examples/ex-serv-authz.c
-@node Miscellaneous examples, Compatibility with the OpenSSL library, Server examples, How to use GnuTLS in applications
+@node Miscellaneous examples
@section Miscellaneous examples
@menu
* PKCS #12 structure generation::
@end menu
-@node Checking for an alert, X.509 certificate parsing example, Miscellaneous examples, Miscellaneous examples
+@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, Certificate request generation, Checking for an alert, Miscellaneous examples
+@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, PKCS #12 structure generation, X.509 certificate parsing example, Miscellaneous examples
+@node Certificate request generation
@subsection Certificate request generation
@anchor{ex:crq}
@verbatiminclude examples/ex-crq.c
-@node PKCS #12 structure generation, , Certificate request generation, Miscellaneous examples
+@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, , Miscellaneous examples, How to use GnuTLS in applications
+@node Compatibility with the OpenSSL library
@section Compatibility with the OpenSSL library
@cindex OpenSSL
@end itemize
-@node Included programs, Function reference, How to use GnuTLS in applications, Top
+@node Included programs
@chapter Included programs
Included with @acronym{GnuTLS} are also a few command line tools that
* Invoking certtool::
@end menu
-@node Invoking srptool, Invoking gnutls-cli, Included programs, Included programs
+@node Invoking srptool
@section Invoking srptool
@anchor{srptool}
@cindex srptool
@end itemize
-@node Invoking gnutls-cli, Invoking gnutls-cli-debug, Invoking srptool, Included programs
+@node Invoking gnutls-cli
@section Invoking gnutls-cli
@cindex gnutls-cli
--copyright prints the program's license
@end verbatim
-@node Invoking gnutls-cli-debug, Invoking gnutls-serv, Invoking gnutls-cli, Included programs
+@node Invoking gnutls-cli-debug
@section Invoking gnutls-cli-debug
@cindex gnutls-cli-debug
Checking for OpenPGP authentication support (TLS extension)... no
@end smallexample
-@node Invoking gnutls-serv, Invoking certtool, Invoking gnutls-cli-debug, Included programs
+@node Invoking gnutls-serv
@section Invoking gnutls-serv
@cindex gnutls-serv
--pskpasswd psk-passwd.txt
@end example
-@node Invoking certtool, , Invoking gnutls-serv, Included programs
+@node Invoking certtool
@section Invoking certtool
@cindex certtool
#time_stamping_key
@end example
-@node Function reference, Certificate to XML convertion functions, Included programs, Top
+@node Function reference
@chapter Function reference
@cindex Function reference
* Error codes and descriptions::
@end menu
-@node Core functions, X.509 certificate functions, Function reference, Function reference
+@node Core functions
@section Core functions
The prototypes for the following functions lie in
@include gnutls-api.texi
-@node X.509 certificate functions, GnuTLS-extra functions, Core functions, Function reference
+@node X.509 certificate functions
@section @acronym{X.509} certificate functions
@anchor{sec:x509api}
@cindex @acronym{X.509} Functions
@include x509-api.texi
-@node GnuTLS-extra functions, OpenPGP functions, X.509 certificate functions, Function reference
+@node GnuTLS-extra functions
@section @acronym{GnuTLS-extra} functions
@cindex @acronym{GnuTLS-extra} functions
@include gnutls-extra-api.texi
-@node OpenPGP functions, TLS Inner Application (TLS/IA) functions, GnuTLS-extra functions, Function reference
+@node OpenPGP functions
@section @acronym{OpenPGP} functions
@cindex @acronym{OpenPGP} functions
@anchor{sec:openpgpapi}
@include pgp-api.texi
-@node TLS Inner Application (TLS/IA) functions, Error codes and descriptions, OpenPGP functions, Function reference
+@node TLS Inner Application (TLS/IA) functions
@section @acronym{TLS} Inner Application (@acronym{TLS/IA}) functions
@cindex @acronym{TLS} Inner Application (@acronym{TLS/IA}) functions
@cindex Inner Application (@acronym{TLS/IA}) functions
@include ia-api.texi
-@node Error codes and descriptions, , TLS Inner Application (TLS/IA) functions, Function reference
+@node Error codes and descriptions
@section Error codes and descriptions
@anchor{Error Codes}
@cindex Error codes
@include error_codes.texi
-@node Certificate to XML convertion functions, All the supported ciphersuites in GnuTLS, Function reference, Top
+@node Certificate to XML convertion functions
@chapter Certificate to @acronym{XML} convertion functions
@cindex Certificate to XML convertion
* An OpenPGP key::
@end menu
-@node An X.509 certificate, An OpenPGP key, Certificate to XML convertion functions, Certificate to XML convertion functions
+@node An X.509 certificate
@section An @acronym{X.509} certificate
@smallexample
</gnutls:x509:certificate>
@end smallexample
-@node An OpenPGP key, , An X.509 certificate, Certificate to XML convertion functions
+@node An OpenPGP key
@section An @acronym{OpenPGP} key
@smallexample
</gnutls:openpgp:key>
@end smallexample
-@node All the supported ciphersuites in GnuTLS, Guile Bindings, Certificate to XML convertion functions, Top
+@node All the supported ciphersuites in GnuTLS
@chapter All the supported ciphersuites in @acronym{GnuTLS}
@anchor{ciphersuites}
@cindex Ciphersuites
@end multitable
-
@c
@c Guile Bindings
@c
@include guile.texi
-
-@node Internal architecture of GnuTLS, Copying Information, Guile Bindings, Top
+@node Internal architecture of GnuTLS
@chapter Internal architecture of GnuTLS
@cindex Internal architecture
@include internals.texi
-@node Copying Information, Concept Index, Internal architecture of GnuTLS, Top
+@node Copying Information
@appendix Copying Information
@menu
@include lgpl.texi
@include gpl.texi
-@node Concept Index, Function and Data Index, Copying Information, Top
+@node Concept Index
@unnumbered Concept Index
@printindex cp
-@node Function and Data Index, Bibliography, Concept Index, Top
+@node Function and Data Index
@unnumbered Function and Data Index
@printindex fn
-@node Bibliography, , Function and Data Index, Top
+@node Bibliography
@unnumbered Bibliography
@table @asis
projects / thirdparty / gnutls.git / commitdiff
