User's Manual

23
The websms_decode() function carries out the reverse operation of websms_encode() by decoding the character string
received by the user in a data field.
int websms_authenticate(struct webotp_context* context, webotp_time_t now, const
unsigned char* packet_ptr, char* blob_ptr, unsigned blob_size);
The websms_authenticate() function is used for checking the answer received from the user by means of the
information contained in the Blob. In this function the Blob must be saved also in case of INVALID_PACKET error.
This is necessary for limiting the number of failed attempts. This limitation is used for preventing brute force attacks
which might take place if an authentication code of few bits is used. In any case it is advisable to always use 24 bits for
the authentication code at least.
7.3 Utility
The utility functions supply some auxiliary services that can come in useful when using the authentication functions.
When during the authentication phases the current time or the generation of random data are requested, it is possible to
use such functions or other sources, if available.
All such functions are thread-safe.
webotp_time
_t webotp_time(void);
The webotp_time() function supplies the number of seconds elapsed from midnight (00:00:00) of 1
st
January 1970 in
Coordinated Universal Time (UTC)
5
. The SDK uses all information of the system data for obtaining such a value. It is
therefore essential that the system time and time zone information are correct.
In case a more precise source for date and time is available, it is possible to use it instead of the webotp_time() function.
int webotp_random(unsigned char* random_ptr, unsigned random_size);
The webotp_random() function is a source of random numbers to be used each time random information on the
authentication process is requested. The SDK uses the random number generator within Windows.
In case more advanced system are available for the generation of random numbers it is possible to use them instead of
the webotp_random() function.
7.4 Users
The users’ management functions enable modifying the authentication information of a user partially. Typically this is
not necessary when the SDK is operated normally.
All such functions are thread-safe.
int
webotp_user_reset
(struct webotp_context* context, unsigned property, char*
blob_ptr, unsigned blob_size);
The webotp_user_reset() function can be used for setting some information in the Blob. In particular it is possible to
reinitialize the management related to the event counter and to the WebOTP protocol time; it is also possible to cancel
the temporary information related to the WebCHR and WebSMS protocols.
It is important to underline the such operations are to be carried out only under extraordinary circumstances and only
after contacting the user directly. The possible causes related to similar problems are mainly due to faulty devices and
therefore may not be solved at the server level.
7.5 Configuration
The authentication process can be customized by varying some parameters controlling the width of the input windows
of the event and time counter. Typically this is not necessary as the default values have been devised for ensuring
maximum usability on the user's part without invalidating the authentication security. To this end the following function
is used:
int webotp_configure(struct webotp_context* context, unsigned
configure_property, unsigned value);
At each call a parameter can be set by specifying the type of property that is to be set by using one of the following
codes:
5
It is the same format used in the C language by the time() function.