pam_sotp user's manual ====================== pam_sotp version 0.1. October 2004 http://www.cavecanen.org/cs/projects/pam_sotp/ 1. Introduction. Features ========================= pam_sotp provides simple one time password support to PAM, the pluggable authentication modules. The usage scenario of pam_sotp is the following The user is provided by a list of one time passwords. Each time the user has to login to the system it is required to enter one of the passwords, which will become invalid after being entered. This list of one time passwords (OTP list) is typically stored in print form 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 control if each user has rights to re-generate its OTP list when all the OTPs has been used. pam_sotp can be configured to: a) Deny regeneration of the OTP list. When the user runs out of passwords he should have to contact the administrator in order to get a new OTP list b) Allow regeneration of passwords under parameters (password length, number of passwords, charset, etc...) fixed by the system administrator. The user has to use the 'otppasswd' utility c) Allow regeneration of passwords allowing also the user to specify the generation parameters. The 'genotbdb' utility, provided with pam_sotp, handles this. 2. Configuring pam_sotp ======================= 2.1 Auth databases ------------------ The first thing you should do is to create the directory /etc/sotp. This is were all the authentication information (i.e.: the passwords) is stored. Under this directory pam_sotp will manage several authentication databases, one for each used you want to enable OTP for. Each database is in fact a binary file with the user's login name as its file name. Each database holds all the information required to authenticate the user, as well as some other configuration parameters. This means that the passwords are stored there, although by default they are hashed using the MD5 algorithm. Two bytes of 'salt' are used when hashing the password in order to disturb cracking efforts. Creation of authentication databases is handled by the 'genotpdb' utility (by default installed in /usr/local/sbin). This utility accepts the following options: -r Allow the user to re-generate his/hers OTP list. A 'yes' value will mean that the user will be able to regenerate his/hers OTP list with the 'otppasswd' command. The default for this option is 'no' -s path If the user is able to re-generate his/hers OTP list (-r yes) the system will need where to write the file containing the clear-text passwords. A typical value for this option would be /home/user/otplist This file will be created with 0700 file permissions, although the user is encouraged to print it as soon as possible and then wipe the file. The default for this option is './secret' -h Hash algorithm used for passwords in the authentication database. 'plain' means that the passwords will not be hashed and thus will be stored in plain text, which is security risk. The default for this option is 'md5' -n number Number of passwords to generate. The default for this option is '20' -p prefix Prefix for the password list. The default is no prefix. -l length Length of the generated passwords. The default is 5 -c charset Charset used to generate the passwords. The default is '0123456789' (numbers). genotp also expects a filename were the authentication database will be stored. So, for example, if you want to generate an authentication database for the user susan, with 50 6-char passwords composed by numbers and some punctuation signs, with the prefix 'squish', and allow susan to regenerate this password list using the 'otppasswd' command, you will have to issue the following command: /usr/local/sbin/genotpdb -r yes -s /home/susan/otplist -n 50 -l 60 -p squish -l 6 -c 0123456789-:. /etc/sotp/susan The file /home/susan/otplist will contain the OTP list: [01] 78:88- [02] .91-9. [03] -:.:39 [04] 46670. .... 2.2 PAM configuration --------------------- The last thing to configure in order to enable SOTP is PAM. The pam_sotp.so pam module provides the auth and password features. Here is the list of the options accepted by the pam_sotp pam module * Global options auth_dir= Path to the SOTP authentication directory * Options related to the auth module prompt_number= Include the password number in the prompt * Options related to the password module This options apply when generating a new password set with the otppasswd utility gen_length= Length of the passwords generated gen_chars= Charset used when generating passwords gen_prefix= Prefix used when generating passwords gen_hash_type= Algorithm used to hash the passwords gen_count= Number of passwords to generate Example: We want to configure the login service with SOTP support. We also want to let in other non-SOTP. 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 authdir=/etc/sotp 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: You can also configure the password service in PAM, so SOTP users can regenerate (if allowed) their OTP list. This can be done with the following configuration in /etc/pam.d/otppasswd # Example PAM configuration file for the otppasswd utility password sufficient pam_sotp.so gen_length=4 gen_count=20 otppasswd will authenticate the user asking for a one time password. This means that users with no unused one time passwords in their database won't be able to regenerate their OTP list. 2.3 Full-featured password generation ------------------------------------- If you want to enable full featured password generation to an user (i.e: he/she can specify all the password generation parameters seen above) just chown his/hers auth database to this user. The user will then be able to use the genotpdb utility to generate the password list. 3. Disclaimer, contact information, etc... ========================================== I said it before, but I will repeat it again: 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 [NOSPAM_AT_NOSPAM] cavecanen [DOT] org. They will be very welcome.