Location: PHPKode > scripts > Multi-OTP PHP class > readme.txt
MultiOTP is a GNU LGPL implementation of a strong two-factor authentication PHP class

The MultiOTP class supports currently the following algorithms:
- mOTP (http://motp.sourceforge.net)
- OATH/HOTP RFC 4226 (http://www.ietf.org/rfc/rfc4226.txt)
- OATH/TOTP HOTPTimeBased RFC 4226 extension

(c) 2010 SysCo systemes de communication sa
http://www.multiotp.net

Current build: 3.0.0 (2010-09-02)

Donation are always welcome! Please check http://www.multiotp.net
and you will find the magic button ;-)


What's new in 3.x releases

  Now it is possible to import PSKC Algorithm Profiles containing tokens
  definition for TOTP and HOTP algorithm. Thus, creating a user and attributing
  a token is easier. You only need to give the name of the user, the token id
  and the desired pin code of the user.
  
  The multiotp-database-format flat file has been enhanced to version 3.
  Regular attributes are written attribute=value and encrypted attributes are
  now written encrypted_attribute:=encrypted_value. If you want to set a new pin
  for a user, you can open the file of the user and change the line
  user_pin:=ACQwJw== by user_pin=1234. The new value will be correctly read the
  next time, and encrypted again the next time something is written in the file.

  In debug mode, the command line version is now returning a text information
  after the exit code.


Change Log
  2010-09-02 3.0.0  SysCo/al Adding tokens handling support, including importing XML tokens definition file
                             Enhanced flat database file format (multiotp 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 "compiled" Windows command line
  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 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:
 - multiotp.class.php      : the main file, it is the class itself
 - multiotp.cli.header.php : header file to be merged with the class for a single file command line tool
 - multiotp.php            : command line tool (which is the merge of the header and the class)
 - multiotp.exe            : command line tool for Windows with embedded PHP
                             (signed with our certificate)
                             if you are using the command line tool for Windows,
                             be sure that the file multiotp.php is removed from
                             the directory, otherwise conflict may appears
 - php-embed.ini           : file used by the command line tool for Windows with external DLL
 - php5ts.dll              : file used by the command line tool for Windows with external DLL
 - php_win32std.dll        : file used by the command line tool for Windows with external DLL
 - php_bcompiler.dll       : file used by the command line tool for Windows with external DLL
 - multiotp.msi            : Windows MSI package that will unpack multiotp.exe and the
                             five necessary files for the external DLL version
 - checkmultiotp.cmd       : Windows script to validate the HOTP implementation

 
When can I use this package ?

    The MultiOTP 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) or
    finally coupled with a radius server like TekRADIUS or FreeRADIUS to be
    able to have a strong authentication through the RADIUS protocol for
    external devices like firewalls for example.

    So if you decide to have strong 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 intranet
    websites and even your Windows login!
    
    Inside a company, you will probably use MultiOTP with a radius server. 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.
    If you are running under Linux or (other *nix brands), FreeRADIUS will do
    the job (http://freeradius.org).
    
    After the selected radius server is installed, copy the MultiOTP command
    line tool somewhere and add the necessary configuration into your radius
    server like this:

    Using multiotp 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%
  
    Using multiotp with FreeRADIUS under Linux

      Define a DEFAULT entry in the /etc/freeradius/users file like this:
      DEFAULT Auth-Type = Accept
      Exec-Program-Wait = "/usr/local/bin/multiotp.php %{User-Name} %{User-Password}",
      Fall-Through = Yes,
      Reply-Message = "Hello, %{User-Name}"

    Now, you will have to select token generators for your users. Currently,
    the library supports the following algorithms: mOTP, TOTP and HOTP.

      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 TOTP or HOTP support
        Check the various markets of your devices, for examples:
        oathtoken for iPhone :    http://code.google.com/p/oathtoken/
        androidtoken for Android: http://code.google.com/p/androidtoken/
        ...

      Hardware tokens
        Feitian provides OATH compliant TOTP and HOTP tokens
         - OTP c100: OATH/HOTP, 6 digits
         - OTP c200: OATH/TOTP, 6 digits, 60 seconds time interval
        ZyXEL OTP (rebranded Authenex A-Key 3600) provides HOTP OATH compliant tokens
         - ZyWALL OTP / A-Key 3600: OATH/HOTP, 6 digits
        Seamoon provides OATH compliant TOTP tokens
         - Seamoon KingKey: OATH/TOTP, 6 digits, 60 seconds time interval
        ...
    
    Install the different tokens and register one token per user using the command line tool.
        multiotp -log -create user1 mOTP 004f5a158bca349a7f23 1234 6 10
        multiotp -log -create user2 mOTP 3459a7f154f47afb5790 5678 6 10
        (...)
        
    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 Radius Credential Provider from LSE Experts (http://www.lsexperts.de)

        
MultiOTP class documentation

    Have a look into the source code if you want to know more about how to use
    it, and check also multiotp.cli.header.php which implements the class.


multiotp command line tool 
  
    multiotp handle and check if the token of a user is correct, based on a specified
    algorithm (currently Mobile-OTP (http://motp.sf.net), OATH/HOTP (RFC 4226)
    and OATH/TOTP (HOTPTimeBased RFC 4226 extension) are implemented).

    If you are using the command line tool for Windows, be sure that the file
    multiotp.php is removed from the directory, otherwise conflict may appears.

    If a token is locked (return code 24), you can resync the token to unlock.

    It will return 0 for a correct token, or an error code (11-99) otherwise.

    Usage:
     multiotp [-log] -import-xml xml_tokens_definition_file.xml
     multiotp [-log] -create [-prefix-pin] user algo seed pin digits [pos|interval]
     multiotp [-log] -create -token-id [-prefix-pin] user token-id pin
     multiotp [-log] -resync [-status] user token1 token2 (two consecutive tokens)
     multiotp [-log] -update-pin user pin
     multiotp [-log] [-debug] user token
     multiotp -delete user

     token-id: id of the previously imported token to attribute to the user
     user:     name of the user (should be the account name)
     algo:     available algorithms are mOTP, HOTP and TOTP
     seed:     hexadecimal seed of the token
     pin:      private pin code of the user
     digits:   number of digits given by the token
     pos:      for HOTP algorithm, position of the next awaited event
     interval: for mOTP and TOTP algorithms, token interval time in seconds

    Options:
     -help        Display this help page
     -version     Display the current version
     -prefix-pin  The pin and the token must be typed merged by the user
                  (if you pin is 1234 and your token displays 5556677,
                   you will have to type 1234556677)
     -status      Display a status bar during resynchronization
     -log         Log operation in the log file (in the \log subdirectory)
     -debug       Enhanced log information, code result on screen

    Examples:
     multiotp -help
     multiotp -log -create jimmy mOTP 004f5a158bca13984d349a7f23 1234 6 10
     multiotp -create -prefix-pin alan TOTP 3683453456769abc3452 2233 6 60
     multiotp -create -prefix-pin anna TOTP 56821bac24fbd2343393 4455 6 30
     multiotp -create -prefix-pin john HOTP 31323334353637383930 5678 6 137
     multiotp -create -token-id -prefix-pin rick 2010090201901 2345
     multiotp -resync -status anna 4455487352 4455983513
     multiotp -resync john 5678456789 5678345231
     multiotp -update-pin alan 4417
     multiotp -debug -log jimmy ea2315
     multiotp -log anna 546078
     multiotp john 5678124578


Return codes

  0 OK: Token accepted
 11 INFO: User successfully created or updated
 12 INFO: User successfully deleted
 13 INFO: User PIN code successfully changed
 14 INFO: Token has been resynchronized successfully
 15 INFO: XML tokens definition file successfully imported
 19 INFO: Requested operation successfully done
 21 ERROR: User doesn't exist
 22 ERROR: User already exists
 23 ERROR: Invalid algorithm
 24 ERROR: User locked (too many tries)
 25 ERROR: User delayed (too many tries, but still a hope in a few minutes)
 26 ERROR: The time based token has already been used
 27 ERROR: Resynchronization of the token has failed
 28 ERROR: Unable to write the changes in the file
 29 ERROR: Token doesn't exist
 30 ERROR: At least one parameter is missing
 31 ERROR: XML tokens definition file doesn't exist
 32 ERROR: XML tokens definition file not successfully imported
 99 ERROR: Authentication failed (and other possible unknown errors)

    
If you need specific developments concerning strong authentication,
do not hesistate to contact us per email at hide@address.com
Return current item: Multi-OTP PHP class