guile: Rename to `libguile-gnutls-v-2'.

[gnutls.git] / doc / cha-auth.texi

@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: Authenticated key exchange using public key infrastructure and certificates (X.509 or OpenPGP).

@item @acronym{SRP} authentication: Authenticated key exchange using a password.

@item @acronym{PSK} authentication: Authenticated key exchange using a pre-shared key.

@item Anonymous authentication: Key exchange without peer authentication.

@end itemize

The rule for each method is to allocate a credentials
structure containing data required for authentication and
associate that structure with the session using
@funcref{gnutls_credentials_set}. Various authentication methods might
require additional data to be stored in the credential structures,
such as ephemeral Diffie-Hellman parameters etc.
In the next paragraphs
we elaborate on supported authentication methods.

@showfuncdesc{gnutls_credentials_set}

@menu
* Certificate authentication::
* Anonymous authentication::
* Authentication using SRP::
* Authentication using PSK::
* Authentication and credentials::
@end menu

@node Certificate authentication
@section Certificate authentication

@subsection Authentication using @acronym{X.509} certificates
@cindex 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.  See @ref{X.509 certificates}, for
more information on @acronym{X.509} protocols.

@subsection Authentication using @acronym{OpenPGP} keys
@cindex 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 @xcite{TLSPGP} proposal.

More information on the @acronym{OpenPGP} trusted model is provided in @ref{OpenPGP certificates}.
For a more detailed introduction to @acronym{OpenPGP} and @acronym{GnuPG} see @xcite{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. 

@showfuncB{gnutls_certificate_allocate_credentials,gnutls_certificate_free_credentials}

After the credentials structures are initialized using the functions
above, the certificate and key pair should be loaded. This should
occur before any @acronym{TLS} session is initialized.
Depending on the certificate type different loading functions
are available, and are shown below.
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.

@showfuncD{gnutls_certificate_set_x509_key_mem,gnutls_certificate_set_openpgp_key,gnutls_certificate_set_openpgp_key_file,gnutls_certificate_set_openpgp_key_mem}
@showfuncB{gnutls_certificate_set_x509_key,gnutls_certificate_set_key}

@showfuncdesc{gnutls_certificate_set_x509_key_file}

As an alternative to loading from files, a callback may be used so that the 
server or the client can specify the certificate and the key at the handshake time.
In that case a certificate should be selected according the peer's signature
algorithm preferences. To get those preferences use
@funcref{gnutls_sign_algorithm_get_requested}. Both functions are shown below.

@showfuncdesc{gnutls_certificate_set_retrieve_function}

@showfuncdesc{gnutls_sign_algorithm_get_requested}


Certificate verification is possible by loading the trusted
authorities into the credentials structure by using
the following functions, applicable to X.509 and OpenPGP certificates.

@showfuncB{gnutls_certificate_set_x509_trust_file,gnutls_certificate_set_openpgp_keyring_file}

Note however that the peer's certificate is not automatically
verified, you should call @funcref{gnutls_certificate_verify_peers2},
after a successful handshake or during if @funcref{gnutls_certificate_set_verify_function}
has been used, to verify the certificate's signature.
An alternative way, which reports a more detailed
verification output, is to use @funcref{gnutls_certificate_get_peers} to
obtain the raw certificate of the peer and verify it using the
functions discussed in @ref{X.509 certificates}.

@showfuncdesc{gnutls_certificate_verify_peers2}

In a handshake, the negotiated cipher suite also depends on the
certificate's parameters, so some key exchange methods might not 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, that require
decryption. It is not recommended to use RSA keys for both
signing and encryption. If possible use a different key for the
@code{DHE_RSA} which uses signing and @code{RSA} that requires decryption.
All the key exchange methods shown in @ref{tab:key-exchange} are
available in certificate authentication.

@showfuncdesc{gnutls_certificate_set_verify_function}

Note that the DHE key exchange methods are generally
slower@footnote{It depends on the group used.  Primes with
lesser bits are always faster, but also easier to break.  See @ref{Selecting cryptographic key sizes}
for the acceptable security levels.} than the elliptic curves counterpart
(ECDHE). Moreover the plain Diffie-Hellman key exchange
requires parameters to be generated and associated with a credentials
structure by the server (see @ref{Parameter generation}). 

@float Table,tab:key-exchange
@multitable @columnfractions .2 .7

@headitem Key exchange @tab Description

@item RSA @tab
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 @tab
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 @tab
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 ECDHE_RSA @tab
The RSA algorithm is used to sign ephemeral elliptic curve Diffie-Hellman 
parameters which are sent to the peer. The key in the certificate must allow 
the key to be used for signing. It also offers 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 @tab
The DSA 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. DSA is the algorithm
of the Digital Signature Standard (DSS).

@item ECDHE_ECDSA @tab
The Elliptic curve DSA algorithm is used to sign ephemeral elliptic
curve Diffie-Hellman parameters which are sent to the peer. The 
certificate must contain ECDSA parameters to use this key exchange 
algorithm. 

@end multitable
@caption{Supported key exchange algorithms.}
@end float

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

The anonymous key exchange offers encryption without any
indication of the peer's identity.  This kind of authentication
is vulnerable to a man in the middle attack, but can be
used even if there is no prior communication or shared trusted parties 
with the peer. Moreover it is useful when complete anonymity is required. 
Unless in one of the above cases, do not use anonymous authentication.  

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. Check
@ref{Parameter generation} for more information.

The initialization functions for the credentials are shown below.

@showfuncD{gnutls_anon_allocate_server_credentials,gnutls_anon_allocate_client_credentials,gnutls_anon_free_server_credentials,gnutls_anon_free_client_credentials}


The available key exchange algorithms for anonymous authentication are
shown below.

@table @code

@item ANON_DH:
This algorithm exchanges Diffie-Hellman parameters.

@item ANON_ECDH:
This algorithm exchanges elliptic curve Diffie-Hellman parameters. It is more 
efficient than ANON_DH on equivalent security levels.

@end table

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

@acronym{GnuTLS} supported authentication via the Secure Remote Password 
or @acronym{SRP} protocol (see @xcite{RFC2945,TOMSRP} for a description).
The @acronym{SRP} key exchange is an extension to the
@acronym{TLS} protocol, and it provided an authenticated with a 
password key exchange. The 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} is not
susceptible to off-line dictionary attacks.
Moreover, 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 @acronym{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. 
The Stanford @acronym{SRP} libraries, include 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 users
of a system.

The implementation in @acronym{GnuTLS} is based on @xcite{TLSSRP}. The
supported key exchange methods are shown below.

@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

The initialization functions in SRP credentials differ between
client and server.

@showfuncD{gnutls_srp_allocate_server_credentials,gnutls_srp_allocate_client_credentials,gnutls_srp_free_server_credentials,gnutls_srp_free_client_credentials}

Clients supporting @acronym{SRP} should set the username and password
prior to connection, to the credentials structure.
Alternatively @funcref{gnutls_srp_set_client_credentials_function}
may be used instead, to specify a callback function that should return the
SRP username and password.
The callback is called once during the @acronym{TLS} handshake.

@showfuncA{gnutls_srp_set_client_credentials}

@showfuncdesc{gnutls_srp_set_client_credentials_function}

In server side the default behavior of @acronym{GnuTLS} is to read
the usernames and @acronym{SRP} verifiers from password files. These
password file format is compatible the with the @emph{Stanford srp libraries}
format.  If a different password file format is to be used, then 
@funcref{gnutls_srp_set_server_credentials_function} should be called,
to set an appropriate callback. 

@showfuncdesc{gnutls_srp_set_server_credentials_file}

@showfuncdesc{gnutls_srp_set_server_credentials_function}

Other helper functions are included in @acronym{GnuTLS}, 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.  See @ref{srptool}, for more information.

@showfuncdesc{gnutls_srp_verifier}

@showfuncB{gnutls_srp_base64_encode,gnutls_srp_base64_decode}


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

Authentication using Pre-shared keys is a method to authenticate using
usernames and binary keys. This protocol avoids making use of public
key infrastructure and expensive calculations, thus it is suitable for
constraint clients.

The implementation in @acronym{GnuTLS} is based on @xcite{TLSPSK}.  
The supported @acronym{PSK} key exchange methods are:

@table @code

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

@item DHE-PSK:
Authentication using the @acronym{PSK} protocol and Diffie-Hellman key
exchange.  This method offers perfect forward secrecy.

@item ECDHE-PSK:
Authentication using the @acronym{PSK} protocol and Elliptic curve Diffie-Hellman key
exchange.  This method offers perfect forward secrecy.

@end table

The initialization functions in PSK credentials differ between
client and server.

@showfuncD{gnutls_psk_allocate_server_credentials,gnutls_psk_allocate_client_credentials,gnutls_psk_free_server_credentials,gnutls_psk_free_client_credentials}

Clients supporting @acronym{PSK} should supply the username and key
before a TLS session is established.  Alternatively 
@funcref{gnutls_psk_set_client_credentials_function} can be used to
specify a callback function. This has the
advantage that the callback will be called only if @acronym{PSK} has
been negotiated.

@showfuncA{gnutls_psk_set_client_credentials}

@showfuncdesc{gnutls_psk_set_client_credentials_function}

In server side the default behavior of @acronym{GnuTLS} is to read
the usernames and @acronym{PSK} keys from a password file. The
password file should contain usernames and keys in hexadecimal
format. The name of the password file can be stored to the credentials
structure by calling @funcref{gnutls_psk_set_server_credentials_file}.  If
a different password file format is to be used, then
a callback should be set instead by @funcref{gnutls_psk_set_server_credentials_function}.

The server can help the client chose a suitable username and password,
by sending a hint. Note that there is no common profile for the PSK hint and applications
are discouraged to use it.
A server, may specify the hint by calling
@funcref{gnutls_psk_set_server_credentials_hint}.  The client can retrieve
the hint, for example in the callback function, using
@funcref{gnutls_psk_client_get_hint}.

@showfuncdesc{gnutls_psk_set_server_credentials_file}

@showfuncC{gnutls_psk_set_server_credentials_function,gnutls_psk_set_server_credentials_hint,gnutls_psk_client_get_hint}

Helper functions to generate and maintain @acronym{PSK} keys are also included
in @acronym{GnuTLS}.

@showfuncC{gnutls_key_generate,gnutls_hex_encode,gnutls_hex_decode}


@node Authentication and credentials
@section Authentication and credentials

In @acronym{GnuTLS} every key exchange method is associated with a
credentials type. For a key exchange method to be available it
must be listed as a priority string (see @ref{Priority Strings}) and
the corresponding credentials type should be initialized and set using
@funcref{gnutls_credentials_set}.  A mapping of the key exchange methods
with the credential types is shown in @ref{tab:key-exchange-cred}.

@float Table,tab:key-exchange-cred
@multitable @columnfractions .4 .25 .25

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

@item @code{KX_RSA},
@code{KX_DHE_RSA},
@code{KX_DHE_DSS},
@code{KX_ECDHE_RSA},
@code{KX_ECDHE_ECDSA},
@code{KX_RSA_EXPORT}
@tab @code{CRD_CERTIFICATE}
@tab @code{CRD_CERTIFICATE}

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

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

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

@item @code{KX_PSK},
@code{KX_DHE_PSK}, @code{KX_ECDHE_PSK}
@tab @code{CRD_PSK}
@tab @code{CRD_PSK}

@end multitable
@caption{Key exchange algorithms and the corresponding credential types.}
@end float