doc/cha-auth.texi

   1 @node Authentication methods
   2 @chapter Authentication Methods
   3
   4 The @acronym{TLS} protocol provides confidentiality and encryption,
   5 but also offers authentication, which is a prerequisite for a secure
   6 connection. The available authentication methods in @acronym{GnuTLS}
   7 are:
   8
   9 @itemize
  10
  11 @item Certificate authentication
  12
  13 @item Anonymous authentication
  14
  15 @item @acronym{SRP} authentication
  16
  17 @item @acronym{PSK} authentication
  18
  19 @end itemize
  20
  21 @menu
  22 * Certificate authentication::
  23 * Anonymous authentication::
  24 * Authentication using SRP::
  25 * Authentication using PSK::
  26 * Authentication and credentials::
  27 * Parameters stored in credentials::
  28 @end menu
  29
  30 @node Certificate authentication
  31 @section Certificate Authentication
  32
  33 @subsection Authentication Using @acronym{X.509} Certificates
  34 @cindex @acronym{X.509} certificates
  35
  36 @acronym{X.509} certificates contain the public parameters, of a
  37 public key algorithm, and an authority's signature, which proves the
  38 authenticity of the parameters.  @xref{The X.509 trust model}, for
  39 more information on @acronym{X.509} protocols.
  40
  41 @subsection Authentication Using @acronym{OpenPGP} Keys
  42 @cindex @acronym{OpenPGP} Keys
  43
  44 @acronym{OpenPGP} keys also contain public parameters of a public key
  45 algorithm, and signatures from several other parties. Depending on
  46 whether a signer is trusted the key is considered trusted or not.
  47 @acronym{GnuTLS}'s @acronym{OpenPGP} authentication implementation is
  48 based on the @xcite{TLSPGP} proposal.
  49
  50 @xref{The OpenPGP trust model}, for more information about the
  51 @acronym{OpenPGP} trust model.  For a more detailed introduction to
  52 @acronym{OpenPGP} and @acronym{GnuPG} see @xcite{GPGH}.
  53
  54 @subsection Using Certificate Authentication
  55
  56 In @acronym{GnuTLS} both the @acronym{OpenPGP} and @acronym{X.509}
  57 certificates are part of the certificate authentication and thus are
  58 handled using a common API.
  59
  60 When using certificates the server is required to have at least one
  61 certificate and private key pair. A client may or may not have such a
  62 pair. The certificate and key pair should be loaded, before any
  63 @acronym{TLS} session is initialized, in a certificate credentials
  64 structure. This should be done by using
  65 @ref{gnutls_certificate_set_x509_key_file} or
  66 @ref{gnutls_certificate_set_openpgp_key_file} depending on the
  67 certificate type.  In the @acronym{X.509} case, the functions will
  68 also accept and use a certificate list that leads to a trusted
  69 authority. The certificate list must be ordered in such way that every
  70 certificate certifies the one before it. The trusted authority's
  71 certificate need not to be included, since the peer should possess it
  72 already.
  73
  74 As an alternative, a callback may be used so the server or the client
  75 specify the certificate and the key at the handshake time.  That
  76 callback can be set using the functions:
  77
  78 @itemize
  79
  80 @item @ref{gnutls_certificate_server_set_retrieve_function}
  81
  82 @item @ref{gnutls_certificate_client_set_retrieve_function}
  83
  84 @end itemize
  85
  86 Clients and servers that will select certificates using callback
  87 functions should select a certificate according the peer's signature
  88 algorithm preferences. To get those preferences use
  89 @ref{gnutls_sign_algorithm_get_requested}.
  90
  91 Certificate verification is possible by loading the trusted
  92 authorities into the credentials structure by using
  93 @ref{gnutls_certificate_set_x509_trust_file} or
  94 @ref{gnutls_certificate_set_openpgp_keyring_file} for openpgp
  95 keys. Note however that the peer's certificate is not automatically
  96 verified, you should call @ref{gnutls_certificate_verify_peers2},
  97 after a successful handshake, to verify the signatures of the
  98 certificate.  An alternative way, which reports a more detailed
  99 verification output, is to use @ref{gnutls_certificate_get_peers} to
 100 obtain the raw certificate of the peer and verify it using the
 101 functions discussed in @ref{The X.509 trust model}.
 102
 103 In a handshake, the negotiated cipher suite depends on the
 104 certificate's parameters, so not all key exchange methods will be
 105 available with some certificates. @acronym{GnuTLS} will disable
 106 ciphersuites that are not compatible with the key, or the enabled
 107 authentication methods.  For example keys marked as sign-only, will
 108 not be able to access the plain RSA ciphersuites, but only the
 109 @code{DHE_RSA} ones. It is recommended not to use RSA keys for both
 110 signing and encryption. If possible use the same key for the
 111 @code{DHE_RSA} and @code{RSA_EXPORT} ciphersuites, which use signing,
 112 and a different key for the plain RSA ciphersuites, which use
 113 encryption.  All the key exchange methods shown below are available in
 114 certificate authentication.
 115
 116 Note that the DHE key exchange methods are generally
 117 slower@footnote{It really depends on the group used.  Primes with
 118 lesser bits are always faster, but also easier to break.  Values less
 119 than 768 should not be used today} than plain RSA and require Diffie
 120 Hellman parameters to be generated and associated with a credentials
 121 structure, by the server.  The @code{RSA-EXPORT} method also requires
 122 512 bit RSA parameters, that should also be generated and associated
 123 with the credentials structure.  See the functions:
 124
 125 @itemize
 126
 127 @item @ref{gnutls_dh_params_generate2}
 128
 129 @item @ref{gnutls_certificate_set_dh_params}
 130
 131 @item @ref{gnutls_rsa_params_generate2}
 132
 133 @item @ref{gnutls_certificate_set_rsa_export_params}
 134
 135 @end itemize
 136
 137 Sometimes in order to avoid bottlenecks in programs it is useful to
 138 store and read parameters from formats that can be generated by
 139 external programs such as @code{certtool}. This is possible with
 140 @acronym{GnuTLS} by using the following functions:
 141
 142 @itemize
 143
 144 @item @ref{gnutls_dh_params_import_pkcs3}
 145
 146 @item @ref{gnutls_rsa_params_import_pkcs1}
 147
 148 @item @ref{gnutls_dh_params_export_pkcs3}
 149
 150 @item @ref{gnutls_rsa_params_export_pkcs1}
 151
 152 @end itemize
 153
 154 Key exchange algorithms for @acronym{OpenPGP} and @acronym{X.509}
 155 certificates:
 156
 157 @table @code
 158
 159 @item RSA:
 160 The RSA algorithm is used to encrypt a key and send it to the peer.
 161 The certificate must allow the key to be used for encryption.
 162
 163 @item RSA_EXPORT:
 164 The RSA algorithm is used to encrypt a key and send it to the peer.
 165 In the EXPORT algorithm, the server signs temporary RSA parameters of
 166 512 bits --- which are considered weak --- and sends them to the
 167 client.
 168
 169 @item DHE_RSA:
 170 The RSA algorithm is used to sign Ephemeral Diffie-Hellman parameters
 171 which are sent to the peer. The key in the certificate must allow the
 172 key to be used for signing. Note that key exchange algorithms which
 173 use Ephemeral Diffie-Hellman parameters, offer perfect forward
 174 secrecy. That means that even if the private key used for signing is
 175 compromised, it cannot be used to reveal past session data.
 176
 177 @item DHE_DSS:
 178 The DSS algorithm is used to sign Ephemeral Diffie-Hellman parameters
 179 which are sent to the peer. The certificate must contain DSA
 180 parameters to use this key exchange algorithm. DSS stands for Digital
 181 Signature Standard.
 182
 183 @end table
 184
 185 @node Anonymous authentication
 186 @section Anonymous Authentication
 187 @cindex Anonymous authentication
 188
 189 The anonymous key exchange performs encryption but there is no
 190 indication of the identity of the peer.  This kind of authentication
 191 is vulnerable to a man in the middle attack, but this protocol can be
 192 used even if there is no prior communication and trusted parties with
 193 the peer, or when full anonymity is required.  Unless really required,
 194 do not use anonymous authentication.  Available key exchange methods
 195 are shown below.
 196
 197 Note that the key exchange methods for anonymous authentication
 198 require Diffie-Hellman parameters to be generated by the server and
 199 associated with an anonymous credentials structure.
 200
 201 Supported anonymous key exchange algorithms:
 202
 203 @table @code
 204
 205 @item ANON_DH:
 206 This algorithm exchanges Diffie-Hellman parameters.
 207
 208 @end table
 209
 210 @node Authentication using SRP
 211 @section Authentication using @acronym{SRP}
 212 @cindex @acronym{SRP} authentication
 213
 214 Authentication via the Secure Remote Password protocol,
 215 @acronym{SRP}@footnote{@acronym{SRP} is described in @xcite{RFC2945}},
 216 is supported.  The @acronym{SRP} key exchange is an extension to the
 217 @acronym{TLS} protocol, and it is a password based authentication
 218 (unlike @acronym{X.509} or @acronym{OpenPGP} that use certificates).
 219 The two peers can be identified using a single password, or there can
 220 be combinations where the client is authenticated using @acronym{SRP}
 221 and the server using a certificate.
 222
 223 The advantage of @acronym{SRP} authentication, over other proposed
 224 secure password authentication schemes, is that @acronym{SRP} does not
 225 require the server to hold the user's password.  This kind of
 226 protection is similar to the one used traditionally in the @emph{UNIX}
 227 @file{/etc/passwd} file, where the contents of this file did not cause
 228 harm to the system security if they were revealed.  The @acronym{SRP}
 229 needs instead of the plain password something called a verifier, which
 230 is calculated using the user's password, and if stolen cannot be used
 231 to impersonate the user. Check @xcite{TOMSRP} for a detailed
 232 description of the @acronym{SRP} protocol and the Stanford
 233 @acronym{SRP} libraries, which includes a PAM module that synchronizes
 234 the system's users passwords with the @acronym{SRP} password
 235 files. That way @acronym{SRP} authentication could be used for all the
 236 system's users.
 237
 238 The implementation in @acronym{GnuTLS} is based on paper
 239 @xcite{TLSSRP}.  The supported @acronym{SRP} key exchange methods are:
 240
 241 @table @code
 242
 243 @item SRP:
 244 Authentication using the @acronym{SRP} protocol.
 245
 246 @item SRP_DSS:
 247 Client authentication using the @acronym{SRP} protocol. Server is
 248 authenticated using a certificate with DSA parameters.
 249
 250 @item SRP_RSA:
 251 Client authentication using the @acronym{SRP} protocol. Server is
 252 authenticated using a certificate with RSA parameters.
 253
 254 @end table
 255
 256 If clients supporting @acronym{SRP} know the username and password
 257 before the connection, should initialize the client credentials and
 258 call the function @ref{gnutls_srp_set_client_credentials}.
 259 Alternatively they could specify a callback function by using the
 260 function @ref{gnutls_srp_set_client_credentials_function}.  This has
 261 the advantage that allows probing the server for @acronym{SRP}
 262 support.  In that case the callback function will be called twice per
 263 handshake.  The first time is before the ciphersuite is negotiated,
 264 and if the callback returns a negative error code, the callback will
 265 be called again if @acronym{SRP} has been negotiated.  This uses a
 266 special @acronym{TLS}-@acronym{SRP} handshake idiom in order to avoid,
 267 in interactive applications, to ask the user for @acronym{SRP}
 268 password and username if the server does not negotiate an
 269 @acronym{SRP} ciphersuite.
 270
 271 In server side the default behaviour of @acronym{GnuTLS} is to read
 272 the usernames and @acronym{SRP} verifiers from password files. These
 273 password files are the ones used by the @emph{Stanford srp libraries}
 274 and can be specified using the
 275 @ref{gnutls_srp_set_server_credentials_file}.  If a different
 276 password file format is to be used, then the function
 277 @ref{gnutls_srp_set_server_credentials_function}, should be called,
 278 in order to set an appropriate callback.
 279
 280 Some helper functions such as
 281
 282 @itemize
 283
 284 @item @ref{gnutls_srp_verifier}
 285
 286 @item @ref{gnutls_srp_base64_encode}
 287
 288 @item @ref{gnutls_srp_base64_decode}
 289
 290 @end itemize
 291
 292 are included in @acronym{GnuTLS}, and can be used to generate and
 293 maintain @acronym{SRP} verifiers and password files.  A program to
 294 manipulate the required parameters for @acronym{SRP} authentication is
 295 also included.  @xref{srptool}, for more information.
 296
 297
 298 @node Authentication using PSK
 299 @section Authentication using @acronym{PSK}
 300 @cindex @acronym{PSK} authentication
 301
 302 Authentication using Pre-shared keys is a method to authenticate using
 303 usernames and binary keys. This protocol avoids making use of public
 304 key infrastructure and expensive calculations, thus it is suitable for
 305 constraint clients.
 306
 307 The implementation in @acronym{GnuTLS} is based on paper
 308 @xcite{TLSPSK}.  The supported @acronym{PSK} key exchange methods are:
 309
 310 @table @code
 311
 312 @item PSK:
 313 Authentication using the @acronym{PSK} protocol.
 314
 315 @item DHE-PSK:
 316 Authentication using the @acronym{PSK} protocol and Diffie-Hellman key
 317 exchange.  This method offers perfect forward secrecy.
 318
 319 @end table
 320
 321 Clients supporting @acronym{PSK} should supply the username and key
 322 before the connection to the client credentials by calling the
 323 function @ref{gnutls_psk_set_client_credentials}.  Alternatively they
 324 could specify a callback function by using the function
 325 @ref{gnutls_psk_set_client_credentials_function}.  This has the
 326 advantage that the callback will be called only if @acronym{PSK} has
 327 been negotiated.
 328
 329 In server side the default behaviour of @acronym{GnuTLS} is to read
 330 the usernames and @acronym{PSK} keys from a password file. The
 331 password file should contain usernames and keys in hexadecimal
 332 format. The name of the password file can be stored to the credentials
 333 structure by calling @ref{gnutls_psk_set_server_credentials_file}.  If
 334 a different password file format is to be used, then the function
 335 @ref{gnutls_psk_set_server_credentials_function}, should be used
 336 instead.
 337
 338 The server can help the client chose a suitable username and password,
 339 by sending a hint.  In the server, specify the hint by calling
 340 @ref{gnutls_psk_set_server_credentials_hint}.  The client can retrieve
 341 the hint, for example in the callback function, using
 342 @ref{gnutls_psk_client_get_hint}.
 343
 344 There is no mechanism to derive a PSK key from a password
 345 specified by the TLS PSK document@footnote{GnuTLS used to provide
 346 @code{gnutls_psk_netconf_derive_key} which follows the algorithm
 347 specified in @file{draft-ietf-netconf-tls-02.txt}. This method
 348 is deprecated and might be removed in later versions of GnuTLS.}.
 349 For password-based authentication check @ref{Authentication using SRP}.
 350
 351 Some helper functions such as:
 352
 353 @itemize
 354
 355 @item @ref{gnutls_hex_encode}
 356
 357 @item @ref{gnutls_hex_decode}
 358
 359 @end itemize
 360
 361 are included in @acronym{GnuTLS}, and may be used to generate and
 362 maintain @acronym{PSK} keys.
 363
 364
 365 @node Authentication and credentials
 366 @section Authentication and Credentials
 367
 368 In @acronym{GnuTLS} every key exchange method is associated with a
 369 credentials type. So in order to enable to enable a specific method,
 370 the corresponding credentials type should be initialized and set using
 371 @ref{gnutls_credentials_set}.  A mapping is shown below.
 372
 373 Key exchange algorithms and the corresponding credential types:
 374
 375 @multitable @columnfractions .3 .3 .3
 376
 377 @headitem Key exchange @tab Client credentials @tab Server credentials
 378
 379 @item @code{KX_RSA}
 380 @item @code{KX_DHE_RSA}
 381 @item @code{KX_DHE_DSS}
 382 @item @code{KX_RSA_EXPORT}
 383 @tab @code{CRD_CERTIFICATE}
 384 @tab @code{CRD_CERTIFICATE}
 385
 386 @item @code{KX_SRP_RSA}
 387 @tab @code{CRD_SRP}
 388 @tab @code{CRD_SRP}
 389 @item @code{KX_SRP_DSS}
 390 @tab
 391 @tab @code{CRD_CERTIFICATE}
 392
 393 @item @code{KX_SRP}
 394 @tab @code{CRD_SRP}
 395 @tab @code{CRD_SRP}
 396
 397 @item @code{KX_ANON_DH}
 398 @tab @code{CRD_ANON}
 399 @tab @code{CRD_ANON}
 400
 401 @item @code{KX_PSK}
 402 @tab @code{CRD_PSK}
 403 @tab @code{CRD_PSK}
 404
 405 @end multitable
 406
 407 @node Parameters stored in credentials
 408 @section Parameters Stored in Credentials
 409
 410 Several parameters such as the ones used for Diffie-Hellman
 411 authentication are stored within the credentials structures, so all
 412 sessions can access them. Those parameters are stored in structures
 413 such as @code{gnutls_dh_params_t} and @code{gnutls_rsa_params_t}, and
 414 functions like @ref{gnutls_certificate_set_dh_params} and
 415 @ref{gnutls_certificate_set_rsa_export_params} can be used to
 416 associate those parameters with the given credentials structure.
 417
 418 Since those parameters need to be renewed from time to time and a
 419 global structure such as the credentials, may not be easy to modify
 420 since it is accessible by all sessions, an alternative interface is
 421 available using a callback function.  This can be set using the
 422 @ref{gnutls_certificate_set_params_function}.  An example is shown
 423 below.
 424
 425 @example
 426 #include <gnutls.h>
 427
 428 gnutls_rsa_params_t rsa_params;
 429 gnutls_dh_params_t dh_params;
 430
 431 /* This function will be called once a session requests DH
 432  * or RSA parameters. The parameters returned (if any) will
 433  * be used for the first handshake only.
 434  */
 435 static int get_params( gnutls_session_t session,
 436         gnutls_params_type_t type,
 437         gnutls_params_st *st)
 438 @{
 439    if (type == GNUTLS_PARAMS_RSA_EXPORT)
 440       st->params.rsa_export = rsa_params;
 441    else if (type == GNUTLS_PARAMS_DH)
 442       st->params.dh = dh_params;
 443    else return -1;
 444
 445    st->type = type;
 446    /* do not deinitialize those parameters.
 447     */
 448    st->deinit = 0;
 449
 450    return 0;
 451 @}
 452
 453 int main()
 454 @{
 455    gnutls_certificate_credentials_t cert_cred;
 456
 457    initialize_params();
 458
 459    /* ...
 460     */
 461
 462    gnutls_certificate_set_params_function( cert_cred, get_params);
 463 @}
 464 @end example