
PAM module for Mobile OTP
--------------------------------

Mobile OTP is a solution for strong two factor authentication.
See http://motp.sourceforge.net/ for more details.



PLATFORMS
~~~~~~~~~

The PAM module for Mobile OTP was developed for
- Linux SuSE 7
- Solaris 8

It is also known to work with 
- newer Linux versions
- Solaris 9
- FreeBSD



INSTALLATION
~~~~~~~~~~~~

Supported module types are "auth", "password" and "account".

For installation you must:

     1. Think about what you are going to do. Especially read the
	documentation about Mobile OTP. And you should know what PAM
	is and how it works ...

     2. Copy sample configuration file "motp.conf" into /etc/security.
	Set file permission to rw-------.
	Edit the configuration file, you may use "motp-manager" for this.
	For creating secrets press #**# on your mobile phone.

     3. Insert lines like
		auth  sufficient /lib/security/pam_mobile_otp.so not_set_pass
		password required /lib/security/pam_mobile_otp.so debug
	and
		account	required /lib/security/pam_mobile_otp.so
	into your pam config file, e. g. /etc/pam.d/login

     4. Copy pam_mobile_otp.so to /lib/security.

     5. Create the directory /var/cache/motp.

     6. Try to log in with Mobile OTP _before_ finishing your actual session.



CONFIGURATION
~~~~~~~~~~~~~

Recognized options are:

   auth:
   	users=<filename>
		for setting a different configuration file, default is 
		/etc/security/motp.conf

	cache=<dirname>
		for using a different cache directory, default is 
		/var/cache/motp

	maxdiff=<seconds>
		for setting the maximum time range in which a passcode
		is accepted. 
		Default is 360 (seconds). That means that clocks may
		differ 3 minutes.

	maxtries=<number>
		sets the number of unsuccessful authentication attempts
		before user is locked.
		Default ist 5.

	debug

	no_warn

	use_first_pass
		if set, the module does not ask for the passcode, but
		uses the password given earlier to an other module.

	try_first_pass
		if set, the module only asks for a passcode, if password
		that was set earlier is not the correct passcode.

	not_set_pass
		passcode will not be set as password for next modules.


   password:
	users=<filename>
		for setting a different configuration file,
		default is /etc/security/motp.conf

	debug

	no_warn


   account: Will unlock user due to retries-exceeded lock-out.
	cache=<dirname>
		for using a different cache directory, default is 
		/var/cache/motp

	debug

	no_warn



KNOWN LIMITATIONS
~~~~~~~~~~~~~~~~~

- The PAM module only supports PINs that have 4 digits. 
  If you want to support more than 4 digits, you may increase this maximum 
  by changing the definition in source code: 
	#define LEN_PIN 4
  The maximum of 4 digits for PINs is not increased generally, because of 
  the module's passwd support. If a user changes PIN, it is overwritten
  in the configuration file motp.conf directly. This implementation means, 
  that all PINs must have an identical length.
  The authentication part supports PINs with different length, i.e. you may
  increase the PIN length to say 8 bytes and use the PAM module without any
  problems, as long as you change motp.conf manually and don't use the 
  passwd functionality of the PAM module.

- Functions are not thread safe.

- User must not type in old PIN when calling passwd. You may configure PAM
  instead.


Any comments, bug reports or questions (to the module only) to
<sebastian.korff@web.de>



LICENSE
~~~~~~~

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU Library General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.

This software is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Library General Public License for more details.

This program uses an implemenation of MD5 by Ulrich Drepper that
was also released under the terms of the GPL

