Next: , Previous: , Up: Associating the credentials   [Contents][Index]

6.4.4 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 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 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 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 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)

Next: , Previous: , Up: Associating the credentials   [Contents][Index]