Current Release: v5.0.2.6
Release Date: 2016-11-04
 Download

Current beta version:
Download


Innovation award


Last readme file
multiOTP(r) open source is a GNU LGPL implementation of a strong two-factor authentication PHP class
multiOTP(r) open source is OATH certified for HOTP/TOTP

(c) 2010-2014 SysCo systemes de communication sa
http://www.multiOTP.net/

Current build: 4.3.1.1 (2014-12-15)

Visit http://forum.multiotp.net/ for additional support.

The multiOTP(r) package is the lightest package available that provides so many
strong authentication functionalities and goodies, and best of all, for anyone
that is interested about security issues, it's a fully open source solution!

This package is the result of a *bunch* of work. If you are happy using this
package, [Donation] are always welcome to support this project.
Please check http://www.multiOTP.net/ and you will find the magic button ;-)
(OATH membership and certifications are not free, sponsorship welcome)

If you need some specific features in the open source edition of multiOTP(r),
please contact us in order to discuss about a sponsorship in order to
prioritize your needs.

This project is *NOT* sponsored by NSA.

The multiOTP(r) class supports currently the following algorithms and RFC's:
- RFC4226 OATH/HOTP (http://www.ietf.org/rfc/rfc4226.txt)
- RFC6238 OATH/TOTP (http://www.ietf.org/rfc/rfc6238.txt)
- Yubico OTP (http://yubico.com/yubikey)
- mOTP (http://motp.sourceforge.net)
- Google Authenticator (OATH/HOTP or OATH/TOTP, base32 seed, QRcode provisioning)
- SMS tokens (using aspsms, clickatell, intellisms, or even your own script)
- RFC6030 PSKC (Additional Portable Symmetric Key Container Algorithm Profiles)
- RFC1994 CHAP (Challenge Handshake Authentication Protocol)
- RFC2433 MS-CHAP (Microsoft PPP CHAP Extensions)
- RFC2759 MS-CHAPv2 (Microsoft PPP CHAP Extensions, Version 2)
- RFC5424 Syslog Protocol (client)


TABLE OF CONTENTS
=================
 * Donations and sponsoring
 * Roadmap for futures releases
 * What's new in the releases
 * Change Log of released version
 * Content of the package
 * When and how can I use this package ?
 * How to install the multiOTP(r) web service under Windows ?
 * How to install the multiOTP(r) radius server under Windows ?
 * Configuring multiOTP(r) with TekRADIUS or TekRADIUS LT under Windows
 * How to install the multiOTP(r) web service under Linux ?
 * Configuring multiOTP(r) with FreeRADIUS under Linux
 * How to configure multiOTP(r) to synchronized the users from an Active Directory ?
 * How to configure multiOTP(r) to synchronized the users from a standard LDAP ?
 * How to configure multiOTP(r) to use the client/server feature ?
 * How to build a Raspberry Pi strong authentication server ?
 * How to install a centralized strong authentication server
  for strong authentication on desktops ?
 * Compatible clients applications and devices
 * External packages used
 * multiOTP(r) PHP class documentation
 * multiOTP(r) command line tool


DONATIONS AND SPONSORING
========================
You can support our multiOTP(r) open source project with donations and sponsoring.
Sponsorships are crucial for ongoing and future development of the project!
If you'd like to support our work, then consider making a donation, any support
is always welcome even if it's as low as $1!
You can also sponsor the development of a specific feature. Please contact
us in order to discuss the detail of the implementation.

Thanks to our main donators and sponsors:
Donator AB (SE)
Henk van der Helm (NL)
Hermann Wegener GmbH & Co. KG (DE)
SerNet GmbH (DE)


ROADMAP FOR NEXT RELEASES
=========================
- Radius challenge/response support (4.3.1.2)
- Doxygen documentation format
- Generic web based SMS provider support
- Users CSV import
  (username;pin;prefix_pin_needed;email;sms;serial_number;manufacturer;algorithm;seed;digits;interval_or_event)
- Multiple hardware tokens support for one account
- Radius gateway support
- YubiCloud support
- FIDO support
- SMS-revolution SMS provider support
- SOAP API
- PostgreSQL support
- ...


WHAT'S NEW IN THE RELEASES
==========================
What's new in 4.3.x releases
- Raspberry Pi edition has now a special proxy to speed up the command line (4.3.1)
- Generic LDAP support (no more only Microsoft AD compatible LDAP) (4.3.1)
- New AD/LDAP sync algorithm to support larger AD (4.3.0)
- If users are synced with an AD, it's now possible to use the AD/LDAP password (4.3.0)
  instead of the PIN code (4.3.0)
- Yubico OTP support, including keys import using the log file in Traditional format (4.3.0)

What's new in 4.2.x releases
- A new option -user-info is now available (4.2.4.1)
- Tokens CSV import (4.2.4.1)
- NT_KEY can be displayed for further handling by FreeRADIUS (4.2.4.1)
- Lot of new QA tests, more than 60 different tests (4.2.4)
- Better MySQL support with mysqli library support (4.2.4)
- If activated, prefix PIN is now also requested for SMS authentication (4.2.2)
- Web GUI is complete for a simple usage (4.2.2)
- Some values can now go back to TekRADIUS (4.2.2)
- AD/LDAP is now fully supported (4.2.1)
- MS-CHAP and MS-CHAPv2 authentication support

What's new in 4.1.x releases
- Syslog support
- Token resync doesn't need prefix PIN anymore
- Specific parameters order in QRCode for Microsoft Authenticator support
- The open source edition of multiOTP(r) is also OATH certified for HOTP and TOTP,
  which includes encrypted PSKC import support
- Instructions and files to build your own strong authentication server device
  on a Raspberry Pi nano-computer
- Self-registration of unattributed hardware tokens
- Automatic resync/unlock during authentication
- Default Linux file mode is now set by default to 0666 to avoid access problem
- Basic web GUI

What's new in 4.0.x releases
- Full client/server support with local cache
- CHAP authentication support
- Emergency scratch passwords list
  (providing a list of 10 emergency one-time-usage passwords)
- SMS code sending (with clickatell, aspsms, intellisms and custom exec support)
- integrated Google Authenticator support with integrated base 32 seed handling
- Conversion from hardware HOTP/TOTP tokens to software tokens
- QRcode generation for HOTP/TOTP automatic provisioning
- Integrated QRcode generator library (from Y. Swetake)
- Group attribute per user (sent back through the Radius attribute Filter-Id)
- A lot of new options, also available in command line
- Options are stored in an external configuration file (or in the database)
- Full MySQL support, including tables creation
- Fully automatic build chain (invisible for you, but very nice for me)
- (Parts of the) comments have been reformatted and enhanced,
  but still some work to do...

What's new in 3.9.x releases
- Support for account with multiple users
- Some bug fixes

What's new in 3.2.x releases
- Google Authenticator support. Special information to handle the base 32 seed.
- Better MySQL backend integration (still in beta). Now it is possible to store
  all information in a MySQL backend instead of a flat file


CHANGE LOG OF RELEASED VERSIONS
===============================
2014-12-15 4.3.1.1 SysCo/al Better generic LDAP support
                              - description sync done in the following order: description, gecos, displayName
                              - memberOf is not always implemented, alternative method to sync users based on group names.
                              - disabled account synchronization using shadowExpire or sambaAcctFlags
                            Better Active Directory support
                              - accountExpires is now supported for synchronization
                              - ms-DS-User-Account-Control-Computed (to handle locked out accounts, available since Windows 2003)
2014-12-09 4.3.1.0 SysCo/al MULTIOTP_PATH environment variable support
                            CLI proxy added to speed up the command line
                            Scratch password need also the prefix PIN if it's activated
                            OTP with integrated serial numbers better supported (in PAP)
                            Generic LDAP support (instead of Microsoft AD support only)
                            Raspberry Pi edition has now a special proxy to speed up the command line
2014-11-04 4.3.0.0 SysCo/al It's now possible to use the AD/LDAP password instead of the PIN code
                            Yubico OTP support, including keys import using the log file in Traditional format
                            qrcode() stub enhanced to check if the required folders are available
                            SyncLdapUsers completely redesigned
                              - no more complete array in memory
                              - MultiotpAdLdap class also enhanced accordingly
                                - cached group_cn requests
                                - cached recursive_groups requests
                                - new "by element" functions
                            Demo mode support
                            Bug fix concerning the NT_KEY generation with enabled prefix PIN (thanks Adam)
                            ResyncToken() method added (instead of using CheckToken() method for synchronization)
2014-06-12 4.2.4.3 SysCo/al Bug fix concerning aspsms provider
2014-04-13 4.2.4.2 SysCo/al XML parsing consolidation, one library for the whole project
                            Fixed bug concerning tokens CSV import
2014-04-13 4.2.4.2 SysCo/al XML parsing consolidation, one library for the whole project
                            Fixed bug concerning tokens CSV import
2014-04-06 4.2.4.1 SysCo/al Fixed bug concerning LDAP handling
                            NT_KEY support added (for FreeRADIUS further handling)
                            Tokens CSV import (serial_number;manufacturer;algorithm;seed;digits;interval_or_event)
                            When a user is deleted, the token(s) attributed to this user is/are unassigned
                            New option -user-info added
2014-03-30 4.2.4   SysCo/al Fixed bug concerning MySQL handling and mysqli support added
                            Enhanced SetAttributesToEncrypt function
                            New implementation fo some external classes
                            Generated QRcode are better
                            LOT of new QA tests, more than 60 different tests (including PHP class and command line versions)
                            Enhanced documentation
2014-03-13 4.2.3   SysCo/al Fixed bug for clear text password going back to TekRADIUS (PIN was always prefixed for mOTP)
2014-03-03 4.2.2   SysCo/al Better AD/LDAP integration
                            Web GUI is now complete for a simple usage, including hardware tokens import
                            Better template for provisioning information
                            Some values can now go back to TekRADIUS
                            If activated, prefix PIN is now also requested for SMS authentication
                            More information in the logs
                            Better list of the external packages used
2014-02-14 4.2.1   SysCo/al AD/LDAP is now fully supported in order to create users based on AD/LDAP content
                            (with groups filtering)
2014-02-07 4.2.0   SysCo/al MS-CHAP and MS-CHAPv2 are now supported
                            (md4 implementation added for PHP backward compatibility)
                            Enhanced LDAP configuration structure
                            Fixed bug during token attribution to users
                            (a "no name" token appeared sometimes)
2014-01-20 4.1.1   SysCo/al md5.js was missing in the public distribution
                            Alternate json_encode function is defined if the JSON extension is not loaded
                            Fixed possible image functions incompatibilities with some PHP versions
                            during QRcode generation
                            As suggested by Sylvain, token resync doesn't need prefix PIN anymore
                            (but still accepted)
                            More verbosity in the logs in debug mode
                            Specific parameters order in QRCode for Microsoft Authenticator support
                            (thanks to Erik Nylund)
2013-12-23 4.1.0   SysCo/al The open source edition of multiOTP(r) is OATH certified ;-)
                            (that means full compatibility with any OATH tokens and encrypted PSKC import support)
                            Raspberry Pi nano-computer is now fully supported
                            Basic web interface
                            Self-registration of hardware tokens is now possible
                            PAP mode: if self-registration is enabled, a user can register a non-attributed token by typing
                            [serial number][OTP] instead of [OTP]. If user has a prefix PIN, type [serial number][PIN][OTP])
                            PAP/CHAP mode: if self-registration is enabled, a user can register a non-attributed token by typing
                            [username:serialnumber] as the username and the [OTP] in the password field. If user has a prefix PIN,
                            he must type [PIN][OTP] in the password field
                            Automatic resync/unlock option during authentication (PAP only). When the autoresync option is enabled,
                            any user can resync his token by typing [OTP1] [OTP2] in the password field. If user has a prefix PIN,
                            he must type [PIN][OTP1] [PIN][OTP2].
                            Tokens with less than 3 characters are not accepted anymore in CheckToken()
                            Default Linux file mode is now set by default (0666 for created and changed files)
                            Error 28 is returned if the file is not writable, even after a successful login
                            Added GetUsersCount() function
                            Added GenerateSmsToken() function
                            Added Groups management functions
                            Added Tokens assignation functions
                            Added SetUserActivated(1|0) and GetUserActivated() function
                            Added SetUserSynchronized(1|0) and GetUserSynchronized() function
                            scratch_passwords is now a text field in the database
                            The third parameter of the Decrypt method is now mandatory
                            Some modifications in order to correctly handle the class methods
2013-09-22 4.0.9   SysCo/al Fixed a bug in GetUserScratchPasswordsArray. If a user had no scratch password
                            and the implementation accepted blank password, it was accepted
2013-08-30 4.0.7   SysCo/al GetScriptFolder() was still buggy sometimes, thanks Frank for the feedback
                            File mode of the created QRcode file is also changed base on GetLinuxFileMode()
                            'sms' as the password to request an SMS token can now be sent in lower or uppercase
                            Added a description attribute for the tokens
2013-08-25 4.0.6   SysCo/al base32_encode() is now RFC compliant with uppercases
                            GetUserTokenQrCode() and GetTokenQrCode() where buggy
                            GetScriptFolder() use now __FILE__ if the full path is included
                            When doing a check in the CLI header, @... is automatically removed from the
                            username if the user doesn't exist, and the check is done on the clean name
                            Added a lot of tests to enhance release quality
2013-08-21 4.0.5   SysCo/al Fixed the check of the cache lifetime
                            Added a temporary server blacklist during the same instances
                            Default server timeout is now set to 1 second
2013-08-20 4.0.4   SysCo/al Adding an optional group attribute for the user
                            (which will be send with the Radius Filter-Id option)
                            Adding scratch passwords generation (if the token is lost)
                            Automatic database schema upgrade using method UpgradeSchemaIfNeeded()
                            Adding client/server support with local cache
                            Adding CHAP authentication support (PAP is of course still supported)
                            The encryption key is now a parameter of the class constructor
                            The method SetEncryptionKey('MyPersonalEncryptionKey') is DEPRECATED
                            The method DefineMySqlConnection is DEPRECATED
                            Full MySQL support, including tables creation (see example and SetSqlXXXX methods)
                            Adding email, sms and seed_password to users attributes
                            Adding sms support (aspsms, clickatell, intellisms, exec)
                            Adding prefix support for debug mode (in order to send Reply-Message := to Radius)
                            Adding a lot of new methods to handle easier the users and the tokens
                            General speedup by using available native functions for hash_hmac and others
                            Default max_time_window has been lowered to 600 seconds (thanks Stefan for suggestion)
                            Integrated Google Authenticator support with integrated base 32 seed handling
                            Integrated QRcode generator library (from Y. Swetake)
                            General options in an external configuration file
                            Comments have been reformatted and enhanced for automatic documentation
                            Development process enhanced, source code reorganized, external contributions are
                            added automatically at the end of the library after an internal build release
2011-10-25 3.9.2   SysCo/al Some quick fixes after intensive check
                            Improved get_script_dir() in CLI for Linux/Windows compatibility
2011-09-15 3.9.1   SysCo/al Some quick fixes concerning multiple users
2011-09-13 3.9.0   SysCo/al Adding support for account with multiple users
2011-07-06 3.2.0   SysCo/al Encryption hash handling with additional error message 33
                            (if the key has changed)
                            Adding more examples
                            Adding generic user with multiple account
                            (Real account name is combined: "user" and "account password")
                            Adding log options, now default doesn't log token value anymore
                            Debugging MySQL backend support for the token handling
                            Fixed automatic detection of \ or / for script path detection
2010-12-19 3.1.1   SysCo/al Better MySQL backend support (still in beta), including in CLI version
2010-09-15 3.1.0   SysCo/al Removed bad extra spaces in the multiotp.php file for Linux
                            Beta MySQL backend support
2010-09-02 3.0.0   SysCo/al Adding tokens handling support, including importing XML tokens definition file
                            Enhanced flat database file format
                            (multiOTP(r) is still compatible with old versions)
                            Internal method SetDataReadFlag renamed to SetUserDataReadFlag
                            Internal method GetDataReadFlag renamed to GetUserDataReadFlag
2010-08-21 2.0.4   SysCo/al Enhancement in order to use an alternate php "compiler"
                            for Windows command line
                            Documentation enhancement
2010-08-18 2.0.3   SysCo/al Minor notice fix, define timezone if not defined (for embedded command line)
                            If user doesn't exist, do not create the related flat file after a check
2010-07-21 2.0.2   SysCo/al Fix to create correctly the folders "users" and "log" if needed
2010-07-19 2.0.1   SysCo/al Foreach was not working well in PHP4, replaced at some places
2010-07-19 2.0.0   SysCo/al New design using a class, mOTP support, cleaning of the code
2010-06-15 1.1.5   SysCo/al Adding OATH/TOTP support
2010-06-15 1.1.4   SysCo/al Project renamed to multiOTP(r) to avoid overlapping
2010-06-08 1.1.3   SysCo/al Typo in script folder detection
2010-06-08 1.1.2   SysCo/al Typo in variable name
2010-06-08 1.1.1   SysCo/al Status bar during resynchronization
2010-06-08 1.1.0   SysCo/al Fix in the example, distribution not compressed
2010-06-07 1.0.0   SysCo/al Initial implementation


CONTENT OF THE PACKAGE
======================
In the linux folder:
- multiotp.php             : command line tool (merge of the header and the class, external files also included)
- multiotp.class.php       : the main file, it is the class itself, external files are already included
- multiotp.server.php     : the web service file (the class is already merged in the file, external files also included)
- check.multiotp.class.php : PHP script to validate some multiOTP(r) functionalities
- md5.js                   : encryption JS library used by multiotp.server.php
- test-tokens.csv         : provisioning file of test tokens
+ oath subfolder           : contains provisioning files for oath test tokens
+ qrcode subfolder         : all necessary files to be able to generate QRcode
+ templates folder         : all templates files needed to generate the provisioning pages from the web GUI

In the raspberry folder:
- all necessary files to be able to create your own strong authentication device using a Raspberry Pi

In the sources folder:
- multiotp.class.php       : the main file, it is the class itself, which requires external files
- multiotp.cli.header.php : header file to be merged with the class for a single file command line tool
- multiotp.server.php     : the web service file, which requires the class as external file
- check.multiotp.class.php : PHP script to validate some multiOTP(r) functionalities
+ contrib subfolder       : contains all external files required by the multiotp.class.php file

In the windows folder:
- multiotp.exe             : command line tool for Windows (digitally signed) with embedded PHP 5.3.1
- multiotp.class.php       : the main file, it is the class itself, external files are already included
- multiotp.server.php     : the web service file (the class is already merged in the file, external files also included)
- check.multiotp.class.php : PHP script to validate some multiOTP(r) functionalities
- md5.js                   : encryption JS library used by multiotp.server.php
- checkmultiotp.cmd       : Windows script to validate some multiOTP(r) functionalities
- radius_debug.cmd         : Windows script to run the multiOTP(r) radius web server in debug mode
- radius_install.cmd       : Windows script to install and start the multiOTP(r) radius web server
- radius_uninstall.cmd     : Windows script to stop and uninstall the multiOTP(r) radius web server
- webservice_install.cmd   : Windows script to install and start the multiOTP(r) web service
- webservice_uninstall.cmd : Windows script to stop and uninstall the multiOTP(r) web service
- test-tokens.csv         : provisioning file of test tokens
+ oath subfolder           : contains provisioning files for oath test tokens
+ qrcode subfolder         : all necessary files to be able to generate QRcode
+ radius subfolder         : all necessary files to be able to install a Windows radius server already
                            configured with multiOTP(r) support (using FreeRADIUS implementation for Windows)
+ templates subfolder     : all templates files needed to generate the provisioning pages from the web GUI
+ tools subfolder         : command line tools needed by some cmd scripts
+ webservice subfolder     : all necessary files to be able to install a Windows multiOTP(r) web service
                            (using mongoose as the light web server on port 8112,
                              or as a secured SSL connection (https) on port 8113)


WHEN AND HOW CAN I USE THIS PACKAGE ?
=====================================
If you decide to have strong two factor authentication inside your company,
this is definitely the package you need! You will be able to have strong
authentication for your VPN accesses, your SSL gateway, your private websites
and even your Windows login for desktops AND laptops!

The multiOTP(r) class can be used alone (for example to have strong
authentication for your PHP based web application), as a command line tool
(to handle users and have strong authentication using command line), as a web
service (to provide centralized authentication for a master/slave installation)
or finally coupled with a radius server like TekRADIUS or FreeRADIUS to be able
to have a strong two factor authentication through the RADIUS protocol for
external devices like for example firewalls or captive portals.

The default backend storage is done in flat files, but you can also defined a
MySQL server as the backend server. To use MySQL, you will only have to provide
the server, the username, the password and the database name. Tables will be
created/updated automatically by multiOTP(r). The schema is also upgraded
automatically if you install a new release of multiOTP(r).

Starting with version 4.x, you can also install a multiOTP(r) web service
on a server, and this way some other multiOTP(r) slave clients (like laptops)
can connect to the web service and caching the tokens information (if allowed).

Inside a company, you will probably use multiOTP(r) with a radius server or as
a web service (see below on how to install these services).

If you are running under Windows, TekRADIUS or TekRADIUS LT will do the job
(http:/www.tekradius.com/).
The difference is that TekRADIUS needs an MS-SQL SERVER (or MS-SQL Express)
and TekRADIUS LT uses only an embedded SQLite database.

multiOTP is working fine under Windows with WinRADIUS, a port of FreeRADIUS
(http://winradius.eu/)

multiOTP is also working fine with another port of FreeRADIUS
for Windows (http://sourceforge.net/projects/freeradius/)

If you are running under Linux, FreeRADIUS will do the job.
(http://freeradius.org/)

Now, you can register your different devices like firewalls, SSL, etc.
in the radius server and provide the IP address(es) of the device(s)
(often called NAS) and their shared Secret.

If you want to have strong authentication on Windows logon, have a look at the
open source MultiOneTimePassword Credential Provider from Last Squirrel IT.
It works with Windows Vista/7/2008/8/2012 in both 32 and 64 bits.
The Credential Provider does not need any RADIUS connection! It uses instead a
local version of multiOTP(r) which can be configured as a client of a
centralized server (with caching support).
(https://code.google.com/p/multi-one-time-password--credential-provider/)

LSE Experts provides a commercial Radius Credential Provider which can talk
directly with a radius server.
(http://www.lsexperts.de)

When the backend is set, it's time to create/define the tokens. You will have
to select hardware or software token generators for your users. Currently, the
library supports mOTP, TOTP, HOTP, SMS or scratch passwords (printed on paper).

mOTP is a free implementation of strong tokens that asks a PIN to generate a
code. This code depends of the time and the PIN typed by the user.

The easiest tokens to use are TOTP, they are time based and well supported by
a lot of implementations like Google Authenticator.
Provisioning will be done simply by flashing a QRcode.

Software tokens with mOTP support
  iPhone:   iOTP from PDTS (type iOTP in the Apple AppStore)
  Android:   Mobile-OTP (http://motp.sf.net/Mobile-OTP.apk)
  PalmOS:   Mobile-OTP (http://motp.sf.net/mobileotp_palm.zip)
  Java J2ME (Nokia and other Java capable phones): MobileOTP
            (http://motp.sf.net/MobileOTP.jad)
  ...
 
Software tokens with OATH compliant HOTP or TOTP support
  Check the various markets of your devices, for examples:
    Google Authenticator (Android/iPhone/iPad/BlackBerry)
    oathtoken for iPhone/iPad: http://code.google.com/p/oathtoken/
    androidtoken for Android: http://code.google.com/p/androidtoken/
    ...

Hardware tokens
  Any tokens that are OATH certified
  Feitian provides OATH compliant HOTP and TOTP tokens
    (seed is provided in a standardized token definition PSKC xml file)
  - OTP c100: OATH/HOTP, 6 digits
  - OTP c200: OATH/TOTP, 6 digits, 60 seconds time interval
    (seed is provided in a standardized token definition PSKC xml file)
  ZyXEL OTP provides HOTP OATH compliant tokens (v2 and old v1 tokens)
  - ZyWALL OTPv2 (rebranded SafeNet/Aladdin eToken PASS) : OATH/HOTP, 6 digits
    (seed is extracted from the importAlpine.dat downloaded file,
      the seed is the sccKey attribute)
  - ZyWALL OTPv1 (rebranded Authenex A-Key 3600): OATH/HOTP, 6 digits
    (seed is extracted from the OTP_data01_upgrade.sql SQL file,
      SEED field at the end of the file)
  Seamoon provides OATH compliant TOTP tokens
  - Seamoon KingKey: OATH/TOTP, 6 digits, 60 seconds time interval
    (seed is provided in a specific smd file)
    ...

If you want to use software tokens with Apps like Google Authenticator, you can
create a QRcode provisioning in two EASY steps with the command line tool:
 - create the token for the user: multiotp -fastcreate my_user
 - generate the provisioning QRcode: multiotp -qrcode my_user my_qrcode.png


HOW TO INSTALL THE MULTIOTP(r) WEB SERVICE UNDER WINDOWS ?
==========================================================
Installing the multiOTP(r) web service is VERY easy. Simply run the
webservice_install script. Mongoose configuration file will be created,
firewall rules will be adapted and the service will be installed and started.
The service is called multiOTPservice and is listening on port 8112 (http)
and on port 8113 (https).


HOW TO INSTALL THE MULTIOTP(r) RADIUS SERVER UNDER WINDOWS ?
============================================================
Installing the multiOTP(r) radius service is VERY easy too. Simply run the
radius_install script. The etc/raddb/modules/multiotp file will be created,
firewall rules will be adapted and the service will be installed and started.
The service is called multiOTPradius and the secret is multiotpsecret for any
client including 127.0.0.1.


CONFIGURING MULTIOTP(r) WITH TEKRADIUS OR TEKRADIUS LT UNDER WINDOWS
====================================================================
TekRADIUS supports a Default Username to be used when a matching user
profile cannot be found for an incoming RADIUS authentication request.
So a quick and easy way is to create in the TekRADIUS Manager a User
named 'Default' that belongs to the existing 'Default' Group.
Then add to this Default user the following attribute :
Check External-Executable C:\multitop\multiotp.exe %ietf|1% %ietf|2% -chap-challenge=%msoft|60% -chap-password=%msoft|3% -ms-chap-challenge=%msoft|11% -ms-chap-response=%msoft|1% -ms-chap2-response=%msoft|25%

Some values can go back to TekRADIUS:

a) Set the right format options for TekRADIUS:
  multiotp -config radius-reply-attributor="=" radius-reply-separator="crlf"
   
b) Set multiOTP to send back to TekRADIUS the clear (non encrypted) authentication:
  multiotp -config clear-otp-attribute="ietf|2"

c) Set multiOTP to send back to TekRADIUS the group of the authenticated user:
  multiotp -config group-attribute="ietf|11"


HOW TO INSTALL THE MULTIOTP(r) WEB SERVICE UNDER LINUX ?
========================================================
The multiOTP(r) web service is a simple web site. If you are under Linux and you
are reading this document, you have for sure the necessary skill to configure
your favorite web server in order to have an URL that will launch the page
multiotp.server.php which is in the main folder of the multiOTP(r) distribution.


CONFIGURING MULTIOTP(r) WITH FREERADIUS UNDER LINUX
===================================================
Using the -request-nt-key option, NT_KEY: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX can
now be displayed (like with the same option used with ntlm_auth).

1) Create a new module file called "multiotp" in etc/raddb/modules/ containing:
# Exec module instance for multiOTP(r) (http://www.multiotp.net/).
# for Linux : replace '/path/to' with the actual path to the multiotp.php file.
# for Windows: replace '/path/to' with the actual path to the multiotp.exe file (also with /).
exec multiotp {
        wait = yes
        input_pairs = request
        output_pairs = reply
        program = "/path/to/multiotp '%{User-Name}' '%{User-Password}' -request-nt-key -src=%{Packet-Src-IP-Address} -chap-challenge=%{CHAP-Challenge} -chap-password=%{CHAP-Password} -ms-chap-challenge=%{MS-CHAP-Challenge} -ms-chap-response=%{MS-CHAP-Response} -ms-chap2-response=%{MS-CHAP2-Response}"
        shell_escape = yes
}

2) In the configuration file called "default" in etc/raddb/sites-enabled/
    a) Add the multiOTP(r) handling
    #
    # Handle multiOTP(r) (http://www.multiotp.net/) authentication.
    # This must be add BEFORE the first "pap" entry found in the file.
    multiotp
   
    b) Add the multiOTP(r) authentication handling
    #
    # Handle multiOTP(r) (http://www.multiotp.net/) authentication.
    # This must be add BEFORE the first "Auth-Type PAP" entry found in the file.
    Auth-Type multiotp {
        multiotp
    }
   
    c) Comment the first line containing only "chap"
    #chap is now handled by multiOTP(r)
   
3) In the configuration file called "inner-tunnel" in etc/raddb/sites-enabled/
    a) Add the multiOTP(r) handling
    #
    # Handle multiOTP(r) (http://www.multiotp.net/) authentication.
    # This must be add BEFORE the first "pap" entry found in the file.
    multiotp
   
    b) Add the multiOTP(r) authentication handling
    #
    # Handle multiOTP(r) (http://www.multiotp.net/) authentication.
    # This must be add BEFORE the first "Auth-Type PAP" entry found in the file.
    Auth-Type multiotp {
        multiotp
    }
   
    c) Comment the first line containing only "chap"
    #chap is now handled by multiOTP(r)

4) In the configuration file called "policy.conf" in etc/raddb/
    a) Add the multiOTP(r) authorization policy
    #
    # Handle multiOTP(r) (http://www.multiotp.net/) authorization policy.
    # This must be add just before the last "}"
    multiotp.authorize {
        if (!control:Auth-Type) {
            update control {
                Auth-Type := multiotp
            }
        }
    }

5) In the configuration file called "radiusd.conf" in etc/raddb/
    a) Depending which port(s) and/or ip address(es) you want to listen, change
      the corresponding ipaddr and port parameters

6) In the configuration file called "clients.conf" in etc/raddb/
    a) Add the clients IP, mask and secret that you want to authorize.
    #
    # Handle multiOTP(r) (http://www.multiotp.net/) for some clients.
    client 0.0.0.0 {
    netmask = 0
    secret = multiotpsecret
    }
   
7) Now, to see what's going on, you can:
  - stop the service : /etc/init.d/freeradius stop
  - launch the FreeRADIUS server in debug mode : /usr/sbin/freeradius -X
  - try to make some authentication requests

8) When you have checked that everything works well:
  - stop the debug mode (CTRL + C)
  - restart the service /etc/init.d/freeradius restart

Some values can go back to FreeRADIUS:

a) Set the right format options for FreeRADIUS:
  multiotp -config radius-reply-attributor=" = " radius-reply-separator=","
   
b) Set multiOTP(r) to send back to FreeRADIUS the group of the authenticated user:
  multiotp -config group-attribute="Filter-Id"


HOW TO CONFIGURE MULTIOTP(r) TO SYNCHRONIZED THE USERS FROM AN ACTIVE DIRECTORY ?
=================================================================================
1) Decide if you want that by default, created users need to type a prefix PIN (1|0):
  multiotp -config default-request-prefix-pin=1
   
2) Decide if you want that by default, created users need to type their
  Active Directory password instead of PIN (1|0):
  multiotp -config default-request-ldap-pwd=1

3) Set the AD/LDAP server type (1=Active Directory | 2=standard LDAP):
  multiotp -config ldap-server-type=1

4) Set the user CN identifier (sAMAccountName, eventually userPrincipalName):
  multiotp -config ldap-cn-identifier="sAMAccountName"

5) Set the group CN identifier (sAMAccountName for Active Directory):
  multiotp -config ldap-group-cn-identifier="sAMAccountName"

6) Set the group attribute:
  multiotp -config ldap-group-attribute="memberOf"

7) Decide if you want to use by default an SSL connection or not (0|1):
  multiotp -config ldap-ssl=0
   
8) Set the default port (389=regular | 636=SSL connection):
  multiotp -config ldap-port=389
   
9) Set the Active Directory server(s), comma separated:
  multiotp -config ldap-domain-controllers=my.srv.com,ldaps://12.13.14.15:636
  (you can define more than one server, and you can also use a SSL connection
    only for one server, on a specific port)
   
10) Set the Base DN:
    multiotp -config ldap-base-dn="DC=demo,DC=multiotp,DC=net"
    (on a Microsoft Windows Server, the different values of the base DN of the
    domain can be displayed using the command ECHO %USERDNSDOMAIN%, and the
    result will be something like DEMO.MULTIOTP.NET)

11) Set the Bind DN (which is the account used to connect to the AD/LDAP):
    multiotp -config ldap-bind-dn="CN=sync,CN=Users,DC=demo,DC=multiotp,DC=net"
    (on a Microsoft Windows Server, the bind DN of the user can be displayed
    using the command dsquery user -name sync, and the result will be
    something like "CN=sync,CN=Users,DC=demo,DC=multiotp,DC=net")
   
12) Set the password of the user used to search in the Active Directory:
    multiotp -config ldap-server-password="password_of_my_ldap_user"
   
13) In which groups users must be in the Active Directory in order to be added:
    multiotp -config ldap-in-group="VPNuser,dialin"
   
14) Set the network timeout
    multiotp -config ldap-network-timeout=10
   
15) Set the transaction time limit
    multiotp -config ldap-time-limit=30

16) Activate the AD/LDAP support (0|1):
    multiotp -config ldap-activated=1
   
17) Let's go for an AD/LDAP users synchronisation !
    (users removed or desactivated in the AD/LDAP are desactivated in multiOTP(r))
    multiotp -debug -display-log -ldap-users-sync
   
DON'T FORGET TO SCHEDULE A SCRIPT THAT WILL DO THE USERS SYNCHRONIZATION REGULARY!


HOW TO CONFIGURE MULTIOTP(r) TO SYNCHRONIZED THE USERS FROM A STANDARD LDAP ?
=============================================================================
1) Decide if you want that by default, created users need to type a prefix PIN (1|0):
  multiotp -config default-request-prefix-pin=1
   
2) Decide if you want that by default, created users need to type their
  LDAP password instead of PIN (1|0):
  multiotp -config default-request-ldap-pwd=1

3) Set the AD/LDAP server type (1=Active Directory | 2=standard LDAP):
  multiotp -config ldap-server-type=2

4) Set the user CN identifier (uid for standard LDAP):
  multiotp -config ldap-cn-identifier="uid"

5) Set the group CN identifier (cn for standard LDAP):
  multiotp -config ldap-group-cn-identifier="cn"

6) Set the group attribute:
  multiotp -config ldap-group-attribute="memberOf"

7) Decide if you want to use by default an SSL connection or not (0|1):
  multiotp -config ldap-ssl=0
   
8) Set the default port (389=regular | 636=SSL connection):
  multiotp -config ldap-port=389
   
9) Set the LDAP server(s), comma separated:
  multiotp -config ldap-domain-controllers=my.srv.com,ldaps://12.13.14.15:636
  (you can define more than one server, and you can also use a SSL connection
    only for one server, on a specific port)
   
10) Set the Base DN:
    multiotp -config ldap-base-dn="dc=demo,dc=multiotp,dc=net"

11) Set the Bind DN (which is the account used to connect to the AD/LDAP):
    multiotp -config ldap-bind-dn="uid=sync,cn=users,dc=demo,dc=multiotp,dc=net"
   
12) Set the password of the user used to search in the LDAP directory:
    multiotp -config ldap-server-password="password_of_my_ldap_user"
   
13) In which groups users must be in LDAP directory in order to be added:
    multiotp -config ldap-in-group="VPNuser,dialin"
   
14) Set the network timeout
    multiotp -config ldap-network-timeout=10
   
15) Set the transaction time limit
    multiotp -config ldap-time-limit=30

16) Activate the AD/LDAP support (0|1):
    multiotp -config ldap-activated=1
   
17) Let's go for an AD/LDAP users synchronisation !
    (users removed or desactivated in the AD/LDAP are desactivated in multiOTP(r))
    multiotp -debug -display-log -ldap-users-sync

DON'T FORGET TO SCHEDULE A SCRIPT THAT WILL DO THE USERS SYNCHRONIZATION REGULARY!


HOW TO CONFIGURE MULTIOTP(r) TO USE THE CLIENT/SERVER FEATURE ?
===============================================================
A) On the server
1) Install the multiOTP(r) web service on the server side. If you are
  using the unmodified included installer to install it under Windows, the
  URL for the multiOTP(r) web service is http://ip.address.of.server:8112
  The web service script installer is called webservice_install.cmd.
2) Set the shared secret key you will use to encode the data between the
  server and the client: multiotp -config server-secret=MySharedSecret
  (this command line will change the configuration file config/multiotp.ini)
3) If you want to allow the client to cache the data on its side, set the
  options accordingly (enable the cache and define the lifetime of the cache):
  multiotp -config server-cache-level=1 server-cache-lifetime=15552000
  (this command line will change the configuration file config/multiotp.ini)
4) Create your users on the server using the web GUI interface. If you are
  using the unmodified included installer to install it under Windows, the
  URL for the multiOTP(r) web service is http://ip.address.of.server:8112

B) On the client(s)
1) Set the shared secret key you will use to encode the data between the
  client and the server: multiotp -config server-secret=MySharedSecret
  (this command line will change the configuration file config/multiotp.ini)
2) If you want to have cache support (if allowed by the multiOTP(r) web service),
  set the option accordingly: multiotp -config server-cache-level=1
  (this command line will change the configuration file config/multiotp.ini)
3) Define the timeout after which you will switch to the next server(s), and
  on the local cache if no server available: multiotp -config server-timeout=3
  (this command line will change the configuration file config/multiotp.ini)
4) Last but not least, define the server(s) you want to connect with:
  multiotp -config server-url=http://ip.address.of.server:8112;http://url2
  (this command line will change the configuration file config/multiotp.ini)
5) Check your installation on the client by typing
  multiotp -display-log -log -debug "user" "token", where "user" is an
  existing user and "token" is the generated token for this user.
  If you have created a user with a prefix PIN, don't forget to type the prefix
  PIN before the displayed token.
  Example without a prefix PIN: multiotp test 457863
  Example with the "1234" prefix PIN: multiotp test 1234457863

   
HOW TO INSTALL A CENTRALIZED STRONG AUTHENTICATION SERVER
FOR STRONG AUTHENTICATION ON DESKTOPS ?
=========================================================
1) Install a client/server multiOTP(r) environment like explained above.
2) On each client, install MultiOneTimePassword Credential Provider (mOTP-CP)
  (https://code.google.com/p/multi-one-time-password--credential-provider/).
  It works with Windows Vista/7/2008/8/2012 in both 32 and 64 bits.
3) During the installation, specify the folder on the client where the
  multiotp.exe file is installed and configured.


HOW TO BUILD A RASPBERRY PI STRONG AUTHENTICATION SERVER ?
==========================================================
0) If you want to download a multiOTP Raspberry Pi image ready to use, follow this URL:
  http://download.multiotp.net/raspberry/
   
  Nano-computer name: multiotp
  IP address: 192.168.1.44 (netmask: 255.255.255.0, default gateway: 192.168.1.1)
  Username: pi
  Password: raspberry
   
  You can now flash the SD (check point 3) and 4) if needed), put the SD Card
  into the Raspberry Pi and boot it. You can go directly to point 15)
   
1) If you want to use a battery backed up Real Time Clock, install it now in your
  Raspberry Pi, the drivers for these models are included in the package:
    http://afterthoughtsoftware.com/products/rasclock
    http://www.cjemicros.co.uk/micros/products/rpirtc.shtml
    http://www.robotshop.com/ca/en/mini-real-time-clock-rtc-module.html
    http://nicegear.co.nz/raspberry-pi/high-precision-real-time-clock-for-raspberry-pi/
   
2) Download the last image of Raspbian to be flashed
  http://downloads.raspberrypi.org/raspbian_latest (currently 2014-09-09-wheezy-raspbian.zip)

3) Format your SD Card using the SD Card Association’s formatting tool
  https://www.sdcard.org/downloads/formatter_4/

4) Flash the raw image using UNIX tool dd or Win32DiskImager for Windows
  (http://sourceforge.net/projects/win32diskimager/files/latest/download).
  This should take about 10 minutes.

5) Copy all files from multiotp/raspberry/boot-part to the root of the SD Card
  (it could overwrite some files like config.txt)

6) When copy is done, eject the SD Card

7) Connect the Raspberry Pi to the local network

8) Put the SD card into the Raspberry Pi and boot it

9) Login directly on your Raspberry Pi, or using SSH, with the default username "pi" and the password "raspberry"

10) Launch the initial configuration by typing sudo raspi-config

11) Choose the following options
    1) Expand Filesystem
    2) Change User Password
    4) Internationalisation Options (if needed)
    8) Advanced Options
      A2 Hostname (change the hostname to your favorite name, for example "multiotp")

12) Select Finish and answer "" to reboot, ore type "sudo reboot"

13) Login again directly (after about 30 seconds) on your Raspberry Pi, or using SSH, with the default username "pi" and your new password

14) Type "sudo /boot/install.sh"
    Everything is done automatically (it will take about 35 minutes) and the Raspberry Pi is rebooted automatically

15) The fixed IP address is set to 192.168.1.44, with a default gateway at 192.168.1.1
    To adapt the network configuration, edit the file /etc/network/interfaces

16) Congratulations! You have now an open source and fully OATH compliant
    strong two factors authentication server!
    Surf on http(s)://192.168.1.44 to use the basic interface (admin / 1234)

17) The default radius secret is set to myfirstpass for the subnet 192.168.0.0/16.
    To adapt the freeradius configuration, edit the file /etc/freeradius/clients.conf.


COMPATIBLE CLIENTS APPLICATIONS AND DEVICES
===========================================
MultiOneTimePassword Credential Provider (mOTP-CP)
If you want to have strong authentication on Windows logon, have a look at the
open source MultiOneTimePassword Credential Provider from Last Squirrel IT.
It works with Windows Vista/7/2008/8/2012 in both 32 and 64 bits.
The Credential Provider is using directly a local version of multiOTP(r) which
can be configured as a client of a centralized multiOTP(r) server (with caching support)
(https://code.google.com/p/multi-one-time-password--credential-provider/)

LSE Experts is providing a commercial Radius Credential Provider which can talk
directly with any radius server to check the token. multiOTP(r) will work with it.
(http://www.lsexperts.de)

Any firewall can connect with the Radius protocol to a multiOTP(r) radius server.
On advanced firewalls like the ZyXEL ZyWALL USG series, you can do some advanced
things like:
- receiving a specific group for each multiOTP(r) user (using the Filter-Id
option). This is very useful to allow specific rules for some groups.
- VPN connections can be set-up to have a strong authentication (X-Auth).
- Strong Web authentication can be combined with specific firewall rules.
- ...


EXTERNAL PACKAGES AND SOFTWARE USED

    CryptoJS 3.1 (BSD New)
    This product contains software provided by Jeff Mott
    https://code.google.com/p/crypto-js/
   
    FreeRADIUS 2.2.3 for Windows (BSD)
    This product contains software provided by FreeRADIUS team, sfreschi and its contributors.
    http://sourceforge.net/projects/freeradius/

    Mongoose Web Server 3.7 for Windows (GPLv2)
    Cesanta Software
    http://mongoose.googlecode.com/files/mongoose_php_bundle_3.7.zip
   
    phpseclib 0.3.8 (MIT License)
    MMVI Jim Wigginton
    http://phpseclib.sourceforge.net/

    PHP LDAP CLASS FOR MANIPULATING ACTIVE DIRECTORY 2.1 (LGPLv2.1)
    Scott Barnett
    http://adldap.sourceforge.net/

    PHP radius class 1.2.2 (LGPLv3)
    André Liechti
    http://developer.sysco.ch/php/

    PHP Syslog class 1.1.2 (FREE "AS IS")
    André Liechti
    http://developer.sysco.ch/php/

    QRcode image PHP scripts 0.50j (FREE "AS IS")
    Y. Swetake
    http://www.swetake.com/qr/index-e.html

    status_bar.php (2010) (FREE "AS IS")
    dealnews.com, Inc.
    http://brian.moonspot.net/status_bar.php.txt

    TCPDF 6.0.061 (LGPLv3)
    Nicola Asuni
    http://www.tcpdf.org/

    XML Parser Class 1.3.0 (LGPLv3)
    Adam A. Flynn
    http://www.criticaldevelopment.net/xml/

    XPertMailer package 4.0.5 (LGPLv2.1)
    Tanase Laurentiu Iulian
    http://xpertmailer.sourceforge.net/
   
    The source files can be downloaded at http://download.multiotp.net/multiotp.zip

 
MULTIOTP(r) PHP CLASS DOCUMENTATION
===================================
Have a look into the source code if you want to know how to use it,
and you may also check multiotp.cli.header.php which implements the class.


MULTIOTP(r) COMMAND LINE TOOL
=============================
multiotp -help content here