3. Configuration
3.1. Creating a new authentication database
pam_sotp stores authentication information in authentication databases. Each authentication database contains the information used to authenticate one user. Authentication databases are grouped into authentication directories. Each pam_sotp-enabled PAM service will authenticate against an authentication directory (by default /etc/sotp, but this can be changed for each service). If the user to be authenticated doesn't have an authentication database under the inspected authentication directory, pam_sotp refuses to authenticate him/her, giving control back to the PAM module stack.
The support utilities for pam_sotp have been merged into one utility: otppasswd. Once you have installed pam_sotp all you have to do to create a new authentication databasefor your user is to run the otppasswd command. otppasswd usage is straightforward:
$ otppasswd -h otppasswd v.0.3.1 (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
otppasswd will overwrite any previous database that the user might have in the authentication directory. This means that you can use otppasswd to generate a new OTP list when you are near to run out of passwords. Keep in mind that since otppasswd overwrites the previous database your previous OTP list won't be valid anymore.
3.2. Configuring the pam_sotp module
The pam_sotp.so module accepts the following options:
auth_dir=path Path to the SOTP authentication directory. If not specified the default (specified with the configure script when pam_sotp was compiled, or /etc/sotp if none was specified) will be used
fail_delay=nsecs Plan a delay of at least nsecs 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=nsecs Set the password lifespan value for this service.
3.2.1. 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:
- The wrong OTP was introduced
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:
3.3. Other issues
3.3.1. Password lifespan
With the options pw_lifespan in the module configuration and -t 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 amount of time an older password will remain valid is calculated as the minimum of the value specified in /etc/pam.d/service configuration file and the value specified with otppasswd when the user database was created. This means that specifying a value of zero 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 behavior).