From c4460a9921013a9700656d55f3c701e0fed5cd2d Mon Sep 17 00:00:00 2001 From: Nikos Mavrogiannopoulos Date: Sun, 23 May 2010 19:01:00 +0200 Subject: Documentation updates. Separated big gnutls.texi to chapter to allow easier maintainance. --- doc/cha-auth.texi | 462 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 462 insertions(+) create mode 100644 doc/cha-auth.texi (limited to 'doc/cha-auth.texi') diff --git a/doc/cha-auth.texi b/doc/cha-auth.texi new file mode 100644 index 0000000000..39da7a5c9a --- /dev/null +++ b/doc/cha-auth.texi @@ -0,0 +1,462 @@ +@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 + +@item @acronym{PSK} authentication + +@end itemize + +@menu +* Certificate authentication:: +* Anonymous authentication:: +* Authentication using SRP:: +* Authentication using PSK:: +* 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 @xcite{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 @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. 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 + +Clients and servers that will select certificates using callback +functions should select a certificate according the peer's signature +algorithm preferences. To get those preferences use +@ref{gnutls_sign_algorithm_get_requested}. + +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 performs 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 @xcite{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 use 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 @xcite{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 +@xcite{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 can 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 using PSK +@section Authentication using @acronym{PSK} +@cindex @acronym{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 paper +@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. + +@end table + +Clients supporting @acronym{PSK} should supply the username and key +before the connection to the client credentials by calling the +function @ref{gnutls_psk_set_client_credentials}. Alternatively they +could specify a callback function by using the function +@ref{gnutls_psk_set_client_credentials_function}. This has the +advantage that the callback will be called only if @acronym{PSK} has +been negotiated. + +In server side the default behaviour 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 @ref{gnutls_psk_set_server_credentials_file}. If +a different password file format is to be used, then the function +@ref{gnutls_psk_set_server_credentials_function}, should be used +instead. + +The server can help the client chose a suitable username and password, +by sending a hint. In the server, specify the hint by calling +@ref{gnutls_psk_set_server_credentials_hint}. The client can retrieve +the hint, for example in the callback function, using +@ref{gnutls_psk_client_get_hint}. + +There is no standard mechanism to derive a PSK key from a password +specified by the TLS PSK document. However, GnuTLS provides +@ref{gnutls_psk_netconf_derive_key} which follows the algorithm +specified in @file{draft-ietf-netconf-tls-02.txt}. + +Some helper functions such as: + +@itemize + +@item @ref{gnutls_hex_encode} + +@item @ref{gnutls_hex_decode} + +@end itemize + +are included in @acronym{GnuTLS}, and may be used to generate and +maintain @acronym{PSK} keys. + + +@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} + +@item @code{KX_PSK} +@tab @code{CRD_PSK} +@tab @code{CRD_PSK} + +@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_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 -- cgit v1.2.1