pam_sotp 0.3.0 manual

0. What's new

1. Introduction. Features

pam_sotp provides simple one time password support to PAM, the pluggable authentication modules.

1.1 Usage scenario

The user is provided with a list of one time passwords. Each time the user wants to authenticate against an SOTP-enabled service he or she will be asked to enter an specific password of the list. In case of successful authentication that password will become invalid or valid only for a configured period of time (depending on how the service was configured) and the service will ask for a different password next time.

This list of one time passwords (OTP list) is typically stored in print form and stored in the user's wallet or in electronic form in the user's PDA or cell phone.

Optionally passwords can be configured with a 'prefix', which is another password which the user has to memorize and which has to be written as a prefix of the requested one time password. The prefix acts as a security measure in case that the OTP list is lost or stolen from the user.

The system administrator can configure a service in such a way that entered passwords are valid for a configured period of time. This feature, which we will call password lifespan, is useful when the application requesting the authentication will have to authenticate several more times in a period of time (for example, a webmail application authenticating against the IMAP server).

2. Configuring pam_sotp

2.1 Creating a new authentication database

$ otppasswd -h
otppasswd v.0.3  (C) 2004 Pedro Diaz (sotp@cavecanen.org)

Usage: otppasswd [OPTIONS]

Available options:
  -o file           File used to store the OTP list
  -n number         Number of passwords to generate (default: 20)
  -p prefix         Prefix to add in each generated password (default: No prefix)
  -l length         Length of each generated password (default: 5)
  -t lifespan       Built-in password lifespan, in seconds (default: 0)
  -e days           Make the auth database expire in x days (default: don't expire)
  -c charset        Charset used when generating passwords (default: 0123456789)
  -d authdir        Authentication directory (default: /etc/sotp/)
  -P                Pretty-print the OTP list
  -h                Show this help message

2.2 PAM configuration

The last thing to configure in order to enable SOTP is PAM. The pam_sotp.so PAM module now only provides auth services.

Options available

• auth_dir=<string>
  Path to the SOTP authentication directory. If not specified the default will be used


• fail_delay=<number>
  Plan a delay of at least number seconds after a failed authentication. The actual number of seconds of waiting depends on PAM and the module stack.

• prompt_number=<yes|no>
  Include the password number in the prompt


• pw_lifespan=<number>
  Set the password lifespan value for this service. Take a look at the 2.3 section to see how password lifespan works on pam_sotp 0.3

Example

We want to configure the login service with SOTP support. We also want to let in other non-SOTP users. SOTP users must also be able to log-in with their regular password.

The file /etc/pam.d/login will look something like this:

auth sufficient pam_sotp.so prompt_number=yes 
account required        pam_unix.so

SOTP users (the ones with an auth database in /etc/sotp) will be asked for an OTP. If the OTP is wrong they will be asked for their regular password:

	odiel:~# telnet localhost
	Trying 127.0.0.1...
	Connected to localhost.localdomain.
	Escape character is '^]'.
	Debian GNU/Linux 3.1 odiel
	odiel login: susan

	One time password [01]:
	Password:

Non-SOTP users won't notice difference:

	odiel:~# telnet localhost
	Trying 127.0.0.1...

	Connected to localhost.localdomain.
	Escape character is '^]'.
	Debian GNU/Linux 3.1 odiel
	odiel login: pdiaz
	Password:

2.3 Other issues

Password lifespan

With the options pw_lifespan=<number> in the module configuration and -t <number> in otppasswd you can configure pam_sotp to authenticate a service with limited time passwords. This basically means that pam_sotp will handle authentication in the same way as before but with the following additional feature: an used password will remain valid for some time after its first use. Of course, the prompted password will be also valid.

The actual ammount of time an older password will remain valid is calculated as the minimum of the value specified in the pam.d configuration file and the value specified with otppasswd when you created the database. This means that specifying a value of cero in either of these places will disable password lifespan for that pam service or authentication database.

Limited Time Passwords are useful for using pam_sotp with software that requires several authentications against a service in a short period of time, such as some webmail systems (Squirrelmail has this behaviour).

3. Disclaimer, contact information, etc...

pam_sotp is not yet ready for production use. This is alpha-quality code, it may be full of remote holes (I hope not ;-). Having said that, I've been using pam_sotp for accessing my webmail for some time and I didn't found any problems.

This is my first PAM module. I've done my best to comply with the standards recommended by the PAM Module Writers' Manual. If you have experience writing PAM modules and you have any suggestions about the code, please contact me!

Suggestions, patches and code contributions can be directed to sotp [_AT_] cavecanen [_DOT_] org. They will be very welcome.