6.4.3 PSK

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

int gnutls_psk_allocate_server_credentials (gnutls_psk_server_credentials_t * sc)

int gnutls_psk_allocate_client_credentials (gnutls_psk_client_credentials_t * sc)

void gnutls_psk_free_server_credentials (gnutls_psk_server_credentials_t sc)

void 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 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 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 structure.

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() . username should be ASCII strings or UTF-8 strings prepared using the "SASLprep" profile of "stringprep".

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 gnutls_psk_set_server_credentials_file. If a different password file format is to be used, then a callback should be set instead by 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 gnutls_psk_set_server_credentials_hint. The client can retrieve the hint, for example in the callback function, using 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 structure.

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

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

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

void gnutls_psk_set_server_credentials_function (gnutls_psk_server_credentials_t cred, gnutls_psk_server_credentials_function * func)

int gnutls_psk_set_server_credentials_hint (gnutls_psk_server_credentials_t res, const char * hint)

const char * gnutls_psk_client_get_hint (gnutls_session_t session)

This document was generated on February 9, 2014 using texi2html 5.0.