path: root/doc/gnutls.texi

\input texinfo   @c -*-texinfo-*-
@comment $Id$
@comment %**start of header
@setfilename gnutls.info
@include version.texi
@settitle GNU TLS @value{VERSION}

@include my-bib-macros.texi
@mybibusetable{Bibliography}

@c Unify some of the indices.
@syncodeindex tp fn
@syncodeindex pg cp

@comment %**end of header
@finalout
@copying
This manual is last updated @value{UPDATED} for version
@value{VERSION} of GNU TLS.

Copyright (C) 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc.


@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
@end quotation
@end copying

@dircategory GNU Libraries
@direntry
* libgnutls: (gnutls).		A Transport Layer Security Library.
@end direntry

@dircategory Network Applications
@direntry
* GnuTLS: (gnutls).			Package for Transport Layer Security.
* certtool: (gnutls)Invoking certtool.	Manipulate certificates and keys.
* srptool: (gnutls)Invoking srptool.	Simple SRP password tool.
* gnutls-serv: (gnutls)Invoking gnutls-serv.	GNU TLS test server.
* gnutls-cli: (gnutls)Invoking gnutls-cli.	GNU TLS test client.
* gnutls-cli-debug: (gnutls)Invoking gnutls-cli-debug.	GNU TLS debug client.
@end direntry

@titlepage
@title GNU TLS
@subtitle Transport Layer Security Library for the GNU system
@subtitle for version @value{VERSION}, @value{UPDATED}
@sp 7
@image{gnutls-logo,6cm,6cm}
@author Nikos Mavroyanopoulos
@author Simon Josefsson (@email{bug-gnutls@@gnu.org})
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@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::
* Copying This Manual::
* Concept Index::
* Function and Data Index::
@c * @mybibnode{}::
* Bibliography::
@end menu


@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.

This document tries to be self contained, although basic network
programming and PKI knowlegde is assumed in most of it. A good introduction
to Public Key Infrastructure can be found in @mybibcite{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/}.

@node The Library
@chapter The Library

In brief @acronym{GnuTLS} can be described as a library which offers an API
to access secure communication protocols. These protocols provide
privacy over insecure lines, and were designed to prevent
eavesdropping, tampering, or message forgery.

Technically @acronym{GnuTLS} is a portable ANSI C based library which
implements the TLS 1.1 and SSL 3.0 protocols (@xref{Introduction to
TLS}, for a more detailed description of the protocols), accompanied
with the required framework for authentication and public key
infrastructure.  The library is available under the GNU Lesser GPL
license@footnote{A copy of the license is included in the
distribution}.  Important features of the @acronym{GnuTLS} library
include:

@itemize

@item Support for TLS 1.0, TLS 1.1, and SSL 3.0 protocols.

@item Support for both @acronym{X.509} and @acronym{OpenPGP} certificates.

@item Support for handling and verification of certificates.

@item Support for @acronym{SRP} for TLS authentication.

@item Support for TLS Extension mechanism.

@item Support for TLS Compression Methods.

@end itemize

Additionally @acronym{GnuTLS} provides a limited emulation API for the
widely used OpenSSL@footnote{@url{http://www.openssl.org/}} library,
to ease integration with existing applications.

@acronym{GnuTLS} consists of three independent parts, namely the ``TLS
protocol part'', the ``Certificate part'', and the ``Crypto backend''
part.  The `TLS protocol part' is the actual protocol implementation,
and is entirely implemented within the @acronym{GnuTLS} library.  The
`Certificate part' consists of the certificate parsing, and
verification functions which is partially implemented in the
@acronym{GnuTLS} library.  The
@acronym{Libtasn1}@footnote{@url{ftp://ftp.gnupg.org/gcrypt/alpha/gnutls/libtasn1/}},
a library which offers @acronym{ASN.1} parsing capabilities, is used
for the @acronym{X.509} certificate parsing functions, and
@acronym{Opencdk}@footnote{@url{ftp://ftp.gnupg.org/gcrypt/alpha/gnutls/opencdk/}}
is used for the @acronym{OpenPGP} key support in @acronym{GnuTLS}.
The ``Crypto backend'' is provided by the
@acronym{Libgcrypt}@footnote{@url{ftp://ftp.gnupg.org/gcrypt/alpha/libgcrypt/}}
library.

In order to ease integration in embedded systems, parts of the
@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
at the figure below. This section may be easier to understand after
having seen the examples (@pxref{examples}).

@image{internals,12cm,8cm}

As shown in the figure, there is a read-only global state that is
initialized once by the global initialization function.  This global
structure, among others, contains the memory allocation functions
used, and some structures needed for the @acronym{ASN.1} parser.  This structure
is never modified by any @acronym{GnuTLS} function, except for the
deinitialization function which frees all memory allocated in the
global structure and is called after the program has permanently
finished using @acronym{GnuTLS}.

The credentials structure is used by some authentication methods, such
as certificate authentication (@pxref{Certificate Authentication}).  A
credentials structure may contain certificates, private keys,
temporary parameters for diffie hellman or RSA key exchange, and other
stuff that may be shared between several TLS sessions.

This structure should be initialized using the appropriate
initialization functions. For example an application which uses
certificate authentication would probably initialize the credentials,
using the appropriate functions, and put its trusted certificates in
this structure. The next step is to associate the credentials
structure with each @acronym{TLS} session.

A @acronym{GnuTLS} session contains all the required stuff for a
session to handle one secure connection. This session calls directly
to the transport layer functions, in order to communicate with the
peer.  Every session has a unique session ID shared with the peer.

Since TLS sessions can be resumed, servers would probably need a
database backend to hold the session's parameters.  Every
@acronym{GnuTLS} session after a successful handshake calls the
appropriate backend function (@xref{resume}, for information on
initialization) to store the newly negotiated session. The session
database is examined by the server just after having received the
client hello@footnote{The first message in a @acronym{TLS} handshake},
and if the session ID sent by the client, matches a stored session,
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
almost all cases a zero or a positive number means success, and a
negative number indicates failure, or a situation that some action has
to be taken. Thus negative error codes may be fatal or not.

Fatal errors terminate the connection immediately and further sends
and receives will be disallowed. An example of a fatal error code is
@code{GNUTLS_E_DECRYPTION_FAILED}. Non-fatal errors may warn about
something, ie a warning alert was received, or indicate the some
action has to be taken. This is the case with the error code
@code{GNUTLS_E_REHANDSHAKE} returned by @ref{gnutls_record_recv}.
This error code indicates that the server requests a re-handshake. The
client may ignore this request, or may reply with an alert.  You can
test if an error code is a fatal one by using the
@ref{gnutls_error_is_fatal}.

If any non fatal errors, that require an action, are to be returned by
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
differently, depending on the sensitivity of the data they
contain. However for performance reasons, the default memory functions
do not overwrite sensitive data from memory, nor protect such objects
from being written to the swap.  In order to change the default
behavior the @ref{gnutls_global_set_mem_functions} function is
available which can be used to set other memory handlers than the
defaults.

The @acronym{Libgcrypt} library on which @acronym{GnuTLS} depends, has such
secure memory allocation functions available. These should be used in
cases where even the system's swap memory is not considered
secure. See the documentation of @acronym{Libgcrypt} for more
information.

@node Callback functions
@section Callback functions
@cindex Callback functions

There are several cases where @acronym{GnuTLS} may need some out of
band input from your program. This is now implemented using some
callback functions, which your program is expected to register.

An example of this type of functions are the push and pull callbacks
which are used to specify the functions that will retrieve and send
data to the transport layer.

@itemize

@item @ref{gnutls_transport_set_push_function}

@item @ref{gnutls_transport_set_pull_function}

@end itemize

Other callback functions such as the one set by
@ref{gnutls_srp_set_server_credentials_function}, may require more
complicated input, including data to be allocated.  These callbacks
should allocate and free memory using the functions shown below.

@itemize

@item @ref{gnutls_malloc}

@item @ref{gnutls_free}

@end itemize

@node 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 @mybibcite{SSL3} designed by Netscape.  @acronym{TLS} is an Internet
protocol, defined by @acronym{IETF}@footnote{IETF, or Internet
Engineering Task Force, is a large open international community of
network designers, operators, vendors, and researchers concerned with
the evolution of the Internet architecture and the smooth operation of
the Internet.  It is open to any interested individual.}, described in
@acronym{RFC} 2246 and also in @mybibcite{RESCOLA}. The protocol provides
confidentiality, and authentication layers over any reliable transport
layer. The description, below, refers to @acronym{TLS} 1.0 but also
applies to @acronym{TLS} 1.1 and @acronym{SSL} 3.0, since the
differences of these protocols are minor. Older protocols such as
@acronym{SSL} 2.0 are not discussed nor 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::
* On SSL 2 and older protocols::
@end menu

@node TLS layers
@section TLS layers
@cindex TLS Layers

@acronym{TLS} is a layered protocol, and consists of the Record
Protocol, the Handshake Protocol and the Alert Protocol. The Record
Protocol is to serve all other protocols and is above the transport
layer.  The Record protocol offers symmetric encryption, data
authenticity, and optionally compression.

The Alert protocol offers some signaling to the other protocols. It
can help informing the peer for the cause of failures and other error
conditions.  @xref{The Alert Protocol}, for more information.  The
alert protocol is above the record protocol.

The Handshake protocol is responsible for the security parameters'
negotiation, the initial key exchange and authentication.  @xref{The
Handshake Protocol}, for more information about the handshake
protocol.  The protocol layering in TLS is shown in the figure below.

@image{layers,12cm,8cm}

@node The transport layer
@section The transport layer
@cindex Transport protocol

@acronym{TLS} is not limited to one transport layer, it can be used
above any transport layer, as long as it is a reliable one.  A set of
functions is provided and their purpose is to load to @acronym{GnuTLS} the
required callbacks to access the transport layer.

@itemize
@item @ref{gnutls_transport_set_push_function}
@item @ref{gnutls_transport_set_pull_function}
@item @ref{gnutls_transport_set_ptr}
@item @ref{gnutls_transport_set_lowat}
@end itemize

These functions accept a callback function as a parameter.  The
callback functions should return the number of bytes written, or -1 on
error and should set @code{errno} appropriately.

@acronym{GnuTLS} currently only interprets the EINTR and EAGAIN errno
values and returns the corresponding @acronym{GnuTLS} error codes
@code{GNUTLS_E_INTERRUPTED} and @code{GNUTLS_E_AGAIN}.  These values
are usually returned by interrupted system calls, or when non blocking
IO is used. All @acronym{GnuTLS} functions can be resumed (called
again), if any of these error codes is returned.  The error codes
above refer to the system call, not the @acronym{GnuTLS} function,
since signals do not interrupt @acronym{GnuTLS}' functions.

For non blocking sockets or other custom made pull/push functions
the @ref{gnutls_transport_set_lowat} must be called, with a zero
low water mark value.

By default, if the transport functions are not set, @acronym{GnuTLS}
will use the Berkeley Sockets functions.  In this case
@acronym{GnuTLS} will use some hacks in order for @code{select} to
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

The Record protocol is the secure communications provider. Its purpose
is to encrypt, authenticate and ---optionally--- compress packets.
The following functions are available:

@table @asis

@item @ref{gnutls_record_send}:
To send a record packet (with application data).

@item @ref{gnutls_record_recv}:
To receive a record packet (with application data).

@item @ref{gnutls_record_get_direction}:
To get the direction of the last interrupted function call.
@end table

As you may have already noticed, the functions which access the Record
protocol, are quite limited, given the importance of this protocol in
@acronym{TLS}.  This is because the Record protocol's parameters are
all set by the Handshake protocol.

The Record protocol initially starts with NULL parameters, which means
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

Confidentiality in the record layer is achieved by using symmetric
block encryption algorithms like @code{3DES}, @code{AES}@footnote{AES,
or Advanced Encryption Standard, is actually the RIJNDAEL algorithm.
This is the algorithm that replaced DES.}, or stream algorithms like
@code{ARCFOUR_128}@footnote{@code{ARCFOUR_128} is a compatible
algorithm with RSA's RC4 algorithm, which is considered to be a trade
secret.}. Ciphers are encryption algorithms that use a single, secret,
key to encrypt and decrypt data. Block algorithms in TLS also provide
protection against statistical analysis of the data.  Thus, if you're
using the @acronym{TLS} protocol, a random number of blocks will be
appended to data, to prevent eavesdroppers from guessing the actual
data size.

Supported cipher algorithms:

@table @code
@item 3DES_CBC
@code{3DES_CBC} is the DES block cipher algorithm used with triple
encryption (EDE). Has 64 bits block size and is used in CBC mode.

@item ARCFOUR_128
ARCFOUR is a fast stream cipher.

@item ARCFOUR_40
This is the ARCFOUR cipher that is fed with a 40 bit key,
which is considered weak.

@item AES_CBC
AES or RIJNDAEL is the block cipher algorithm that replaces the old
DES algorithm.  Has 128 bits block size and is used in CBC mode. This
is not officially supported in TLS.
@end table

Supported MAC algorithms:

@table @code
@item MAC_MD5
MD5 is a cryptographic hash algorithm designed by Ron Rivest. Outputs
128 bits of data.

@item MAC_SHA
SHA is a cryptographic hash algorithm designed by NSA. Outputs 160
bits of data.

@item MAC_RMD160
RIPEMD is a cryptographic hash algorithm developed in the framework of
the EU project RIPE. Outputs 160 bits of data.

@end table

@node Compression algorithms used in the record layer
@subsection Compression algorithms used in the record layer
@cindex Compression algorithms

The TLS record layer also supports compression.  The algorithms
implemented in @acronym{GnuTLS} can be found in the table below.
All the algorithms except for DEFLATE which is
referenced in @mybibcite{TLSCOMP}, should be considered as
@acronym{GnuTLS}' extensions@footnote{You should use
@ref{gnutls_handshake_set_private_extensions} to enable private
extensions.}, and should be advertised only when the peer is known to
have a compliant client, to avoid interoperability problems.

The included algorithms perform really good when text, or other
compressible data are to be transfered, but offer nothing on already
compressed data, such as compressed images, zipped archives etc.
These compression algorithms, may be useful in high bandwidth TLS
tunnels, and in cases where network usage has to be minimized. As a
drawback, compression increases latency.

The record layer compression in @acronym{GnuTLS} is implemented based
on the paper @mybibcite{TLSCOMP}.
The supported compression algorithms are:

@table @code
@item DEFLATE
Zlib compression, using the deflate algorithm.

@item LZO
LZO is a very fast compression algorithm. This algorithm is only
available if the @acronym{GnuTLS-extra} library has been initialized
and the private extensions are enabled.

@end table

@node Weaknesses and countermeasures
@subsection Weaknesses and countermeasures

Some weaknesses that may affect the security of the Record layer have
been found in @acronym{TLS} 1.0 protocol. These weaknesses can be
exploited by active attackers, and exploit the facts that

@enumerate

@item
@acronym{TLS} has separate alerts for ``decryption_failed'' and
``bad_record_mac''

@item
The decryption failure reason can be detected by timing the response
time.

@item
The IV for CBC encrypted packets is the last block of the previous
encrypted packet.

@end enumerate

Those weaknesses were solved in @acronym{TLS} 1.1 which is implemented
in @acronym{GnuTLS}. For a detailed discussion see the archives of the
TLS Working Group mailing list and the paper @mybibcite{CBCATT}.

@node The TLS Alert Protocol
@section The TLS Alert Protocol
@anchor{The Alert Protocol}
@cindex Alert protocol

The Alert protocol is there to allow signals to be sent between peers.
These signals are mostly used to inform the peer about the cause of a
protocol failure. Some of these signals are used internally by the
protocol and the application protocol does not have to cope with them
(see @code{GNUTLS_A_CLOSE_NOTIFY}), and others refer to the
application protocol solely (see @code{GNUTLS_A_USER_CANCELLED}).  An
alert signal includes a level indication which may be either fatal or
warning. Fatal alerts always terminate the current connection, and
prevent future renegotiations using the current session ID.

The alert messages are protected by the record protocol, thus the
information that is included does not leak. You must take extreme care
for the alert information not to leak to a possible attacker, via
public log files etc.

@table @asis
@item @ref{gnutls_alert_send}:
To send an alert signal.

@item @ref{gnutls_error_to_alert}:
To map a gnutls error number to an alert signal.

@item @ref{gnutls_alert_get}:
Returns the last received alert.

@item @ref{gnutls_alert_get_name}:
Returns the name, in a character array, of the given alert.

@end table

@node The TLS Handshake Protocol
@section The TLS Handshake Protocol
@anchor{The Handshake Protocol}
@cindex Handshake protocol

The Handshake protocol is responsible for the ciphersuite negotiation,
the initial key exchange, and the authentication of the two peers.
This is fully controlled by the application layer, thus your program
has to set up the required parameters. Available functions to control
the handshake protocol include:

@table @asis
@item @ref{gnutls_cipher_set_priority}:
To set the priority of bulk cipher algorithms.

@item @ref{gnutls_mac_set_priority}:
To set the priority of MAC algorithms.

@item @ref{gnutls_kx_set_priority}:
To set the priority of key exchange algorithms.

@item @ref{gnutls_compression_set_priority}:
To set the priority of compression methods.

@item @ref{gnutls_certificate_type_set_priority}:
To set the priority of certificate types (e.g., @acronym{OpenPGP},
@acronym{X.509}).

@item @ref{gnutls_protocol_set_priority}:
To set the priority of protocol versions (e.g., @acronym{SSL} 3.0,
@acronym{TLS} 1.0).

@item @ref{gnutls_set_default_priority}:
To set some defaults in the current session.  That way you don't have
to call each priority function, independently, but you have to live
with the defaults.

@item @ref{gnutls_credentials_set}:
To set the appropriate credentials structures.

@item @ref{gnutls_certificate_server_set_request}:
To set whether client certificate is required or not.

@item @ref{gnutls_handshake}:
To initiate the handshake.
@end table

@subsection TLS cipher suites

The Handshake Protocol of @acronym{TLS} negotiates cipher suites of
the form @code{TLS_DHE_RSA_WITH_3DES_CBC_SHA}.  The usual cipher
suites contain these parameters:

@itemize

@item The key exchange algorithm.
@code{DHE_RSA} in the example.

@item The Symmetric encryption algorithm and mode
@code{3DES_CBC} in this example.

@item The MAC@footnote{MAC stands for Message Authentication Code. It can be described as a keyed hash algorithm. See RFC2104.} algorithm used for authentication.
@code{MAC_SHA} is used in the above example.

@end itemize

The cipher suite negotiated in the handshake protocol will affect the
Record Protocol, by enabling encryption and data authentication.  Note
that you should not over rely on @acronym{TLS} to negotiate the
strongest available cipher suite. Do not enable ciphers and algorithms
that you consider weak.

The priority functions, dicussed above, allow the application layer to
enable and set priorities on the individual ciphers. It may imply that
all combinations of ciphersuites are allowed, but this is not
true. For several reasons, not discussed here, some combinations were
not defined in the @acronym{TLS} protocol.  The supported ciphersuites
are shown in @ref{ciphersuites}.

@subsection Client authentication
@cindex Client Certificate authentication

In the case of ciphersuites that use certificate authentication, the
authentication of the client is optional in @acronym{TLS}.  A server
may request a certificate from the client --- using the
@ref{gnutls_certificate_server_set_request} function. If a
certificate is to be requested from the client during the handshake,
the server will send a certificate request message that contains a
list of acceptable certificate signers. The client may then send a
certificate, signed by one of the server's acceptable signers. In
@acronym{GnuTLS} the server's acceptable signers list is constructed
using the trusted CA certificates in the credentials structure.

@subsection Resuming Sessions
@anchor{resume}
@cindex Resuming sessions

The @ref{gnutls_handshake} function, is expensive since a lot of
calculations are performed. In order to support many fast connections
to the same server a client may use session resuming. @strong{Session
resuming} is a feature of the @acronym{TLS} protocol which allows a
client to connect to a server, after a successful handshake, without
the expensive calculations.  This is achieved by using the previously
established keys. @acronym{GnuTLS} supports this feature, and the
example (@pxref{ex:resume-client}) illustrates a typical use of it.

Keep in mind that sessions are expired after some time, for security
reasons, thus it may be normal for a server not to resume a session
even if you requested that.  Also note that you must enable, using the
priority functions, at least the algorithms used in the last session.

@subsection Resuming internals

The resuming capability, mostly in the server side, is one of the
problems of a thread-safe TLS implementations. The problem is that all
threads must share information in order to be able to resume
sessions. The gnutls approach is, in case of a client, to leave all
the burden of resuming to the client. Ie. copy and keep the necessary
parameters. See the functions:

@itemize

@item @ref{gnutls_session_get_data}

@item @ref{gnutls_session_get_id}

@item @ref{gnutls_session_set_data}

@end itemize

The server side is different. A server has to specify some callback
functions which store, retrieve and delete session data. These can be
registered with:

@itemize

@item @ref{gnutls_db_set_remove_function}

@item @ref{gnutls_db_set_store_function}

@item @ref{gnutls_db_set_retrieve_function}

@item @ref{gnutls_db_set_ptr}

@end itemize

It might also be useful to be able to check for expired sessions in
order to remove them, and save space. The function
@ref{gnutls_db_check_entry} is provided for that reason.

@node TLS Extensions
@section TLS Extensions
@cindex TLS Extensions

A number of extensions to the @acronym{TLS} protocol have been
proposed mainly in @acronym{RFC} 3546
(@url{http://www.ietf.org/rfc/rfc3546.txt}). The extensions supported
in @acronym{GnuTLS} are:

@itemize
@item Maximum fragment length negotiation
@item Server name indication
@end itemize

and they will be discussed in the subsections that follow.

@subsection Maximum fragment length negotiation
@cindex TLS Extensions
@cindex Maximum fragment length

This extension allows a @acronym{TLS} implementation to negotiate a
smaller value for record packet maximum length. This extension may be
useful to clients with constrained capabilities. See the
@ref{gnutls_record_set_max_size} and the
@ref{gnutls_record_get_max_size} functions.

@subsection Server name indication
@anchor{serverind}
@cindex TLS Extensions
@cindex Server name indication

A common problem in @acronym{HTTPS} servers is the fact that the
@acronym{TLS} protocol is not aware of the hostname that a client
connects to, when the handshake procedure begins. For that reason the
@acronym{TLS} server has no way to know which certificate to send.

This extension solves that problem within the @acronym{TLS} protocol,
and allows a client to send the HTTP hostname before the handshake
begins within the first handshake packet.  The functions
@ref{gnutls_server_name_set} and @ref{gnutls_server_name_get} can be
used to enable this extension, or to retrieve the name sent by a
client.

@node On SSL 2 and older protocols
@section On SSL 2 and older protocols
@cindex SSL 2

One of the initial decisions in the @acronym{GnuTLS} development was
to implement the security protocols for the transport layer.
Initially @acronym{TLS} 1.0 was implemented since it was the latest at
that time, and was considered to be the most advanced in security
properties.  Later the @acronym{SSL} 3.0 protocol was implemented
since it is still the only protocol supported by several servers and
there are no serious security vulnerabilities known.

One question that may arise is why we didn't implement @acronym{SSL}
2.0 in the library.  There are several reasons, most important being
that it has serious security flaws, unacceptable for a modern security
library.  Other than that, this protocol is barely used by anyone
these days (it has been deprecated since 1996).

@cindex PCT
Other protocols such as Microsoft's @acronym{PCT} 1 and @acronym{PCT}
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
@chapter Authentication methods

The @acronym{TLS} protocol provides confidentiality and encryption,
but also offers authentication, which is a prerequisite for a secure
connection. The available authentication methods in @acronym{GnuTLS}
are:

@itemize

@item Certificate authentication

@item Anonymous authentication

@item @acronym{SRP} authentication

@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
@cindex @acronym{X.509} certificates

@acronym{X.509} certificates contain the public parameters, of a
public key algorithm, and an authority's signature, which proves the
authenticity of the parameters.  @xref{The X.509 trust model}, for
more information on @acronym{X.509} protocols.

@subsection Authentication using @acronym{OpenPGP}keys
@cindex @acronym{OpenPGP} Keys

@acronym{OpenPGP} keys also contain public parameters of a public key
algorithm, and signatures from several other parties. Depending on
whether a signer is trusted the key is considered trusted or not.
@acronym{GnuTLS}'s @acronym{OpenPGP} authentication implementation is
based on the @mybibcite{TLSPGP} proposal.

@xref{The OpenPGP trust model}, for more information about the
@acronym{OpenPGP} trust model.  For a more detailed introduction to
@acronym{OpenPGP} and @acronym{GnuPG} see @mybibcite{GPGH}.

@subsection Using certificate authentication

In @acronym{GnuTLS} both the @acronym{OpenPGP} and @acronym{X.509}
certificates are part of the certificate authentication and thus are
handled using a common API.

When using certificates the server is required to have at least one
certificate and private key pair. A client may or may not have such a
pair. The certificate and key pair should be loaded, before any
@acronym{TLS} session is initialized, in a certificate credentials
structure. This should be done by using
@ref{gnutls_certificate_set_x509_key_file} or
@ref{gnutls_certificate_set_openpgp_key_file} depending on the
certificate type.  In the @acronym{X.509} case, the functions will
also accept and use a certificate list that leads to a trusted
authority. The certificate list must be ordered in such way that every
certificate certifies the one before it. The trusted authority's
certificate need not to be included, since the peer should possess it
already.

As an alternative, a callback may be used so the server or the client
specify the certificate and the key at the handshake time.  That
callback can be set using the functions:

@itemize

@item @ref{gnutls_certificate_server_set_retrieve_function}

@item @ref{gnutls_certificate_client_set_retrieve_function}

@end itemize

Certificate verification is possible by loading the trusted
authorities into the credentials structure by using
@ref{gnutls_certificate_set_x509_trust_file} or
@ref{gnutls_certificate_set_openpgp_keyring_file} for openpgp
keys. Note however that the peer's certificate is not automatically
verified, you should call @ref{gnutls_certificate_verify_peers2},
after a successful handshake, to verify the signatures of the
certificate.  An alternative way, which reports a more detailed
verification output, is to use @ref{gnutls_certificate_get_peers} to
obtain the raw certificate of the peer and verify it using the
functions discussed in @ref{The X.509 trust model}.

In a handshake, the negotiated cipher suite depends on the
certificate's parameters, so not all key exchange methods will be
available with some certificates. @acronym{GnuTLS} will disable
ciphersuites that are not compatible with the key, or the enabled
authentication methods.  For example keys marked as sign-only, will
not be able to access the plain RSA ciphersuites, but only the
@code{DHE_RSA} ones. It is recommended not to use RSA keys for both
signing and encryption. If possible use the same key for the
@code{DHE_RSA} and @code{RSA_EXPORT} ciphersuites, which use signing,
and a different key for the plain RSA ciphersuites, which use
encryption.  All the key exchange methods shown below are available in
certificate authentication.

Note that the DHE key exchange methods are generally
slower@footnote{It really depends on the group used.  Primes with
lesser bits are always faster, but also easier to break.  Values less
than 768 should not be used today} than plain RSA and require Diffie
Hellman parameters to be generated and associated with a credentials
structure, by the server.  The @code{RSA-EXPORT} method also requires 512 bit RSA
parameters, that should also be generated and associated with the
credentials structure.  See the functions:

@itemize

@item @ref{gnutls_dh_params_generate2}

@item @ref{gnutls_certificate_set_dh_params}

@item @ref{gnutls_rsa_params_generate2}

@item @ref{gnutls_certificate_set_rsa_export_params}

@end itemize

Sometimes in order to avoid bottlenecks in programs it is usefull to store
and read parameters from formats that can be generated by external programs such
as @code{certtool}. This is possible with @acronym{GnuTLS} by using the following
functions:

@itemize

@item @ref{gnutls_dh_params_import_pkcs3}

@item @ref{gnutls_rsa_params_import_pkcs1}

@item @ref{gnutls_dh_params_export_pkcs3}

@item @ref{gnutls_rsa_params_export_pkcs1}

@end itemize

Key exchange algorithms for @acronym{OpenPGP} and @acronym{X.509}
certificates:

@table @code

@item RSA:
The RSA algorithm is used to encrypt a key and send it to the peer.
The certificate must allow the key to be used for encryption.

@item RSA_EXPORT:
The RSA algorithm is used to encrypt a key and send it to the peer.
In the EXPORT algorithm, the server signs temporary RSA parameters of
512 bits --- which are considered weak --- and sends them to the client.

@item DHE_RSA:
The RSA algorithm is used to sign Ephemeral Diffie Hellman parameters
which are sent to the peer. The key in the certificate must allow the
key to be used for signing. Note that key exchange algorithms which
use Ephemeral Diffie Hellman parameters, offer perfect forward
secrecy. That means that even if the private key used for signing is
compromised, it cannot be used to reveal past session data.

@item DHE_DSS:
The DSS algorithm is used to sign Ephemeral Diffie Hellman parameters
which are sent to the peer. The certificate must contain DSA
parameters to use this key exchange algorithm. DSS stands for Digital
Signature Standard.

@end table

@node Anonymous authentication
@section Anonymous authentication
@cindex Anonymous authentication

The anonymous key exchange perform encryption but there is no
indication of the identity of the peer.  This kind of authentication
is vulnerable to a man in the middle attack, but this protocol can be
used even if there is no prior communication and trusted parties with
the peer, or when full anonymity is required.  Unless really required,
do not use anonymous authentication.  Available key exchange methods
are shown below.

Note that the key exchange methods for anonymous authentication
require Diffie Hellman parameters to be generated by the server and associated with
an anonymous credentials structure.

Supported anonymous key exchange algorithms:

@table @code

@item ANON_DH:
This algorithm exchanges Diffie Hellman parameters.

@end table

@node Authentication using SRP
@section Authentication using @acronym{SRP}
@cindex @acronym{SRP} authentication

Authentication via the Secure Remote Password protocol,
@acronym{SRP}@footnote{@acronym{SRP} is described in @mybibcite{RFC2945}},
is supported.  The @acronym{SRP} key exchange is an extension to the
@acronym{TLS} protocol, and it is a password based authentication
(unlike @acronym{X.509} or @acronym{OpenPGP} that uses certificates).
The two peers can be identified using a single password, or there can
be combinations where the client is authenticated using @acronym{SRP}
and the server using a certificate.

The advantage of @acronym{SRP} authentication, over other proposed
secure password authentication schemes, is that @acronym{SRP} does not
require the server to hold the user's password.  This kind of
protection is similar to the one used traditionally in the @emph{UNIX}
@file{/etc/passwd} file, where the contents of this file did not cause
harm to the system security if they were revealed.  The @acronym{SRP}
needs instead of the plain password something called a verifier, which
is calculated using the user's password, and if stolen cannot be used
to impersonate the user. Check @mybibcite{TOMSRP} for a detailed description
of the @acronym{SRP} protocol and the Stanford @acronym{SRP}
libraries, which includes a PAM module that synchronizes the system's
users passwords with the @acronym{SRP} password files. That way
@acronym{SRP} authentication could be used for all the system's users.

The implementation in @acronym{GnuTLS} is based on paper
@mybibcite{TLSSRP}.  The supported @acronym{SRP} key exchange methods are:

@table @code

@item SRP:
Authentication using the @acronym{SRP} protocol.

@item SRP_DSS:
Client authentication using the @acronym{SRP} protocol. Server is
authenticated using a certificate with DSA parameters.

@item SRP_RSA:
Client authentication using the @acronym{SRP} protocol. Server is
authenticated using a certificate with RSA parameters.

@end table

If clients supporting @acronym{SRP} know the username and password
before the connection, should initialize the client credentials and
call the function @ref{gnutls_srp_set_client_credentials}.
Alternatively they could specify a callback function by using the
function @ref{gnutls_srp_set_client_credentials_function}.  This has
the advantage that allows probing the server for @acronym{SRP}
support.  In that case the callback function will be called twice per
handshake.  The first time is before the ciphersuite is negotiated,
and if the callback returns a negative error code, the callback will
be called again if @acronym{SRP} has been negotiated.  This uses a
special @acronym{TLS}-@acronym{SRP} handshake idiom in order to avoid,
in interactive applications, to ask the user for @acronym{SRP}
password and username if the server does not negotiate an
@acronym{SRP} ciphersuite.

In server side the default behaviour of @acronym{GnuTLS} is to read
the usernames and @acronym{SRP} verifiers from password files. These
password files are the ones used by the @emph{Stanford srp libraries}
and can be specified using the
@ref{gnutls_srp_set_server_credentials_file}.  If a different
password file format is to be used, then the function
@ref{gnutls_srp_set_server_credentials_function}, should be called,
in order to set an appropriate callback.

Some helper functions such as:

@itemize

@item @ref{gnutls_srp_verifier}

@item @ref{gnutls_srp_base64_encode}

@item @ref{gnutls_srp_base64_decode}

@end itemize

Are included in @acronym{GnuTLS}, and may be used to generate, and
maintain @acronym{SRP} verifiers, and password files.  A program to
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
credentials type. So in order to enable to enable a specific method,
the corresponding credentials type should be initialized and set using
@ref{gnutls_credentials_set}.  A mapping is shown below.

Key exchange algorithms and the corresponding credential types:

@multitable @columnfractions .3 .3 .3

@headitem Key exchange @tab Client credentials @tab Server credentials

@item @code{KX_RSA}
@item @code{KX_DHE_RSA}
@item @code{KX_DHE_DSS}
@item @code{KX_RSA_EXPORT}
@tab @code{CRD_CERTIFICATE}
@tab @code{CRD_CERTIFICATE}

@item @code{KX_SRP_RSA}
@tab @code{CRD_SRP}
@tab @code{CRD_SRP}
@item @code{KX_SRP_DSS}
@tab
@tab @code{CRD_CERTIFICATE}

@item @code{KX_SRP}
@tab @code{CRD_SRP}
@tab @code{CRD_SRP}

@item @code{KX_ANON_DH}
@tab @code{CRD_ANON}
@tab @code{CRD_ANON}

@end multitable

@node Parameters stored in credentials
@section Parameters stored in credentials

Several parameters such as the ones used for Diffie-Hellman
authentication are stored within the credentials structures, so all
sessions can access them. Those parameters are stored in structures
such as @code{gnutls_dh_params_t} and @code{gnutls_rsa_params_t}, and
functions like @ref{gnutls_certificate_set_dh_params} and
@ref{gnutls_certificate_set_rsa_export_params} can be used to
associate those parameters with the given credentials structure.

Since those parameters need to be renewed from time to time and a
global structure such as the credentials, may not be easy to modify
since it is accessible by all sessions, an alternative interface is
available using a callback function.  This can be set using the
@ref{gnutls_certificate_set_params_function}.  An example is shown
below.

@example
#include <gnutls.h>

gnutls_rsa_params_t rsa_params;
gnutls_dh_params_t dh_params;

/* This function will be called once a session requests DH
 * or RSA parameters. The parameters returned (if any) will
 * be used for the first handshake only.
 */
static int get_params( gnutls_session_t session,
        gnutls_params_type_t type,
        gnutls_params_st *st)
@{
   if (type == GNUTLS_PARAMS_RSA_EXPORT)
      st->params.rsa_export = rsa_params;
   else if (type == GNUTLS_PARAMS_DH)
      st->params.dh = dh_params;
   else return -1;

   st->type = type;
   /* do not deinitialize those parameters.
    */
   st->deinit = 0;

   return 0;
@}

int main()
@{
   gnutls_certificate_credentials_t cert_cred;

   initialize_params();

   /* ...
    */

   gnutls_certificate_set_params_function( cert_cred, get_params);
@}
@end example

@node More on certificate authentication
@chapter More on certificate authentication
@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
@cindex @acronym{X.509} certificates

The @acronym{X.509} protocols rely on a hierarchical trust model. In
this trust model Certification Authorities (CAs) are used to certify
entities.  Usually more than one certification authorities exist, and
certification authorities may certify other authorities to issue
certificates as well, following a hierarchical model.

@image{x509-1,7cm,9.5cm}

One needs to trust one or more CAs for his secure communications. In
that case only the certificates issued by the trusted authorities are
acceptable.  See the figure above for a typical example.  The API for
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
certificate holder, the signer, a unique serial number, expiration
dates and some other fields @mybibcite{RFC3280} as shown in the table
below.

@table @code

@item version:
The field that indicates the version of the certificate.

@item serialNumber:
This field holds a unique serial number per certificate.

@item issuer:
Holds the issuer's distinguished name.

@item validity:
The activation and expiration dates.

@item subject:
The subject's distinguished name of the certificate.

@item extensions:
The extensions are fields only present in version 3 certificates.

@end table

The certificate's @emph{subject or issuer name} is not just a single
string.  It is a Distinguished name and in the @acronym{ASN.1}
notation is a sequence of several object IDs with their corresponding
values. Some of available OIDs to be used in an @acronym{X.509}
distinguished name are defined in @file{gnutls/x509.h}.

The @emph{Version} field in a certificate has values either 1 or 3 for
version 3 certificates.  Version 1 certificates do not support the
extensions field so it is not possible to distinguish a CA from a
person, thus their usage should be avoided.

The @emph{validity} dates are there to indicate the date that the
specific certificate was activated and the date the certificate's key
would be considered invalid.

Certificate @emph{extensions} are there to include information about
the certificate's subject that did not fit in the typical certificate
fields. Those may be e-mail addresses, flags that indicate whether the
belongs to a CA etc.  All the supported @acronym{X.509} version 3
extensions are shown in the table below.

@table @code

@item subject key id (2.5.29.14):
An identifier of the key of the subject.

@item authority key id (2.5.29.35):
An identifier of the authority's key used to sign the certificate.

@item subject alternative name (2.5.29.17):
Alternative names to subject's distinguished name.

@item key usage (2.5.29.15):
Constraints the key's usage of the certificate.

@item extended key usage (2.5.29.37):
Constraints the purpose of the certificate.

@item basic constraints (2.5.29.19):
Indicates whether this is a CA certificate or not.

@item CRL distribution points (2.5.29.31):
This extension is set by the CA, in order to inform about the issued CRLs.

@end table

In @acronym{GnuTLS} the @acronym{X.509} certificate structures are handled using
the @code{gnutls_x509_crt_t} type and the corresponding private keys
with the @code{gnutls_x509_privkey_t} type.  All the available
functions for @acronym{X.509} certificate handling have their prototypes in
@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

Verifying certificate paths is important in @acronym{X.509} authentication. For
this purpose the function @ref{gnutls_x509_crt_verify} is
provided. The output of this function is the bitwise OR of the
elements of the @code{gnutls_certificate_status_t} enumeration.  A
detailed description of these elements can be found in figure below.
The function @ref{gnutls_certificate_verify_peers2} is equivalent to
the previous one, and will verify the peer's certificate in a TLS
session.

@table @code

@item CERT_INVALID:
The certificate is not signed by one of the known authorities, or
the signature is invalid.

@item CERT_REVOKED:
The certificate has been revoked by its CA.

@item CERT_SIGNER_NOT_FOUND:
The certificate's issuer is not known. This is the case when the
issuer is not in the trusted certificates list.

@item GNUTLS_CERT_SIGNER_NOT_CA:
The certificate's signer was not a CA. This may happen if
this was a version 1 certificate, which is common with some CAs, or
a version 3 certificate without the basic constrains extension.

@item GNUTLS_CERT_INSECURE_ALGORITHM:
The certificate was signed using an insecure algorithm such as MD2 or MD5.
These algorithms have been broken and should not be trusted.

@end table

There is also to possibility to pass some input to the verification functions in
the form of flags. For  @ref{gnutls_x509_crt_verify} the flags are passed straightforward, but
@ref{gnutls_certificate_verify_peers2} depends on the flags set by calling @code{gnutls_certificate_set_verify_flags}.
All the available flags are part of the enumeration @ref{gnutls_certificate_verify_flags} and
are explained in the table below.

@anchor{gnutls_certificate_verify_flags}
@tindex gnutls_certificate_verify_flags
@table @code
@item GNUTLS_VERIFY_DISABLE_CA_SIGN:
If set a signer does not have to be a certificate authority. This
flag should normaly be disabled, unless you know what this means.

@item GNUTLS_VERIFY_ALLOW_X509_V1_CA_CRT:
Allow only trusted CA certificates that have version 1.  This is
safer than GNUTLS_VERIFY_ALLOW_ANY_X509_V1_CA_CRT, and should be
used instead. That way only signers in your trusted list will be
allowed to have certificates of version 1.

@item GNUTLS_VERIFY_ALLOW_ANY_X509_V1_CA_CRT:
Allow CA certificates that have version 1 (both root and
intermediate). This is dangerous since those haven't the
basicConstraints extension. Must be used in combination with
GNUTLS_VERIFY_ALLOW_X509_V1_CA_CRT.

@item GNUTLS_VERIFY_DO_NOT_ALLOW_SAME:
If a certificate is not signed by anyone trusted but exists in
the trusted CA list do not treat it as trusted.

@item GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD2:
Allow certificates to be signed using the broken MD2 algorithm.

@item GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5:
Allow certificates to be signed using the broken MD5 algorithm.
@end table

Although the verification of a certificate path indicates that the
certificate is signed by trusted authority, does not reveal anything
about the peer's identity. It is required to verify if the
certificate's owner is the one you expect. For more information consult @mybibcite{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

A certificate request is a structure, which contain information about
an applicant of a certificate service.  It usually contains a private
key, a distinguished name and secondary data such as a challenge
password. @acronym{GnuTLS} supports the requests defined in
@acronym{PKCS} #10 @mybibcite{RFC2986}. Other certificate request's format
such as PKIX's @mybibcite{RFC2511} are not currently supported.

In @acronym{GnuTLS} the @acronym{PKCS} #10 structures are handled
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

A @acronym{PKCS} #12 structure @mybibcite{PKCS12} usually contains a user's
private keys and certificates. It is commonly used in browsers to
export and import the user's identities.

In @acronym{GnuTLS} the @acronym{PKCS} #12 structures are handled
using the @code{gnutls_pkcs12_t} type. This is an abstract type that
may hold several @code{gnutls_pkcs12_bag_t} types.  The Bag types are
the holders of the actual data, which may be certificates, private
keys or encrypted data.  An Bag of type encrypted should be decrypted
in order for its data to be accessed.

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
@cindex @acronym{OpenPGP} Keys

The @acronym{OpenPGP} key authentication relies on a distributed trust
model, called the ``web of trust''. The ``web of trust'' uses a
decentralized system of trusted introducers, which are the same as a
CA. @acronym{OpenPGP} allows anyone to sign anyone's else public
key. When Alice signs Bob's key, she is introducing Bob's key to
anyone who trusts Alice. If someone trusts Alice to introduce keys,
then Alice is a trusted introducer in the mind of that observer.

@image{pgp1,11cm,9cm}

For example: If David trusts Alice to be an introducer, and Alice
signed Bob's key, Dave also trusts Bob's key to be the real one.

There are some key points that are important in that model. In the
example Alice has to sign Bob's key, only if she is sure that the key
belongs to Bob. Otherwise she may also make Dave falsely believe that
this is Bob's key. Dave has also the responsibility to know who to
trust.  This model is similar to real life relations.

Just see how Charlie behaves in the previous example. Although he has
signed Bob's key - because he knows, somehow, that it belongs to Bob -
he does not trust Bob to be an introducer. Charlie decided to trust
only Kevin, for some reason. A reason could be that Bob is lazy
enough, and signs other people's keys without being sure that they
belong to the actual owner.

@subsection @acronym{OpenPGP} keys

In @acronym{GnuTLS} the @acronym{OpenPGP} key structures
@mybibcite{RFC2440} are handled using the @code{gnutls_openpgp_key_t} type
and the corresponding private keys with the
@code{gnutls_openpgp_privkey_t} type. All the prototypes for the key
handling functions can be found at @file{gnutls/openpgp.h}.

@subsection Verifying an @acronym{OpenPGP} key

The verification functions of @acronym{OpenPGP} keys, included in
@acronym{GnuTLS}, are simple ones, and do not use the features of the
``web of trust''.  For that reason, if the verification needs are
complex, the assistance of external tools like @acronym{GnuPG} and
GPGME (@url{http://www.gnupg.org/related_software/gpgme/}) is
recommended.

There are two verification functions in @acronym{GnuTLS}, The
@ref{gnutls_openpgp_key_verify_ring} and the
@ref{gnutls_openpgp_key_verify_trustdb}.  The first one checks an
@acronym{OpenPGP} key against a given set of public keys (keyring) and
returns the key status. The key verification status is the same as in
@acronym{X.509} certificates, although the meaning and interpretation are
different. For example an @acronym{OpenPGP} key may be valid, if the
self signature is ok, even if no signers were found.  The meaning of
verification status is shown in the figure below.  The latter function
checks a @acronym{GnuPG} trust database for the given key. This
function does not check the key signatures, only checks for disabled
and revoked keys.

@table @code

@item CERT_INVALID:
A signature on the key is invalid. That means that the key was
modified by somebody, or corrupted during transport.

@item CERT_REVOKED:
The key has been revoked by its owner.

@item CERT_SIGNER_NOT_FOUND:
The key was not signed by a known signer.

@item GNUTLS_CERT_INSECURE_ALGORITHM:
The certificate was signed using an insecure algorithm such as MD2 or MD5.
These algorithms have been broken and should not be trusted.

@end table

@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
@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
assigning a new port number for the secure services. That way two
separate ports were assigned, one for the non secure sessions, and one
for the secured ones. This has the benefit that if a user requests a
secure session then the client will try to connect to the secure port
and fail otherwise. The only possible attack with this method is a
denial of service one. The most famous example of this method is the
famous ``HTTP over TLS'' or @acronym{HTTPS} protocol @mybibcite{RFC2818}.

Despite its wide use, this method is not as good as it seems.  This
approach starts the @acronym{TLS} Handshake procedure just after the
client connects on the ---so called--- secure port.  That way the
@acronym{TLS} protocol does not know anything about the client, and
popular methods like the host advertising in HTTP do not
work@footnote{See also the Server Name Indication extension on
@ref{serverind}.}.  There is no way for the client to say ``I
connected to YYY server'' before the Handshake starts, so the server
cannot possibly know which certificate to use.

Other than that it requires two separate ports to run a single
service, which is unnecessary complication. Due to the fact that there
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
different approach to enable the secure layer.  They use something
called the ``TLS upgrade'' method. This method is quite tricky but it
is more flexible. The idea is to extend the application protocol to
have a ``STARTTLS'' request, whose purpose it to start the TLS
protocols just after the client requests it.  This is a really neat
idea and does not require an extra port.

This method is used by almost all modern protocols and there is even
the @mybibcite{RFC2817} paper which proposes extensions to HTTP to support
it.

The tricky part, in this method, is that the ``STARTTLS'' request is
sent in the clear, thus is vulnerable to modifications.  A typical
attack is to modify the messages in a way that the client is fooled
and thinks that the server does not have the ``STARTTLS'' capability.
See a typical conversation of a hypothetical protocol:

@quotation
(client connects to the server)

CLIENT: HELLO I'M MR. XXX

SERVER: NICE TO MEET YOU XXX

CLIENT: PLEASE START TLS

SERVER: OK

*** TLS STARTS

CLIENT: HERE ARE SOME CONFIDENTIAL DATA
@end quotation

And see an example of a conversation where someone is acting
in between:

@quotation
(client connects to the server)

CLIENT: HELLO I'M MR. XXX

SERVER: NICE TO MEET YOU XXX

CLIENT: PLEASE START TLS

(here someone inserts this message)

SERVER: SORRY I DON'T HAVE THIS CAPABILITY

CLIENT: HERE ARE SOME CONFIDENTIAL DATA
@end quotation

As you can see above the client was fooled, and was dummy enough to
send the confidential data in the clear.

How to avoid the above attack? As you may have already thought this
one is easy to avoid. The client has to ask the user before it
connects whether the user requests @acronym{TLS} or not. If the user
answered that he certainly wants the secure layer the last
conversation should be:

@quotation
(client connects to the server)

CLIENT: HELLO I'M MR. XXX

SERVER: NICE TO MEET YOU XXX

CLIENT: PLEASE START TLS

(here someone inserts this message)

SERVER: SORRY I DON'T HAVE THIS CAPABILITY

CLIENT: BYE

(the client notifies the user that the secure connection was not possible)
@end quotation

This method, if implemented properly, is far better than the
traditional method, and the security properties remain the same, since
only denial of service is possible. The benefit is that the server may
request additional data before the @acronym{TLS} Handshake protocol
starts, in order to send the correct certificate, use the correct
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
defined in the header file @file{gnutls/gnutls.h}.  This must be
included in all programs that make use of the @acronym{GnuTLS}
library.

The extra functionality of the @acronym{GnuTLS-extra} library is
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
indeed one which fits all requirements.  Even with binary
compatibility new features may have been introduced but due to problem
with the dynamic linker an old version is actually used.  So you may
want to check that the version is okay right after program startup.
See the function @ref{gnutls_check_version}.

@node Building the source
@subsection Building the source

If you want to compile a source file including the `gnutls/gnutls.h'
header file, you must make sure that the compiler can find it in the
directory hierarchy.  This is accomplished by adding the path to the
directory in which the header file is located to the compilers include
file search path (via the -I option).

However, the path to the include file is determined at the time the
source is configured.  To solve this problem, @acronym{GnuTLS} ships
with two small helper programs @command{libgnutls-config} and
@command{libgnutls-extra-config} that knows about the path to the
include file and other configuration options.  The options that need
to be added to the compiler invocation at compile time are output by
the @code{--cflags} option to @command{libgnutls-config}.  The
following example shows how it can be used at the command line:

@example
gcc -c foo.c `libgnutls-config --cflags`
@end example

Adding the output of @command{libgnutls-config --cflags} to the
compilers command line will ensure that the compiler can find the
@acronym{GnuTLS} header file.

A similar problem occurs when linking the program with the library.
Again, the compiler has to find the library files.  For this to work,
the path to the library files has to be added to the library search
path (via the -L option).  For this, the option @code{--libs} to
@command{libgnutls-config} can be used.  For convenience, this option
also outputs all other options that are required to link the program
with the @acronym{GnuTLS} libararies.  The example shows how to link
`foo.o' with the @acronym{GnuTLS} libraries to a program @emph{foo}.

@example
gcc -o foo foo.o `libgnutls-config --libs`
@end example

Of course you can also combine both examples to a single command by
specifying both options to `libgnutls-config':

@example
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
parts of the crypto backend, such as the random generator, are
not. Since @emph{libgcrypt 1.1.92} there was an automatic detection of
the thread library used by the application, so most applications
wouldn't need to do any changes to ensure thread-safety. Due to the
unportability of the automatic thread detection, this was removed from
later releases of @emph{libgcrypt}, so applications have now to
register callback functions to ensure proper locking in sensitive
parts of @emph{libgcrypt}.

There are helper macros to help you properly initialize the libraries.
Examples are shown below.

@itemize

@item POSIX threads
@example
#include <gnutls.h>
#include <gcrypt.h>
#include <errno.h>
#include <pthread.h>
GCRY_THREAD_OPTION_PTHREAD_IMPL;

int main() 
@{
   /* The order matters.
    */
   gcry_control (GCRYCTL_SET_THREAD_CBS, &gcry_threads_pthread);
   gnutls_global_init();
@}
@end example

@item GNU PTH threads
@example
#include <gnutls.h>
#include <gcrypt.h>
#include <errno.h>
#include <pth.h>
GCRY_THREAD_OPTION_PTH_IMPL;

int main() 
@{
   gcry_control (GCRYCTL_SET_THREAD_CBS, &gcry_threads_pth);
   gnutls_global_init();
@}
@end example

@item Other thread packages
@example
/* The gcry_thread_cbs structure must have been
 * initialized.
 */
static struct gcry_thread_cbs gcry_threads_other = @{ ... @};

int main()
@{
   gcry_control (GCRYCTL_SET_THREAD_CBS, &gcry_threads_other);
@}
@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
authentication.  This means no external certificates or passwords are
needed to set up the connection.  As could be expected, the connection
is vulnerable to man-in-the-middle (active or redirection) attacks.
However, the data is integrity and privacy protected.

@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
communicates with servers that use @acronym{X.509} or
@acronym{OpenPGP} certificate authentication. The following client is
a very simple @acronym{TLS} client, it does not support session
resuming, not even certificate verification. The TCP functions defined
in this example are used in most of the other examples below, without
redefining them.

@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
the current established session.  This includes the underlying ciphers
and the protocols involved.  That is the purpose of the following
function.  Note that this function will print meaningful values only
if called after a successful @ref{gnutls_handshake}.

@verbatiminclude examples/ex-session-info.c

@node Verifying peer's certificate
@subsection Verifying peer's certificate
@anchor{ex:verify}

A @acronym{TLS} session is not secure just after the handshake
procedure has finished.  It must be considered secure, only after the
peer's certificate and identity have been verified. That is, you have
to verify the signature in peer's certificate, the hostname in the
certificate, and expiration dates.  Just after this step you should
treat the connection as being a secure one.

@verbatiminclude examples/ex-rfc2818.c

An other example is listed below which provides a more detailed
verification output.

@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
pairs, and may not want to load all of them in the credentials
structure.  The following example demonstrates the use of the
certificate selection callback.

@verbatiminclude examples/ex-cert-select.c

@node Client with Resume capability example
@subsection Client with Resume capability example
@anchor{ex:resume-client}

This is a modification of the simple client example. Here we
demonstrate the use of session resumption. The client tries to connect
once using @acronym{TLS}, close the connection and then try to
establish a new connection using the previously negotiated data.

@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}
client which connects to a server and authenticates using a
@emph{username} and a @emph{password}. The server may authenticate
itself using a certificate, and in that case it has to be verified.

@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
@acronym{X.509} authentication, using the RSA ciphersuites.

@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}
authentication.  This server supports the export-grade cipher suites,
the DHE ciphersuites and session resuming.

@verbatiminclude examples/ex-serv-export.c

@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
@acronym{@acronym{OpenPGP}} key authentication. You can easily combine
this functionality ---that is have a server that supports both
@acronym{X.509} and @acronym{OpenPGP} certificates--- but we separated
them to keep these examples as simple as possible.

@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
also possible to combine this functionality with a certificate
server. Here it is separate for simplicity.

@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
used to serve the example client for anonymous authentication.

@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
current session.

@verbatiminclude examples/ex-alert.c

@node X.509 certificate parsing example
@subsection @acronym{X.509} certificate parsing example
@anchor{ex:x509-info}

To demonstrate the @acronym{X.509} parsing capabilities an example program is
listed below.  That program reads the peer's certificate, and prints
information about it.

@verbatiminclude examples/ex-x509-info.c

@node Certificate request generation
@subsection Certificate request generation
@anchor{ex:crq}

The following example is about generating a certificate request, and a
private key. A certificate request can be later be processed by a CA,
which should return a signed certificate.

@verbatiminclude examples/ex-crq.c

@node PKCS #12 structure generation
@subsection @acronym{PKCS} #12 structure generation
@anchor{ex:pkcs12}

The following example is about generating a @acronym{PKCS} #12
structure.

@verbatiminclude examples/ex-pkcs12.c

@node Compatibility with the OpenSSL library
@section Compatibility with the OpenSSL library
@cindex OpenSSL

To ease @acronym{GnuTLS}' integration with existing applications, a
compatibility layer with the widely used OpenSSL library is included
in the @code{gnutls-openssl} library. This compatibility layer is not
complete and it is not intended to completely reimplement the OpenSSL
API with @acronym{GnuTLS}.  It only provides source-level
compatibility. There is currently no attempt to make it
binary-compatible with OpenSSL.

The prototypes for the compatibility functions are in the
@file{gnutls/openssl.h} header file.

Current limitations imposed by the compatibility layer include:

@itemize

@item Error handling is not thread safe.

@end itemize

@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{srptool}
@cindex srptool

The @file{srptool} is a very simple program that emulates the programs
in the @emph{Stanford SRP libraries}.  It is intended for use in
places where you don't expect @acronym{SRP} authentication to be the
used for system users.  Traditionally @emph{libsrp} used two
files. One called 'tpasswd' which holds usernames and verifiers, and
'tpasswd.conf' which holds generators and primes.

How to use srptool:

@itemize

@item
To create tpasswd.conf which holds the g and n values for
@acronym{SRP} protocol (generator and a large prime), run:

@example
$ srptool --create-conf /etc/tpasswd.conf
@end example

@item
This command will create /etc/tpasswd and will add user 'test' (you
will also be prompted for a password). Verifiers are stored by default
in the way libsrp expects.

@example
$ srptool --passwd /etc/tpasswd \
    --passwd-conf /etc/tpasswd.conf -u test
@end example

@item
This command will check against a password. If the password matches
the one in /etc/tpasswd you will get an ok.

@example
$ srptool --passwd /etc/tpasswd \
    --passwd-conf /etc/tpasswd.conf --verify -u test
@end example

@end itemize

@node Invoking gnutls-cli
@section Invoking gnutls-cli
@cindex gnutls-cli

Simple client program to set up a TLS connection to some other
computer.  It sets up a TLS connection and forwards data from the
standard input to the secured socket and vice versa.

@verbatim
GNU TLS test client
Usage:  gnutls-cli [options] hostname

     -d, --debug integer      Enable debugging
     -r, --resume             Connect, establish a session. Connect
                              again and resume this session.
     -s, --starttls           Connect, establish a plain session and
                              start TLS when EOF or a SIGALRM is
                              received.
     --crlf                   Send CR LF instead of LF.
     --x509fmtder             Use DER format for certificates to read
                              from.
     -f, --fingerprint        Send the openpgp fingerprint, instead
                              of the key.
     --disable-extensions     Disable all the TLS extensions.
     --xml                    Print the certificate information in
                              XML format.
     --print-cert             Print the certificate in PEM format.
     -p, --port integer       The port to connect to.
     --recordsize integer     The maximum record size to advertize.
     -V, --verbose            More verbose output.
     --ciphers cipher1 cipher2...
                              Ciphers to enable.
     --protocols protocol1 protocol2...
                              Protocols to enable.
     --comp comp1 comp2...    Compression methods to enable.
     --macs mac1 mac2...      MACs to enable.
     --kx kx1 kx2...          Key exchange methods to enable.
     --ctypes certType1 certType2...
                              Certificate types to enable.
     --x509cafile FILE        Certificate file to use.
     --x509crlfile FILE       CRL file to use.
     --pgpkeyfile FILE        PGP Key file to use.
     --pgpkeyring FILE        PGP Key ring file to use.
     --pgptrustdb FILE        PGP trustdb file to use.
     --pgpcertfile FILE       PGP Public Key (certificate) file to
                              use.
     --x509keyfile FILE       X.509 key file to use.
     --x509certfile FILE      X.509 Certificate file to use.
     --srpusername NAME       SRP username to use.
     --srppasswd PASSWD       SRP password to use.
     --insecure               Don't abort program if server
                              certificate can't be validated.
     -l, --list               Print a list of the supported
                              algorithms  and modes.
     -h, --help               prints this help
     -v, --version            prints the program's version number
     --copyright              prints the program's license
@end verbatim

@node Invoking gnutls-cli-debug
@section Invoking gnutls-cli-debug
@cindex gnutls-cli-debug

This program was created to assist in debugging @acronym{GnuTLS}, but
it might be useful to extract a @acronym{TLS} server's capabilities.
It's purpose is to connect onto a @acronym{TLS} server, perform some
tests and print the server's capabilities. If called with the `-v'
parameter a more checks will be performed. An example output is:

@smallexample
crystal:/cvs/gnutls/src$ ./gnutls-cli-debug localhost -p 5556
Resolving 'localhost'...
Connecting to '127.0.0.1:5556'...
Checking for TLS 1.1 support... yes
Checking fallback from TLS 1.1 to... N/A
Checking for TLS 1.0 support... yes
Checking for SSL 3.0 support... yes
Checking for version rollback bug in RSA PMS... no
Checking for version rollback bug in Client Hello... no
Checking whether we need to disable TLS 1.0... N/A
Checking whether the server ignores the RSA PMS version... no
Checking whether the server can accept Hello Extensions... yes
Checking whether the server can accept cipher suites not in SSL 3.0 spec... yes
Checking whether the server can accept a bogus TLS record version in the client hello... yes
Checking for certificate information... N/A
Checking for trusted CAs... N/A
Checking whether the server understands TLS closure alerts... yes
Checking whether the server supports session resumption... yes
Checking for export-grade ciphersuite support... no
Checking RSA-export ciphersuite info... N/A
Checking for anonymous authentication support... no
Checking anonymous Diffie Hellman group info... N/A
Checking for ephemeral Diffie Hellman support... no
Checking ephemeral Diffie Hellman group info... N/A
Checking for AES cipher support (TLS extension)... yes
Checking for 3DES cipher support... yes
Checking for ARCFOUR 128 cipher support... yes
Checking for ARCFOUR 40 cipher support... no
Checking for MD5 MAC support... yes
Checking for SHA1 MAC support... yes
Checking for RIPEMD160 MAC support (TLS extension)... yes
Checking for ZLIB compression support (TLS extension)... yes
Checking for LZO compression support (GnuTLS extension)... yes
Checking for max record size (TLS extension)... yes
Checking for SRP authentication support (TLS extension)... yes
Checking for OpenPGP authentication support (TLS extension)... no
@end smallexample

@node Invoking gnutls-serv
@section Invoking gnutls-serv
@cindex gnutls-serv

Simple server program that listens to incoming TLS connections.

@verbatim
GNU TLS test server
Usage: gnutls-serv [options]

     -d, --debug integer      Enable debugging
     -g, --generate           Generate Diffie Hellman Parameters.
     -p, --port integer       The port to connect to.
     -q, --quiet              Suppress some messages.
     --nodb                   Does not use the resume database.
     --http                   Act as an HTTP Server.
     --echo                   Act as an Echo Server.
     --dhparams FILE          DH params file to use.
     --x509fmtder             Use DER format for certificates
     --x509cafile FILE        Certificate file to use.
     --x509crlfile FILE       CRL file to use.
     --pgpkeyring FILE        PGP Key ring file to use.
     --pgptrustdb FILE        PGP trustdb file to use.
     --pgpkeyfile FILE        PGP Key file to use.
     --pgpcertfile FILE       PGP Public Key (certificate) file to
                              use.
     --x509keyfile FILE       X.509 key file to use.
     --x509certfile FILE      X.509 Certificate file to use.
     --x509dsakeyfile FILE    Alternative X.509 key file to use.
     --x509dsacertfile FILE   Alternative X.509 certificate file to
                              use.
     --srppasswd FILE         SRP password file to use.
     --srppasswdconf FILE     SRP password conf file to use.
     --ciphers cipher1 cipher2...
                              Ciphers to enable.
     --protocols protocol1 protocol2...
                              Protocols to enable.
     --comp comp1 comp2...    Compression methods to enable.
     --macs mac1 mac2...      MACs to enable.
     --kx kx1 kx2...          Key exchange methods to enable.
     --ctypes certType1 certType2...
                              Certificate types to enable.
     -l, --list               Print a list of the supported
                              algorithms  and modes.
     -h, --help               prints this help
     -v, --version            prints the program's version number
     --copyright              prints the program's license
@end verbatim

@node Invoking certtool
@section Invoking certtool
@cindex certtool

This is a program to generate @acronym{X.509} certificates, certificate
requests, CRLs and private keys. The program can be used interactively
or non interactively by specifying the @code{--template} command line
option. See below for an example of a template file.

How to use certtool interactively:

@itemize
@item
To generate parameters for Diffie Hellman key exchange, use the command:
@example
$ certtool --generate-dh-params --outfile dh.pem
@end example

@item
To generate parameters for the RSA-EXPORT key exchange, use the command:
@example
$ certtool --generate-privkey --bits 512 --outfile rsa.pem
@end example

@end itemize

@itemize

@item
To create a self signed certificate, use the command:
@example
$ certtool --generate-privkey --outfile ca-key.pem
$ certtool --generate-self-signed --load-privkey ca-key.pem \
   --outfile ca-cert.pem
@end example

Note that a self-signed certificate usually belongs to a certificate
authority, that signs other certificates.

@item
To create a private key, run:

@example
$ certtool --generate-privkey --outfile key.pem
@end example

@item
To create a certificate request, run:

@example
$ certtool --generate-request --load-privkey key.pem \
  --outfile request.pem
@end example

@item
To generate a certificate using the previous request, use the command:

@example
$ certtool --generate-certificate --load-request request.pem \
   --outfile cert.pem \
   --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem
@end example

@item
To view the certificate information, use:

@example
$ certtool --certificate-info --infile cert.pem
@end example

@item
To generate a @acronym{PKCS} #12 structure using the previous key and
certificate, use the command:

@example
$ certtool --load-certificate cert.pem --load-privkey key.pem \
  --to-p12 --outder --outfile key.p12
@end example

@end itemize

Certtool's template file format:

@itemize

@item
Firstly create a file named 'cert.cfg' that contains the information
about the certificate. An example file is listed below.

@item
Then execute:

@example
$ certtool --generate-certificate cert.pem --load-privkey key.pem  \
   --template cert.cfg \
   --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem
@end example

@end itemize

An example certtool template file:

@example
# X.509 Certificate options
#
# DN options

# The organization of the subject.
organization = "Koko inc."

# The organizational unit of the subject.
unit = "sleeping dept."

# The locality of the subject.
# locality =

# The state of the certificate owner.
state = "Attiki"

# The country of the subject. Two letter code.
country = GR

# The common name of the certificate owner.
cn = "Cindy Lauper"

# A user id of the certificate owner.
#uid = "clauper"

# If the supported DN OIDs are not adequate you can set
# any OID here.
# For example set the X.520 Title and the X.520 Pseudonym
# by using OID and string pairs.
#dn_oid = "2.5.4.12" "Dr." "2.5.4.65" "jackal"

# This is deprecated and should not be used in new
# certificates.
# pkcs9_email = "none@@none.org"

# The serial number of the certificate
serial = 007

# In how many days, counting from today, this certificate will expire.
expiration_days = 700

# X.509 v3 extensions

# A dnsname in case of a WWW server.
#dns_name = "www.none.org"

# An IP address in case of a server.
#ip_address = "192.168.1.1"

# An email in case of a person
email = "none@@none.org"

# An URL that has CRLs (certificate revocation lists)
# available. Needed in CA certificates.
#crl_dist_points = "http://www.getcrl.crl/getcrl/"

# Whether this is a CA certificate or not
#ca

# Whether this certificate will be used for a TLS client
#tls_www_client

# Whether this certificate will be used for a TLS server
#tls_www_server

# Whether this certificate will be used to sign data (needed
# in TLS DHE ciphersuites).
signing_key

# Whether this certificate will be used to encrypt data (needed
# in TLS RSA ciphersuites). Note that it is prefered to use different
# keys for encryption and signing.
#encryption_key

# Whether this key will be used to sign other certificates.
#cert_signing_key

# Whether this key will be used to sign CRLs.
#crl_signing_key

# Whether this key will be used to sign code.
#code_signing_key

# Whether this key will be used to sign OCSP data.
#ocsp_signing_key

# Whether this key will be used for time stamping.
#time_stamping_key
@end example

@node Function reference
@chapter Function reference
@cindex Function reference

@menu
* Core functions::
* X.509 certificate functions::
* GnuTLS-extra functions::
* OpenPGP functions::
* Error codes and descriptions::
@end menu

@node Core functions
@section Core functions

The prototypes for the following functions lie in
@file{gnutls/gnutls.h}.

@include gnutls-api.texi

@node X.509 certificate functions
@section @acronym{X.509} certificate functions
@anchor{sec:x509api}
@cindex @acronym{X.509} Functions

The following functions are to be used for @acronym{X.509} certificate handling.
Their prototypes lie in @file{gnutls/x509.h}.

@include x509-api.texi

@node GnuTLS-extra functions
@section @acronym{GnuTLS-extra} functions
@cindex @acronym{GnuTLS-extra} functions

These functions are only available in the GPL version of the library
called @code{gnutls-extra}. The prototypes for this library lie in
@file{gnutls/extra.h}.

@include gnutls-extra-api.texi

@node OpenPGP functions
@section @acronym{OpenPGP} functions
@cindex @acronym{OpenPGP} functions
@anchor{sec:openpgpapi}

The following functions are to be used for @acronym{OpenPGP} certificate
handling.  Their prototypes lie in @file{gnutls/openpgp.h}.

@include pgp-api.texi

@node Error codes and descriptions
@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
functions:

@itemize

@item @ref{gnutls_x509_crt_to_xml}

@item @ref{gnutls_openpgp_key_to_xml}

@end itemize

@menu
* An X.509 certificate::
* An OpenPGP key::
@end menu

@node An X.509 certificate
@section An @acronym{X.509} certificate

@smallexample
<?xml version="1.0" encoding="UTF-8"?>

<gnutls:x509:certificate version="1.1">
 <certificate type="SEQUENCE">
  <tbsCertificate type="SEQUENCE">
    <version type="INTEGER" encoding="HEX">02</version>
    <serialNumber type="INTEGER" encoding="HEX">01</serialNumber>
    <signature type="SEQUENCE">
      <algorithm type="OBJECT ID">1.2.840.113549.1.1.4</algorithm>
      <parameters type="ANY">
        <md5WithRSAEncryption encoding="HEX">0500</md5WithRSAEncryption>
      </parameters>
    </signature>
    <issuer type="CHOICE">
      <rdnSequence type="SEQUENCE OF">
        <unnamed1 type="SET OF">
          <unnamed1 type="SEQUENCE">
            <type type="OBJECT ID">2.5.4.6</type>
            <value type="ANY">
              <X520countryName>GR</X520countryName>
            </value>
          </unnamed1>
        </unnamed1>
        <unnamed2 type="SET OF">
          <unnamed1 type="SEQUENCE">
            <type type="OBJECT ID">2.5.4.8</type>
            <value type="ANY">
              <X520StateOrProvinceName>Attiki</X520StateOrProvinceName>
            </value>
          </unnamed1>
        </unnamed2>
        <unnamed3 type="SET OF">
          <unnamed1 type="SEQUENCE">
            <type type="OBJECT ID">2.5.4.7</type>
            <value type="ANY">
              <X520LocalityName>Athina</X520LocalityName>
            </value>
          </unnamed1>
        </unnamed3>
        <unnamed4 type="SET OF">
          <unnamed1 type="SEQUENCE">
            <type type="OBJECT ID">2.5.4.10</type>
            <value type="ANY">
              <X520OrganizationName>GNUTLS</X520OrganizationName>
            </value>
          </unnamed1>
        </unnamed4>
        <unnamed5 type="SET OF">
          <unnamed1 type="SEQUENCE">
            <type type="OBJECT ID">2.5.4.11</type>
            <value type="ANY">
              <X520OrganizationalUnitName>GNUTLS dev.</X520OrganizationalUnitName>
            </value>
          </unnamed1>
        </unnamed5>
        <unnamed6 type="SET OF">
          <unnamed1 type="SEQUENCE">
            <type type="OBJECT ID">2.5.4.3</type>
            <value type="ANY">
              <X520CommonName>GNUTLS TEST CA</X520CommonName>
            </value>
          </unnamed1>
        </unnamed6>
        <unnamed7 type="SET OF">
          <unnamed1 type="SEQUENCE">
            <type type="OBJECT ID">1.2.840.113549.1.9.1</type>
            <value type="ANY">
              <Pkcs9email>gnutls-dev@@gnupg.org</Pkcs9email>
            </value>
          </unnamed1>
        </unnamed7>
      </rdnSequence>
    </issuer>
    <validity type="SEQUENCE">
      <notBefore type="CHOICE">
        <utcTime type="TIME">010707101845Z</utcTime>
      </notBefore>
      <notAfter type="CHOICE">
        <utcTime type="TIME">020707101845Z</utcTime>
      </notAfter>
    </validity>
    <subject type="CHOICE">
      <rdnSequence type="SEQUENCE OF">
        <unnamed1 type="SET OF">
          <unnamed1 type="SEQUENCE">
            <type type="OBJECT ID">2.5.4.6</type>
            <value type="ANY">
              <X520countryName>GR</X520countryName>
            </value>
          </unnamed1>
        </unnamed1>
        <unnamed2 type="SET OF">
          <unnamed1 type="SEQUENCE">
            <type type="OBJECT ID">2.5.4.8</type>
            <value type="ANY">
              <X520StateOrProvinceName>Attiki</X520StateOrProvinceName>
            </value>
          </unnamed1>
        </unnamed2>
        <unnamed3 type="SET OF">
          <unnamed1 type="SEQUENCE">
            <type type="OBJECT ID">2.5.4.7</type>
            <value type="ANY">
              <X520LocalityName>Athina</X520LocalityName>
            </value>
          </unnamed1>
        </unnamed3>
        <unnamed4 type="SET OF">
          <unnamed1 type="SEQUENCE">
            <type type="OBJECT ID">2.5.4.10</type>
            <value type="ANY">
              <X520OrganizationName>GNUTLS</X520OrganizationName>
            </value>
          </unnamed1>
        </unnamed4>
        <unnamed5 type="SET OF">
          <unnamed1 type="SEQUENCE">
            <type type="OBJECT ID">2.5.4.11</type>
            <value type="ANY">
              <X520OrganizationalUnitName>GNUTLS dev.</X520OrganizationalUnitName>
            </value>
          </unnamed1>
        </unnamed5>
        <unnamed6 type="SET OF">
          <unnamed1 type="SEQUENCE">
            <type type="OBJECT ID">2.5.4.3</type>
            <value type="ANY">
              <X520CommonName>localhost</X520CommonName>
            </value>
          </unnamed1>
        </unnamed6>
        <unnamed7 type="SET OF">
          <unnamed1 type="SEQUENCE">
            <type type="OBJECT ID">1.2.840.113549.1.9.1</type>
            <value type="ANY">
              <Pkcs9email>root@@localhost</Pkcs9email>
            </value>
          </unnamed1>
        </unnamed7>
      </rdnSequence>
    </subject>
    <subjectPublicKeyInfo type="SEQUENCE">
      <algorithm type="SEQUENCE">
        <algorithm type="OBJECT ID">1.2.840.113549.1.1.1</algorithm>
        <parameters type="ANY">
          <rsaEncryption encoding="HEX">0500</rsaEncryption>
        </parameters>
      </algorithm>
      <subjectPublicKey type="BIT STRING" encoding="HEX" length="1120">
      30818902818100D00B49EBB226D951F5CC57072199DDF287683D2DA1A0E
      FCC96BFF73164777C78C3991E92EDA66584E7B97BAB4BE68D595D225557
      E01E7E57B5C35C04B491948C5C427AD588D8C6989764996D6D44E17B65C
      CFC86F3B4842DE559B730C1DE3AEF1CE1A328AFF8A357EBA911E1F7E8FC
      1598E21E4BF721748C587F50CF46157D950203010001</subjectPublicKey>
    </subjectPublicKeyInfo>
    <extensions type="SEQUENCE OF">
      <unnamed1 type="SEQUENCE">
        <extnID type="OBJECT ID">2.5.29.35</extnID>
        <critical type="BOOLEAN">FALSE</critical>
        <extnValue type="SEQUENCE">
          <keyIdentifier type="OCTET STRING" encoding="HEX">
          EFEE94ABC8CA577F5313DB76DC1A950093BAF3C9</keyIdentifier>
        </extnValue>
      </unnamed1>
      <unnamed2 type="SEQUENCE">
        <extnID type="OBJECT ID">2.5.29.37</extnID>
        <critical type="BOOLEAN">FALSE</critical>
        <extnValue type="SEQUENCE OF">
          <unnamed1 type="OBJECT ID">1.3.6.1.5.5.7.3.1</unnamed1>
          <unnamed2 type="OBJECT ID">1.3.6.1.5.5.7.3.2</unnamed2>
          <unnamed3 type="OBJECT ID">1.3.6.1.4.1.311.10.3.3</unnamed3>
          <unnamed4 type="OBJECT ID">2.16.840.1.113730.4.1</unnamed4>
        </extnValue>
      </unnamed2>
      <unnamed3 type="SEQUENCE">
        <extnID type="OBJECT ID">2.5.29.19</extnID>
        <critical type="BOOLEAN">TRUE</critical>
        <extnValue type="SEQUENCE">
          <cA type="BOOLEAN">FALSE</cA>
        </extnValue>
      </unnamed3>
    </extensions>
  </tbsCertificate>
  <signatureAlgorithm type="SEQUENCE">
    <algorithm type="OBJECT ID">1.2.840.113549.1.1.4</algorithm>
    <parameters type="ANY">
      <md5WithRSAEncryption encoding="HEX">0500</md5WithRSAEncryption>
    </parameters>
  </signatureAlgorithm>
  <signature type="BIT STRING" encoding="HEX" length="1024">
  B73945273AF2A395EC54BF5DC669D953885A9D811A3B92909D24792D36A44EC
  27E1C463AF8738BEFD29B311CCE8C6D9661BEC30911DAABB39B8813382B32D2
  E259581EBCD26C495C083984763966FF35D1DEFE432891E610C85072578DA74
  23244A8F5997B41A1F44E61F4F22C94375775055A5E72F25D5E4557467A91BD
  4251</signature>
 </certificate>
</gnutls:x509:certificate>
@end smallexample

@node An OpenPGP key
@section An @acronym{OpenPGP} key

@smallexample
<?xml version="1.0"?>

<gnutls:openpgp:key version="1.0">
 <OPENPGPKEY>
  <MAINKEY>
    <KEYID>BD572CDCCCC07C3</KEYID>
    <FINGERPRINT>BE615E88D6CFF27225B8A2E7BD572CDCCCC07C35</FINGERPRINT>
    <PKALGO>DSA</PKALGO>
    <KEYLEN>1024</KEYLEN>
    <CREATED>1011533164</CREATED>
    <REVOKED>0</REVOKED>
    <KEY ENCODING="HEX"/>
    <DSA-P>0400E72E76B62EEFA9A3BD594093292418050C02D7029D6CA2066E
    FC34C86038627C643EB1A652A7AF1D37CF46FC505AC1E0C699B37895B4BCB
    3E53541FFDA4766D6168C2B8AAFD6AB22466D06D18034D5DAC698E6993BA5
    B350FF822E1CD8702A75114E8B73A6B09CB3B93CE44DBB516C9BB5F95BB66
    6188602A0A1447236C0658F</DSA-P>
    <DSA-Q>00A08F5B5E78D85F792CC2072F9474645726FB4D9373</DSA-Q>
    <DSA-G>03FE3578D689D6606E9118E9F9A7042B963CF23F3D8F1377A273C0
    F0974DBF44B3CABCBE14DD64412555863E39A9C627662D77AC36662AE4497
    92C3262D3F12E9832A7565309D67BA0AE4DF25F5EDA0937056AD5BE89F406
    9EBD7EC76CE432441DF5D52FFFD06D39E5F61E36947B698A77CB62AB81E4A
    4122BF9050671D9946C865E</DSA-G>
    <DSA-Y>0400D061437A964DDE318818C2B24DE008E60096B60DB8A684B85A
    838D119FC930311889AD57A3B927F448F84EB253C623EDA73B42FF78BCE63
    A6A531D75A64CE8540513808E9F5B10CE075D3417B801164918B131D3544C
    8765A8ECB9971F61A09FC73D509806106B5977D211CB0E1D04D0ED96BCE89
    BAE8F73D800B052139CBF8D</DSA-Y>
  </MAINKEY>
  <USERID>
    <NAME>OpenCDK test key (Only intended for test purposes!)</NAME>
    <EMAIL>opencdk@@foo-bar.org</EMAIL>
    <PRIMARY>0</PRIMARY>
    <REVOKED>0</REVOKED>
  </USERID>
  <SIGNATURE>
    <VERSION>4</VERSION>
    <SIGCLASS>19</SIGCLASS>
    <EXPIRED>0</EXPIRED>
    <PKALGO>DSA</PKALGO>
    <MDALGO>SHA1</MDALGO>
    <CREATED>1011533164</CREATED>
    <KEYID>BD572CDCCCC07C3</KEYID>
  </SIGNATURE>
  <SUBKEY>
    <KEYID>FCB0CF3A5261E06</KEYID>
    <FINGERPRINT>297B48ACC09C0FF683CA1ED1FCB0CF3A5261E067</FINGERPRINT>
    <PKALGO>ELG</PKALGO>
    <KEYLEN>1024</KEYLEN>
    <CREATED>1011533167</CREATED>
    <REVOKED>0</REVOKED>
    <KEY ENCODING="HEX"/>
    <ELG-P>0400E20156526069D067D24F4D71E6D38658E08BE3BF246C1ADCE0
    8DB69CD8D459C1ED335738410798755AFDB79F1797CF022E70C7960F12CA6
    896D27CFD24A11CD316DDE1FBCC1EA615C5C31FEC656E467078C875FC509B
    1ECB99C8B56C2D875C50E2018B5B0FA378606EB6425A2533830F55FD21D64
    9015615D49A1D09E9510F5F</ELG-P>
    <ELG-G>000305</ELG-G>
    <ELG-Y>0400D0BDADE40432758675C87D0730C360981467BAE1BEB6CC105A
    3C1F366BFDBEA12E378456513238B8AD414E52A2A9661D1DF1DB6BB5F33F6
    906166107556C813224330B30932DB7C8CC8225672D7AE24AF2469750E539
    B661EA6475D2E03CD8D3838DC4A8AC4AFD213536FE3E96EC9D0AEA65164B5
    76E01B37A8DCA89F2B257D0</ELG-Y>
  </SUBKEY>
  <SIGNATURE>
    <VERSION>4</VERSION>
    <SIGCLASS>24</SIGCLASS>
    <EXPIRED>0</EXPIRED>
    <PKALGO>DSA</PKALGO>
    <MDALGO>SHA1</MDALGO>
    <CREATED>1011533167</CREATED>
    <KEYID>BD572CDCCCC07C3</KEYID>
  </SIGNATURE>
 </OPENPGPKEY>
</gnutls:openpgp:key>
@end smallexample

@node All the supported ciphersuites in GnuTLS
@chapter All the supported ciphersuites in @acronym{GnuTLS}
@anchor{ciphersuites}
@cindex Ciphersuites

@multitable @columnfractions .45 .20 .35

@item @code{TLS_RSA_NULL_MD5} 
@tab 0x00 0x01
@tab RFC 2246

@item @code{TLS_ANON_DH_3DES_EDE_CBC_SHA} 
@tab 0x00 0x1B
@tab RFC 2246

@item @code{TLS_ANON_DH_ARCFOUR_MD5}
@tab 0x00 0x18
@tab RFC 2246

@item @code{TLS_ANON_DH_AES_128_CBC_SHA}
@tab 0x00 0x34
@tab RFC 2246

@item @code{TLS_ANON_DH_AES_256_CBC_SHA}
@tab 0x00 0x3A
@tab RFC 2246

@item @code{TLS_RSA_ARCFOUR_SHA}
@tab 0x00 0x05
@tab  RFC 2246

@item @code{TLS_RSA_ARCFOUR_MD5}
@tab 0x00 0x04
@tab RFC 2246

@item @code{TLS_RSA_3DES_EDE_CBC_SHA}
@tab 0x00 0x0A
@tab RFC 2246

@item @code{TLS_RSA_EXPORT_ARCFOUR_40_MD5}
@tab 0x00 0x03
@tab RFC 2246

@item @code{TLS_DHE_DSS_3DES_EDE_CBC_SHA}
@tab 0x00 0x13
@tab RFC 2246

@item @code{TLS_DHE_RSA_3DES_EDE_CBC_SHA}
@tab 0x00 0x16
@tab RFC 2246

@item @code{TLS_RSA_AES_128_CBC_SHA}
@tab 0x00 0x2F
@tab RFC 3268

@item @code{TLS_RSA_AES_128_CBC_SHA}
@tab 0x00 0x35
@tab RFC 3268

@item @code{TLS_DHE_DSS_AES_256_CBC_SHA}
@tab 0x00 0x38
@tab RFC 3268

@item @code{TLS_DHE_DSS_AES_128_CBC_SHA}
@tab 0x00 0x32
@tab RFC 3268

@item @code{TLS_DHE_RSA_AES_256_CBC_SHA}
@tab 0x00 0x39
@tab RFC 3268

@item @code{TLS_DHE_RSA_AES_128_CBC_SHA}
@tab 0x00 0x33
@tab RFC 3268

@item @code{TLS_SRP_SHA_3DES_EDE_CBC_SHA}
@tab 0x00 0x50
@tab draft-ietf-tls-srp

@item @code{TLS_SRP_SHA_AES_128_CBC_SHA}
@tab 0x00 0x53
@tab draft-ietf-tls-srp

@item @code{TLS_SRP_SHA_AES_256_CBC_SHA}
@tab 0x00 0x56
@tab draft-ietf-tls-srp

@item @code{TLS_SRP_SHA_RSA_3DES_EDE_CBC_SHA}
@tab 0x00 0x51
@tab draft-ietf-tls-srp

@item @code{TLS_SRP_SHA_DSS_3DES_EDE_CBC_SHA}
@tab 0x00 0x52
@tab draft-ietf-tls-srp

@item @code{TLS_SRP_SHA_RSA_AES_128_CBC_SHA}
@tab 0x00 0x54
@tab draft-ietf-tls-srp

@item @code{TLS_SRP_SHA_DSS_AES_128_CBC_SHA}
@tab 0x00 0x55
@tab draft-ietf-tls-srp

@item @code{TLS_SRP_SHA_RSA_AES_256_CBC_SHA}
@tab 0x00 0x57
@tab draft-ietf-tls-srp

@item @code{TLS_SRP_SHA_DSS_AES_256_CBC_SHA}
@tab 0x00 0x58
@tab draft-ietf-tls-srp

@item @code{TLS_DHE_DSS_3DES_EDE_CBC_RMD}
@tab 0x00 0x72
@tab draft-ietf-tls-openpgp-keys

@item @code{TLS_DHE_RSA_3DES_EDE_CBC_RMD}
@tab 0x00 0x77
@tab draft-ietf-tls-openpgp-keys

@item @code{TLS_DHE_DSS_AES_256_CBC_RMD}
@tab 0x00 0x73
@tab draft-ietf-tls-openpgp-keys

@item @code{TLS_DHE_DSS_AES_128_CBC_RMD}
@tab 0x00 0x74
@tab draft-ietf-tls-openpgp-keys

@item @code{TLS_DHE_RSA_AES_128_CBC_RMD}
@tab 0x00 0x78
@tab draft-ietf-tls-openpgp-keys

@item @code{TLS_DHE_RSA_AES_256_CBC_RMD}
@tab 0x00 0x79
@tab draft-ietf-tls-openpgp-keys

@item @code{TLS_RSA_3DES_EDE_CBC_RMD}
@tab 0x00 0x7C
@tab draft-ietf-tls-openpgp-keys

@item @code{TLS_RSA_AES_128_CBC_RMD}
@tab 0x00 0x7D
@tab draft-ietf-tls-openpgp-keys

@item @code{TLS_RSA_AES_256_CBC_RMD}
@tab 0x00 0x7E
@tab draft-ietf-tls-openpgp-keys

@item @code{TLS_DHE_DSS_ARCFOUR_SHA}
@tab 0x00 0x66
@tab draft-ietf-tls-56-bit-ciphersuites

@end multitable


@node Copying This Manual
@appendix Copying This Manual

@menu
* GNU Free Documentation License::  License for copying this manual.
@end menu

@include fdl.texi

@node Concept Index
@unnumbered Concept Index

@printindex cp

@node Function and Data Index
@unnumbered Function and Data Index

@printindex fn

@c texi2dvi has problem if unnumbered is put there. However makeinfo works great.
@c STUPID texinfo.

@c @node @mybibnode{}
@c @unnumbered @mybibnode{}
@node Bibliography
@unnumbered Bibliography
@include bibliography.texi


@bye