ext: Anonymous credentials,  Prev: SRP credentials,  Up: Associating the credentials

6.4.4 PSK
---------

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

‘INT *note gnutls_psk_allocate_server_credentials:: (gnutls_psk_server_credentials_t * SC)’
‘INT *note gnutls_psk_allocate_client_credentials:: (gnutls_psk_client_credentials_t * SC)’
‘VOID *note gnutls_psk_free_server_credentials:: (gnutls_psk_server_credentials_t SC)’
‘VOID *note gnutls_psk_free_client_credentials:: (gnutls_psk_client_credentials_t SC)’

Clients supporting PSK should supply the username and key before a TLS
session is established.  Alternatively *note
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 PSK has been negotiated.

‘INT *note gnutls_psk_set_client_credentials:: (gnutls_psk_client_credentials_t RES, const char * USERNAME, const gnutls_datum_t * KEY, gnutls_psk_key_flags FLAGS)’

 -- Function: void gnutls_psk_set_client_credentials_function
          (gnutls_psk_client_credentials_t CRED,
          gnutls_psk_client_credentials_function * FUNC)
     CRED: is a ‘gnutls_psk_server_credentials_t’ type.

     FUNC: is the callback function

     This function can be used to set a callback to retrieve the
     username and password for client PSK authentication.  The
     callback's function form is: int (*callback)(gnutls_session_t,
     char** username, gnutls_datum_t* key);

     The ‘username’ and ‘key’ ->data must be allocated using
     ‘gnutls_malloc()’ .  The ‘username’ should be an ASCII string or
     UTF-8 string.  In case of a UTF-8 string it is recommended to be
     following the PRECIS framework for usernames (rfc8265).

     The callback function will be called once per handshake.

     The callback function should return 0 on success.  -1 indicates an
     error.

In server side the default behavior of GnuTLS is to read the usernames
and 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 *note
gnutls_psk_set_server_credentials_file::.  If a different password file
format is to be used, then a callback should be set instead by *note
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 *note gnutls_psk_set_server_credentials_hint::.  The
client can retrieve the hint, for example in the callback function,
using *note gnutls_psk_client_get_hint::.

 -- Function: int gnutls_psk_set_server_credentials_file
          (gnutls_psk_server_credentials_t RES, const char *
          PASSWORD_FILE)
     RES: is a ‘gnutls_psk_server_credentials_t’ type.

     PASSWORD_FILE: is the PSK password file (passwd.psk)

     This function sets the password file, in a
     ‘gnutls_psk_server_credentials_t’ type.  This password file holds
     usernames and keys and will be used for PSK authentication.

     Each entry in the file consists of a username, followed by a colon
     (':') and a hex-encoded key.  If the username contains a colon or
     any other special character, it can be hex-encoded preceded by a
     '#'.

     *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned,
     otherwise an error code is returned.

‘VOID *note gnutls_psk_set_server_credentials_function:: (gnutls_psk_server_credentials_t CRED, gnutls_psk_server_credentials_function * FUNC)’
‘INT *note gnutls_psk_set_server_credentials_hint:: (gnutls_psk_server_credentials_t RES, const char * HINT)’
‘CONST CHAR * *note gnutls_psk_client_get_hint:: (gnutls_session_t SESSION)’