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

6.4.3 SRP

The initialization functions in SRP credentials differ between client and server. Clients supporting SRP should set the username and password prior to connection, to the credentials structure. Alternatively gnutls_srp_set_client_credentials_function may be used instead, to specify a callback function that should return the SRP username and password. The callback is called once during the TLS handshake.

int gnutls_srp_allocate_server_credentials (gnutls_srp_server_credentials_t * sc)
int gnutls_srp_allocate_client_credentials (gnutls_srp_client_credentials_t * sc)
void gnutls_srp_free_server_credentials (gnutls_srp_server_credentials_t sc)
void gnutls_srp_free_client_credentials (gnutls_srp_client_credentials_t sc)
int gnutls_srp_set_client_credentials (gnutls_srp_client_credentials_t res, const char * username, const char * password)
Function: void gnutls_srp_set_client_credentials_function (gnutls_srp_client_credentials_t cred, gnutls_srp_client_credentials_function * func)

cred: is a gnutls_srp_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 SRP authentication. The callback’s function form is:

int (*callback)(gnutls_session_t, char** username, char**password);

The username and password 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 password can be in ASCII format, or normalized using gnutls_utf8_password_normalize() .

The callback function will be called once per handshake before the initial hello message is sent.

The callback should not return a negative error code the second time called, since the handshake procedure will be aborted.

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 SRP verifiers from password files. These password file format is compatible the with the Stanford srp libraries format. If a different password file format is to be used, then gnutls_srp_set_server_credentials_function should be called, to set an appropriate callback.

Function: int gnutls_srp_set_server_credentials_file (gnutls_srp_server_credentials_t res, const char * password_file, const char * password_conf_file)

res: is a gnutls_srp_server_credentials_t type.

password_file: is the SRP password file (tpasswd)

password_conf_file: is the SRP password conf file (tpasswd.conf)

This function sets the password files, in a gnutls_srp_server_credentials_t type. Those password files hold usernames and verifiers and will be used for SRP authentication.

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

Function: void gnutls_srp_set_server_credentials_function (gnutls_srp_server_credentials_t cred, gnutls_srp_server_credentials_function * func)

cred: is a gnutls_srp_server_credentials_t type.

func: is the callback function

This function can be used to set a callback to retrieve the user’s SRP credentials. The callback’s function form is:

int (*callback)(gnutls_session_t, const char* username, gnutls_datum_t *salt, gnutls_datum_t *verifier, gnutls_datum_t *generator, gnutls_datum_t *prime);

username contains the actual username. The salt , verifier , generator and prime must be filled in using the gnutls_malloc() . For convenience prime and generator may also be one of the static parameters defined in gnutls.h.

Initially, the data field is NULL in every gnutls_datum_t structure that the callback has to fill in. When the callback is done GnuTLS deallocates all of those buffers which are non-NULL, regardless of the return value.

In order to prevent attackers from guessing valid usernames, if a user does not exist, g and n values should be filled in using a random user’s parameters. In that case the callback must return the special value (1). See gnutls_srp_set_server_fake_salt_seed too. If this is not required for your application, return a negative number from the callback to abort the handshake.

The callback function will only be called once per handshake. The callback function should return 0 on success, while -1 indicates an error.

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