WebOTP Developer’s Manual v1.
© Copyright 2007 Eutronsec Spa - Via Gandhi, 12 - 24048 Treviolo (BG) – Italy. All rights reserved. The names of the other products mentioned are trademarks of their respective owners.
Table of contents 1 PREFACE ................................................................................................................................................................. 5 1.1 ABOUT THIS MANUAL .......................................................................................................................................... 5 1.2 HOW TO USE THIS MANUAL..................................................................................................................................
7.4 USERS ................................................................................................................................................................ 23 7.5 CONFIGURATION................................................................................................................................................ 23 7.5.1 Input window for the counter field ............................................................................................................ 24 7.5.
1 Preface This chapter describes the contents and the layout of this manual and of WebOTP distribution. 1.1 About this manual This manual describes the WebOTP product and how to operate and integrate it into an authentication service. 1.2 How to use this manual This manual is meant for the developer who needs to integrate the WebOTP product into an already existing authentication service or that is underway.
1.5.1 Hardware components The SDK demonstrative release is supplied with a WebOTP device that is working, demonstrative and already initialized. The demo device is always initialized with the cryptographic server-key and blob-key set to 202122232425262728292A2B2C2D2E2F303132333435363738393A3B3C3D3E3F and with the serial set to 1. The relevant initialization information is contained in the WebOTPDemo.csv file. 1.5.
1.6 Feedback The quickest way for getting in touch with Eutronsec as regards WebOTP is sending an email message to the helpdesk: helpdesk@eutronsec.it It is also possible to call the Customer Service’s number +39-35697055 or to send a fax to number +39-35697092. For any commercial contact it is possible to send an email message to the following address: info@eutronsec.
2 Introduction 2.1 What is WebOTP? WebOTP is a secure authentication device via PC and related USB connection. WebOTP is especially suited for the authentication of web service users by means of an Internet browser, but it can also be used within all those environments requiring any form of authentication. The product is made up of an USB device for authentication to assign to users and by an SDK software which provides the necessary services for authentication. 2.
2.4.3 SMS The SMS-based protocol, in short WebSMS, has been developed for all those cases in which it is not possible to use the WebOTP hardware device, because of damage, loss or simply because a USB connection is not available for connecting it. Via this protocol the server sends the user an SMS containing a code consisting of letters and/or numbers which the user will be able to use for authenticating. 2.
3 Getting Started This chapter illustrates the use of the WebOTP device 3.1 SDK installation The WebOTP product is provided with an SDK including the documentation, the libraries for interfacing with the server applications and a test application. For installing the SDK WebOTP on the Windows platforms run the WebOTPSDK.exe installation program. On completion of the installation the SDK content can be accessed by the application menus via the entry Eutronsec/WebOTP SDK. 3.
During the communication process between the device and the system the keyboard led will blink and the round icon will become yellow. At the end of the authentication process the program displays the device serial number.
4 Requirements This chapter describes the minimum requisites in terms of software and hardware that are compulsory for WebOTP operations. The WebOTP product features different requirements on the client side and on the server side, according to the authentication protocol in use. 4.1 Client The hardware device can be used on every system that is provided with a USB 1.1 or USB 2.0 connection.
5 Authentication This chapter describes the authentication type that is carried out from WebOTP. The WebOTP and WebCHR protocol authentication is based on the use of a symmetric cryptography algorithm and of a secret shared among the hardware devices and the authentication server. The WebSMS protocol authentication is based on the exchange of information via user’s telephone instead. 5.
6 Device This chapter describes the WebOTP hardware devices. WebOTP is a hardware device with a USB 2.0 connection which uses the HUMAN INTERFACE DEVICE (HID) standard for communicating with the PC. The device contains a microprocessor, which is able to carry out authentication operations by using the AES256 cryptography standard which is the state-of-the-art in terms of security. 6.1 Event-based and time-based The devices are provided in two different versions.
Possible configurations are: Configuration Description WebOTP Invisible The most widely used and best usable configuration. The authentication occurs in a totally transparent way for the user. WebOTP Alpha The configuration that best enables integrating with already existing password-based systems. The authentication occurs by transmitting an alphabetical string which can be easily recognized by already existing applications.
The authentication data are embedded into a bit sequence which provides a special header and a special footer: Size Description Header 4 bit Sequence for recognizing the transmission start and for identifying the device type in connection and the protocol in use. For the WebOTP protocol the sequence is always 0001. Data 20*8 bit Data to transmit for authentication. The single bytes are sent starting from the least meaningful bit.
Therefore when interpreting the keys no difference shall be made between receiving capital letters and small letters, and the ‘Q’ and ‘A’ letters shall be treated likewise. The authentication data are embedded into a bit sequence which provides a special header: Size Description Header 4 bit Sequence for recognizing the transmission start and for identifying the device type in connection and the protocol in use. For the WebOTP protocol the sequence is always 0001.
The user must proceed like this: 1. The user inserts the device 2. The operating system starts the installation wizard. The user presses “Next”. 3. The user presses “Next”. 4. The user presses “Next”. 5. The user presses “Next”. 6. The user inserts the Windows 98 original CD-ROM, keeps selecting the installation default directory and presses “OK”.
7. The user presses “Next”. 8. The user presses “Finish” and the configuration process is completed. When installation is completed the authentication process starts automatically. This process is requested only on first insertion on any USB port. 6.5.3 Linux Linux operating system recognizes the device immediately. There is no difference between the first insertion and the following ones. 6.5.
5. The user just waits for the device to generate a sequence of recognition keys. This sequence is generated only once after five seconds form insertion. It is therefore essential for the use to open this panel within 5 seconds. 6. The system detects the recognition sequence but does not identify the device, thus it signals the user such a condition by requesting a manual selection of the keyboard type. 7. The user selects any type of keyboard and the configuration process is completed. 8.
7 SDK This chapter describes the WebOTP SDK. The WebOTP product is distributed with an SDK which puts at the developer’s disposal the necessary services for using the WebOTP features. The WebOTP features can be subdivided into the following categories: Initialization – Initialization features. WebOTP – Features for WebOTP authentication. WebCHR – Features for WebCHR authentication. WebSMS – Features for WebSMS authentication. Utilities - Generic utility features. Users – Customization features.
The Blob must be updated after each successful use by the authentication functions. When a function ends in error, the Blob has not been modified and therefore it is not necessary to update it4. 7.2.1 WebOTP The WebOTP authentication takes place through a single communication from the user to the server. The server receives a 20 byte-long data string which is checked via function webotp_authenticate().
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.
RANGE_COUNTER Maximum leap ahead of the event counter from the latest authentication. The value is expressed in units. The default value is 1500. RANGE_TIME_PAST Maximum fixed component of time error for devices with a past time value (device clock is slower than normal). The value is expressed in seconds. The default value is 30. RANGE_TIME_FUTURE Maximum fixed component of time error for devices with a future time value (device clock is faster than normal). The value is expressed in seconds.
The devices are calibrated in the production phase with an error lower than 2 ppm (parts per million). The storage temperature can increase the error though, as regards the period of exposure to such a temperature. The progress of the error according to the temperature is expressed in the following table.
The user is NOT authenticated. INVALID_BLOB The datum supplied as Blob is invalid. The data in the Blob are both encrypted and validated. Every variation not carried out by the SDK is identified and makes the Blob unserviceable. In that case it is necessary to reset a valid Blob in the database. It is also possible that an incorrect Blob-key is being used. The user is NOT authenticated. INVALID_PACKET The received packet is invalid.
The user is NOT authenticated. INVALID_COUNTER_LATE The authentication has failed because too many unsuccessful attempts at authentication have been made. It is probably a user error or a brute force attack attempt. In this case the user needs to be required to retry and carry out the authentication. The user is NOT authenticated. 7.7 LIbraries 7.7.
8 Integration This chapter describes how to integrate the WebOTP device into an authentication service. 8.1 Integration into a web service WebOTP has been designed for making the use of a web service as user-friendly as possible. Both in case a new authentication service is to be created and in case such a service is to be integrated into an existing one.
8.1.3 Client At the client level it is necessary to modify the login page in order to register the information sent to the device. It is also possible to modify other pages of the website, among which the home page, for recognizing the insertion of the device and authenticate the user without any intermediate phase. The recommended system is using a script for recording the key pressure and for sending them to the server.
e.cancelBubble = true; return false; } return true; } // trap the keydown events document.
9 Technical specifications 9.1 WebOTP event-based Size: 34x16x8 mm Interconnection: USB 2.0 FullSpeed Protocol: HID 1.11 Connector: USB Male Type A Power supply: fed by USB port Temperature: -20 - +80°C Humidity: 20-95% relative humidity 9.2 WebOTP time-based Size: 55x20x9 mm Interconnection: USB 2.0 FullSpeed Protocol: HID 1.
10 Appendixes 10.1 Glossary One Time Password Generic authentication protocol requiring the use of dynamic non-reusable passwords. Challenge Response Generic authentication protocol requiring the use of a bi-directional information exchange between client and server.
