SMSAuthenticator ================ Welcome to the first release of the SMSAuthenticator two-factor authentication SOAP module. This software was developed at the Norwegian Centre for Telemedicine, as a part of the project 'PasientLink'. SMSAuthenticator implements a two-factor authentication process. In the first phase, the authenticator receives application generated requests for authentication of a specified user. When the request is received, a single-use password is generated and sent using GSM Short Messaging Service to a GSM cell phone registered on the specified user. The single-use password has a configurable timeout (default 5 minutes). In the second phase of the authentication process, a request is made specifying the user id and a hash of the single-use password. If both the single-use and user specified password are valid, the user will be authenticated i.e. a boolean true value will be returned in the SOAP call. The single-use passwords are generated using a secure random generator (SHA1PRNG-algorithm), and are held in-memory only, for a limited period of time. As soon as an authentication request has been completed, the single-use password is disposed of. User passwords may be generated when creating users, and are in accordance to FIPS PUB 181 (code is based on GPW). The SMSAuthenticator has an easy to use web based administration interface, which can be configured to use the SMSAthenticator itself to ensure secure administration access. The distribution archive is organized as follows: classes - compiled classes conf - apache tomcat config files (servlet8082.xml contains SSL example config) defaultroot - Jbuilder6 webapp-context. Also contains velocity templates and misc files used to rebuild the SMSAuthenticator db - contains database scripts for PostgreSQL doc - API docs for the authenticator lib - contains required libraries (only mainly jar files, not full distributions) src - contains source code and Apache SOAP deployment descriptor test - contains unit test source code (JUnit based) The SMSAuthenticator uses a number of libraries, all open source. INSTALLING ========== 0. Install a JRE (Java Runtime Environment) for your platform, versjon 1.3 or newer. You should also make sure that the Java binaries (java/keytool etc) are in the path. If you want to rebuild the SMSAuthenticator from source, you'll want to install JDK (Java Development Kit) instead of the JRE, version 1.3 or newer. 1. Install a servlet container. SMSAuthenticator has been tested with Apache Jakarta Tomcat (version 4.0.x and 3.2.3, see http://jakarta.apache.org/tomcat). 2. Deploy the SMSAuthenticator war file (SMSAuthenticator.war) into the servlet container. For Tomcat this means copying the SMSAuthenticator war file into the webapps folder (see the 'REBUILDING' section below on how to rebuild the war file from source). You probably also want to run the SOAP service over SSL to reduce the risk for man in the middle-attacks. First however, we advise you to test the service without SSL. When you want to install SSL, please follow the directions for your servlet container on how to install SSL support. For Tomcat, this information can be found here: http://jakarta.apache.org/tomcat/tomcat-4.0-doc/ssl-howto.html. Sample SSL setup is provided in conf/server8082.xml and authenticator.keystore 3. Edit the configuration file 'authenticator.properties'. This file is contained in SMSAuthenticator.war, and is usually unpacked automatically when starting the servlet container with a new version of the war file. After the war file is unpacked, you will find the file in ./WEB-INF/classes/authenticator.properties Set database and adminstration properties (username/password/phone number). The GSM phone number set here is used when authenticating the administrator. See note below for setting the adminstration password. Logging properties should also be set. Please follow the Log4j documentation for setting up log appenders and patterns. Default all events will be logged to the console and to a file. Syslog appender must be downloaded from the Log4j website see http://jakarta.apache.org/log4j/). 4. To actually send SMS messages, the SMSAuthenticator uses the Gsmlib tool 'gsmsendsmsmessage'. This tool must be installed, and a reference to the tool must be made in the properties file. Gsmlib has been tested with a number of GSM devices, currently (from the Gsmlib 1.9 README): - Nokia 6150/Xircom REM56G.100 - Nokia 6150/Options "GSM-Ready(R) Cellular-Only" modem from Option International - Nokia 6210/- (Linux IrDA serial device) - Nokia 8810/- (Linux IrDA serial device) - Siemens S10D/Dr Neuhaus Gipsy Card GSM - Siemens S25/- (Linux IrDA serial device) - Siemens S35i/- (Linux IrDA serial device) - Ericcson SH888/- (Linux IrDA serial device) - Ericsson 6050102/GM 12 GSM module - -/Siemens M20T (stand-alone GSM module) - -/Wavecom WM02 GSM (stand-alone GSM module) - Nokia 7110 (firware rev 4.80)/- (Linux IrDA serial device) - Nokia 8290 (USA GSM 1900MHz)/- (Linux IrDA serial device) - Falcom A2-1/- (stand-alone GSM module) - Ericsson R320s/- (Linux IrDA serial device) - Motorola Timeport 260/- (Serial cable and Linux IrDA serial device) - Motorola Timeport 250/- (Linux IrDA serial device) - Motorola Timeport P7389/- (Linux IrDA serial device) - Nokia Cellular Card Phone RPE-1 GSM900 and - Nokia Card Phone RPM-1 GSM900/1800 - Nokia Cardphone/Compaq iPAQ - Omnipoint technologies Redhawk 2000 GSM modem - Ericsson T28 (but one firmware revision is reported to have problems) - Ericcson T65 - Ericcson T39m/Bluetooth For convenience, the GSmlib 1.9 distribution is distributed in the current distribution, see the lib folder. 5. The SMSAuthenticator currently uses PostgreSQL to manage users. PostgreSQL must be set up separately. Database scripts may be found in the db folder. 'mysql.sql' contains script to create tables, and 'drop.sql' to drop the tables. Windows users should download and install the Cygwin package (www.cygwin.com) for PostgreSQL support. AlsoMake sure that you restrict access to the database, so that users won't be able to add/modify users outside of the provided administration interface. 6. After starting the servlet container, you should now be able to start using the SOAP service, see the 'USING' section below Note on setting the administration password: The administration password in the authenticator.properties file is a BASE64- encoded SHA-1 hash of the password. In order to set a new password you need to generate a BASE64-encoded SHA-1 hash of your own password. This may be done by running 'ant -Dinput=mypassword base64sha1'. This will output the following lines: base64sha1: [java] BASE64SHA-1: kd/Z3bQZiv/FwZTNjObTOP3kcOI= Where 'kd/Z3bQZiv/FwZTNjObTOP3kcOI=' is the BASE64-encoded SHA-1 hash of the password. Put this into your authenticator.properties file ('admin_password_hash' property). For this to work, Jakarta Apache Ant must be installed, see http://jakarta.apache.org/ant. Ant is also required to rebuild the SMSAuthenticator without JBuilder6 installed, see 'REBUILDING' section. USING ===== To manage the authenticator service after installing, start the servlet container and start the web interface at http://hostname:port/servlet/admin log in using the administrator username setup in the configuration file, default 'administrator'. The default password is 'drmovinckel'. If you do not have a GSM device attacked and configured, read the error log messages to get the single- use password required to log in. To use the authenticator SOAP service, follow the directions of your SOAP toolkit. Also, see the WDSL description found in the file SMSAuthenticator.wdsl and the deploymentdescriptor found in the file src/AuthenticatorService_Deployment_Descriptor.xml . Example code for using the SMSAuthenticator will be released shortly. Please contact us at 'thomas.strandenaes@telemed.no' if you need help on using the SMSAuthenticator using SOAP. REBUILDING ========== In order to rebuild the SMSAuthenticator from source and run unit tests, or to generate a new SMSAuthenticator.war distribution file, you need to install Apache Jakarta Ant or have JBuilder6 Enterprise Edition installed. See http://jakarta.apache.org/ant for Apache Jakarta Ant. Ant is the de-facto build tool for Java projects, so you probably want to go there anyway. After installing Ant, you should be able to recompile SMSAuthenticator by issuing the command 'ant compile' from the SMSAuthenticator root directory (contains the file build.xml). To run unit tests for the SMSAuthenticator, run 'ant test'. To rebuild SMSAuthenticator.war, run 'ant war'. If you perform changes to the deployment descriptor or otherwise want to redeploy the SOAP service, use the Ant build target 'deploy'. SMSAuthenticator is also distributed with the JBuilder6-EE project (pasientlink_authenticator.jpx). The project contains a web context for running/ debugging the SOAP server and for making the SMSAuthenticator war file. Use the 'AllTests' runtime configuration to run/debug tests. TROUBLESHOOTING =============== * Problem: When trying to use the admin interface of the SMSAuthenticator (http://hostname:port/servlet/admin), the browser time outs trying to get to the login page. * Possible solution: verify that the database is running and is accessible. TIPS ==== If you want to turn of directory browsing for the SMSAuthenticator admin files, change the init parameter 'listings' to 'false' in the conf/web.xml file (Tomcat 4.x): listings false LICENSING ========= The SMSAuthenticator uses a BSD-type open source license. See the file LICENSE.txt for further details. CONTACT ======= If you have any questions or comments, technical or otherwise, regarding the SMSAuthenticator or anything else except the PasientLink project: contact Thomas Strandenęs: thomas.strandenaes@telemed.no For more information about the PasientLink project: contact Per Egil Kummervold: per.egil.kummervold@telemed.no