lib/gnutls_psk.c

   1 /*
   2  * Copyright (C) 2005, 2007, 2008 Free Software Foundation
   3  *
   4  * Author: Nikos Mavrogiannopoulos
   5  *
   6  * This file is part of GNUTLS.
   7  *
   8  * The GNUTLS library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Lesser General Public License
  10  * as published by the Free Software Foundation; either version 2.1 of
  11  * the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful, but
  14  * WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Lesser General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public
  19  * License along with this library; if not, write to the Free Software
  20  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
  21  * USA
  22  *
  23  */
  24
  25 /* Functions for manipulating the PSK credentials. */
  26
  27 #include <gnutls_int.h>
  28 #include <gnutls_errors.h>
  29 #include <auth_psk.h>
  30 #include <gnutls_state.h>
  31
  32 #ifdef ENABLE_PSK
  33
  34 #include <auth_psk_passwd.h>
  35 #include <gnutls_num.h>
  36 #include <gnutls_helper.h>
  37 #include <gnutls_datum.h>
  38 #include "debug.h"
  39
  40 /**
  41   * gnutls_psk_free_client_credentials - Used to free an allocated gnutls_psk_client_credentials_t structure
  42   * @sc: is an #gnutls_psk_client_credentials_t structure.
  43   *
  44   * This structure is complex enough to manipulate directly thus this
  45   * helper function is provided in order to free (deallocate) it.
  46   **/
  47 void
  48 gnutls_psk_free_client_credentials (gnutls_psk_client_credentials_t sc)
  49 {
  50   _gnutls_free_datum (&sc->username);
  51   _gnutls_free_datum (&sc->key);
  52   gnutls_free (sc);
  53 }
  54
  55 /**
  56   * gnutls_psk_allocate_client_credentials - Used to allocate an gnutls_psk_server_credentials_t structure
  57   * @sc: is a pointer to an #gnutls_psk_server_credentials_t structure.
  58   *
  59   * This structure is complex enough to manipulate directly thus this
  60   * helper function is provided in order to allocate it.
  61   *
  62   * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
  63   **/
  64 int
  65 gnutls_psk_allocate_client_credentials (gnutls_psk_client_credentials_t * sc)
  66 {
  67   *sc = gnutls_calloc (1, sizeof (psk_client_credentials_st));
  68
  69   if (*sc == NULL)
  70     return GNUTLS_E_MEMORY_ERROR;
  71
  72   return 0;
  73 }
  74
  75 /**
  76   * gnutls_psk_set_client_credentials - Used to set the username/password, in a gnutls_psk_client_credentials_t structure
  77   * @res: is an #gnutls_psk_client_credentials_t structure.
  78   * @username: is the user's zero-terminated userid
  79   * @key: is the user's key
  80   * @format: indicate the format of the key, either
  81   * %GNUTLS_PSK_KEY_RAW or %GNUTLS_PSK_KEY_HEX.
  82   *
  83   * This function sets the username and password, in a
  84   * gnutls_psk_client_credentials_t structure.  Those will be used in
  85   * PSK authentication. @username should be an ASCII string or UTF-8
  86   * strings prepared using the "SASLprep" profile of "stringprep".
  87   * The key can be either in raw byte format or in Hex (not with the
  88   * '0x' prefix).
  89   *
  90   * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
  91   **/
  92 int
  93 gnutls_psk_set_client_credentials (gnutls_psk_client_credentials_t res,
  94                                    const char *username,
  95                                    const gnutls_datum_t * key,
  96                                    gnutls_psk_key_flags flags)
  97 {
  98   int ret;
  99
 100   if (username == NULL || key == NULL || key->data == NULL)
 101     {
 102       gnutls_assert ();
 103       return GNUTLS_E_INVALID_REQUEST;
 104     }
 105
 106   ret = _gnutls_set_datum (&res->username, username, strlen (username));
 107   if (ret < 0)
 108     return ret;
 109
 110   if (flags == GNUTLS_PSK_KEY_RAW)
 111     {
 112       if (_gnutls_set_datum (&res->key, key->data, key->size) < 0)
 113         {
 114           gnutls_assert ();
 115           ret = GNUTLS_E_MEMORY_ERROR;
 116           goto error;
 117         }
 118     }
 119   else
 120     {                           /* HEX key */
 121       size_t size;
 122       size = res->key.size = key->size / 2;
 123       res->key.data = gnutls_malloc (size);
 124       if (res->key.data == NULL)
 125         {
 126           gnutls_assert ();
 127           ret = GNUTLS_E_MEMORY_ERROR;
 128           goto error;
 129         }
 130
 131       ret = gnutls_hex_decode (key, (char *) res->key.data, &size);
 132       res->key.size = (unsigned int)size;
 133       if (ret < 0)
 134         {
 135           gnutls_assert ();
 136           goto error;
 137         }
 138
 139     }
 140
 141   return 0;
 142
 143 error:
 144   _gnutls_free_datum (&res->username);
 145
 146   return ret;
 147 }
 148
 149 /**
 150  * gnutls_psk_free_server_credentials - Used to free an allocated gnutls_psk_server_credentials_t structure
 151  * @sc: is an #gnutls_psk_server_credentials_t structure.
 152  *
 153  * This structure is complex enough to manipulate directly thus this
 154  * helper function is provided in order to free (deallocate) it.
 155  **/
 156 void
 157 gnutls_psk_free_server_credentials (gnutls_psk_server_credentials_t sc)
 158 {
 159   gnutls_free (sc->password_file);
 160   gnutls_free (sc);
 161 }
 162
 163 /**
 164  * gnutls_psk_allocate_server_credentials - Used to allocate an gnutls_psk_server_credentials_t structure
 165  * @sc: is a pointer to an #gnutls_psk_server_credentials_t structure.
 166  *
 167  * This structure is complex enough to manipulate directly thus this
 168  * helper function is provided in order to allocate it.
 169  *
 170  * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
 171  **/
 172 int
 173 gnutls_psk_allocate_server_credentials (gnutls_psk_server_credentials_t * sc)
 174 {
 175   *sc = gnutls_calloc (1, sizeof (psk_server_cred_st));
 176
 177   if (*sc == NULL)
 178     return GNUTLS_E_MEMORY_ERROR;
 179
 180   return 0;
 181 }
 182
 183
 184 /**
 185  * gnutls_psk_set_server_credentials_file - Used to set the password files, in a gnutls_psk_server_credentials_t structure
 186  * @res: is an #gnutls_psk_server_credentials_t structure.
 187  * @password_file: is the PSK password file (passwd.psk)
 188  *
 189  * This function sets the password file, in a
 190  * %gnutls_psk_server_credentials_t structure.  This password file
 191  * holds usernames and keys and will be used for PSK authentication.
 192  *
 193  * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
 194  **/
 195 int
 196 gnutls_psk_set_server_credentials_file (gnutls_psk_server_credentials_t
 197                                         res, const char *password_file)
 198 {
 199
 200   if (password_file == NULL)
 201     {
 202       gnutls_assert ();
 203       return GNUTLS_E_INVALID_REQUEST;
 204     }
 205
 206   /* Check if the files can be opened */
 207   if (_gnutls_file_exists (password_file) != 0)
 208     {
 209       gnutls_assert ();
 210       return GNUTLS_E_FILE_ERROR;
 211     }
 212
 213   res->password_file = gnutls_strdup (password_file);
 214   if (res->password_file == NULL)
 215     {
 216       gnutls_assert ();
 217       return GNUTLS_E_MEMORY_ERROR;
 218     }
 219
 220   return 0;
 221 }
 222
 223 /**
 224  * gnutls_psk_set_server_credentials_hint - Set a identity hint, in a %gnutls_psk_server_credentials_t structure
 225  * @res: is an #gnutls_psk_server_credentials_t structure.
 226  * @hint: is the PSK identity hint string
 227  *
 228  * This function sets the identity hint, in a
 229  * %gnutls_psk_server_credentials_t structure.  This hint is sent to
 230  * the client to help it chose a good PSK credential (i.e., username
 231  * and password).
 232  *
 233  * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
 234  *
 235  * Since: 2.4.0
 236  **/
 237 int
 238 gnutls_psk_set_server_credentials_hint (gnutls_psk_server_credentials_t res,
 239                                         const char *hint)
 240 {
 241   res->hint = gnutls_strdup (hint);
 242   if (res->hint == NULL)
 243     {
 244       gnutls_assert ();
 245       return GNUTLS_E_MEMORY_ERROR;
 246     }
 247
 248   return 0;
 249 }
 250
 251 /**
 252  * gnutls_psk_set_server_credentials_function - Used to set a callback to retrieve the user's PSK credentials
 253  * @cred: is a #gnutls_psk_server_credentials_t structure.
 254  * @func: is the callback function
 255  *
 256  * This function can be used to set a callback to retrieve the user's PSK credentials.
 257  * The callback's function form is:
 258  * int (*callback)(gnutls_session_t, const char* username,
 259  *  gnutls_datum_t* key);
 260  *
 261  * @username contains the actual username.
 262  * The @key must be filled in using the gnutls_malloc().
 263  *
 264  * In case the callback returned a negative number then gnutls will
 265  * assume that the username does not exist.
 266  *
 267  * The callback function will only be called once per handshake.  The
 268  * callback function should return 0 on success, while -1 indicates
 269  * an error.
 270  **/
 271 void
 272 gnutls_psk_set_server_credentials_function (gnutls_psk_server_credentials_t
 273                                             cred,
 274                                             gnutls_psk_server_credentials_function
 275                                             * func)
 276 {
 277   cred->pwd_callback = func;
 278 }
 279
 280 /**
 281  * gnutls_psk_set_client_credentials_function - Used to set a callback to retrieve the username and key
 282  * @cred: is a #gnutls_psk_server_credentials_t structure.
 283  * @func: is the callback function
 284  *
 285  * This function can be used to set a callback to retrieve the username and
 286  * password for client PSK authentication.
 287  * The callback's function form is:
 288  * int (*callback)(gnutls_session_t, char** username,
 289  *  gnutls_datum_t* key);
 290  *
 291  * The @username and @key->data must be allocated using gnutls_malloc().
 292  * @username should be ASCII strings or UTF-8 strings prepared using
 293  * the "SASLprep" profile of "stringprep".
 294  *
 295  * The callback function will be called once per handshake.
 296  *
 297  * The callback function should return 0 on success.
 298  * -1 indicates an error.
 299  **/
 300 void
 301 gnutls_psk_set_client_credentials_function (gnutls_psk_client_credentials_t
 302                                             cred,
 303                                             gnutls_psk_client_credentials_function
 304                                             * func)
 305 {
 306   cred->get_function = func;
 307 }
 308
 309
 310 /**
 311  * gnutls_psk_server_get_username - return the username of the peer
 312  * @session: is a gnutls session
 313  *
 314  * This should only be called in case of PSK authentication and in
 315  * case of a server.
 316  *
 317  * Returns: the username of the peer, or %NULL in case of an error.
 318  **/
 319 const char *
 320 gnutls_psk_server_get_username (gnutls_session_t session)
 321 {
 322   psk_auth_info_t info;
 323
 324   CHECK_AUTH (GNUTLS_CRD_PSK, NULL);
 325
 326   info = _gnutls_get_auth_info (session);
 327   if (info == NULL)
 328     return NULL;
 329
 330   if (info->username[0] != 0)
 331     return info->username;
 332
 333   return NULL;
 334 }
 335
 336 /**
 337  * gnutls_psk_client_get_hint - return the PSK identity hint of the peer
 338  * @session: is a gnutls session
 339  *
 340  * The PSK identity hint may give the client help in deciding which
 341  * username to use.  This should only be called in case of PSK
 342  * authentication and in case of a client.
 343  *
 344  * Returns: the identity hint of the peer, or %NULL in case of an error.
 345  *
 346  * Since: 2.4.0
 347  **/
 348 const char *
 349 gnutls_psk_client_get_hint (gnutls_session_t session)
 350 {
 351   psk_auth_info_t info;
 352
 353   CHECK_AUTH (GNUTLS_CRD_PSK, NULL);
 354
 355   info = _gnutls_get_auth_info (session);
 356   if (info == NULL)
 357     return NULL;
 358
 359   if (info->hint[0] != 0)
 360     return info->hint;
 361
 362   return NULL;
 363 }
 364
 365 /**
 366   * gnutls_hex_decode - decode hex encoded data
 367   * @hex_data: contain the encoded data
 368   * @result: the place where decoded data will be copied
 369   * @result_size: holds the size of the result
 370   *
 371   * This function will decode the given encoded data, using the hex encoding
 372   * used by PSK password files.
 373   *
 374   * Note that hex_data should be null terminated.
 375   *
 376   * Returns: %GNUTLS_E_SHORT_MEMORY_BUFFER if the buffer given is not
 377   *   long enough, or 0 on success.
 378   **/
 379 int
 380 gnutls_hex_decode (const gnutls_datum_t * hex_data, char *result,
 381                    size_t * result_size)
 382 {
 383   int ret;
 384
 385   ret =
 386     _gnutls_hex2bin (hex_data->data, hex_data->size, (opaque *) result,
 387                      result_size);
 388   if (ret < 0)
 389     return ret;
 390
 391   return 0;
 392 }
 393
 394 /**
 395   * gnutls_hex_encode - convert raw data to hex encoded
 396   * @data: contain the raw data
 397   * @result: the place where hex data will be copied
 398   * @result_size: holds the size of the result
 399   *
 400   * This function will convert the given data to printable data, using
 401   * the hex encoding, as used in the PSK password files.
 402   *
 403   * Returns: %GNUTLS_E_SHORT_MEMORY_BUFFER if the buffer given is not
 404   * long enough, or 0 on success.
 405   **/
 406 int
 407 gnutls_hex_encode (const gnutls_datum_t * data, char *result,
 408                    size_t * result_size)
 409 {
 410   if (*result_size < data->size + data->size + 1)
 411     {
 412       gnutls_assert ();
 413       return GNUTLS_E_SHORT_MEMORY_BUFFER;
 414     }
 415
 416   _gnutls_bin2hex (data->data, data->size, result, *result_size);
 417
 418   return 0;
 419 }
 420
 421 /**
 422   * gnutls_psk_set_server_dh_params - set the DH parameters for a server to use
 423   * @res: is a gnutls_psk_server_credentials_t structure
 424   * @dh_params: is a structure that holds diffie hellman parameters.
 425   *
 426   * This function will set the diffie hellman parameters for an
 427   * anonymous server to use. These parameters will be used in Diffie
 428   * Hellman with PSK cipher suites.
 429   **/
 430 void
 431 gnutls_psk_set_server_dh_params (gnutls_psk_server_credentials_t res,
 432                                  gnutls_dh_params_t dh_params)
 433 {
 434   res->dh_params = dh_params;
 435 }
 436
 437 /**
 438   * gnutls_psk_set_server_params_function - set the DH parameters callback
 439   * @res: is a gnutls_certificate_credentials_t structure
 440   * @func: is the function to be called
 441   *
 442   * This function will set a callback in order for the server to get
 443   * the diffie hellman parameters for PSK authentication. The callback
 444   * should return zero on success.
 445   **/
 446 void
 447 gnutls_psk_set_server_params_function (gnutls_psk_server_credentials_t res,
 448                                        gnutls_params_function * func)
 449 {
 450   res->params_func = func;
 451 }
 452
 453 #endif /* ENABLE_PSK */