OTPasswd - One-Time Password Authentication System -------------------------------------------------- https://savannah.nongnu.org/projects/otpasswd Updated: 15-Sep-10 (v0.7beta) INSTALLATION GUIDE Contents ======== 0. Introduction 1. Installation Overview 2. Package Dependencies 3. Installation - Source Package 4. Installation - Binary Package 5. System Configuration 6. User Configuration 7. PAM Configuration - General 8. PAM Configuration - OpenSSH 9. PAM Configuration - su 10. Copyright 0. Introduction =============== A few of the more important issues related to OTPasswd installation are worth noting, however. OTPasswd can easily be configured to work in conjunction with any text-based PAM-aware application, such as sudo, su, ftp, or any standard *nix console login. The typical use case for OTPasswd by far, however, is to secure non-publickey SSH logins, which is what will be described in this section. Operational Mode ---------------- OTPasswd is able to run in two slightly different modes, which are distinguished by the location of the stored user data (called `the state'). This is a deliberate and essential configuration choice that must be made by the system administrator. Each choice carries with it certain consequences with respect to system security. In the 'USER DB' mode, a user's state is stored in the user's home directory. Because of this, the OTPasswd utility does not need escalated SUID privileges to access and modify the user's state. As a consequence, however, the user's data may be changed by the user at will. This prevents OTPasswd from effectively enforcing various security policies. Among other things, it permits a user to create a situation where one-time passwords (passcodes) are reused, which could be interpreted as effectively defeating the entire point behind OTP authentication. It should be noted that if the system user-base is trusted, competent, and conversant in IT security issues, this may not be a relevant concern. In any event, the USER DB mode effectively implies that OTPasswd security is optional. In the second operational mode, the 'GLOBAL DB' mode, every user's state is stored in a single database under system control. This operational mode may use a number of backend database interfaces, such as a flat-file, usually /etc/otpasswd/otshadow, or (not yet implemented) LDAP/MySQL database. The user has no read/write access to the configuration and state data, and hence the system is capable of enforcing OTPasswd security policies. As an example, GLOBAL DB mode ensures that passcodes are never reused. This mode of operation does require that the OTPasswd agent be installed as SUID root, which may be viewed by some as being undesirable since this may present a security exposure in its own right. It should be stressed, however, that the OTPasswd software was written in a manner observant of secure coding practices, and while the agent is installed SUID root, it merely uses these privileges to read its configuration files and then it promptly drops the root privileges. Or, put another way, the OTPasswd agent only holds root privileges for a brief time during which it never processes any user input. The benefit of this approach is that the GLOBAL DB mode allows the system administrator to choose whether OTPasswd security is optional, or mandatory. To even increase security the OTPasswd console utility was split into two executables: utility (otpasswd) and agent (agent_otp). Only the latter is given the root privileges, but it's completely bereft of any user interface, which is implemented in the utility. This division ensures the user won't be able to suspend execution of the agent while it has locked the global database. It is important to note that this is the first critical decision that a system administrator must make in configuring OTPasswd. No default is provided for this choice, and OTPasswd will not operate until the operational mode has been configured. 1. Installation Overview ======================== To compile, install, and configure OTPasswd to work with SSH you must complete the following steps: 0. Have all required dependencies 1. Install the package 2. Tweak OTPasswd configuration 3. Generate a user key (and print at least one passcard) 4. Enable OTPasswd in /etc/pam.d 5. Configure SSH to use PAM authentication Be aware that if OTPasswd is installed over an SSH connection, it is possible to inadvertently become "locked-out". This can happen if OTPasswd is enabled for SSH logins prior to having generated an initial set of passcodes, which in turn requires the generation of a OTPasswd user key. The installation procedure outlined above is intended to minimize the likelihood that this will happen. 2. Package Dependencies ======================= OTPasswd may be installed either through compilation from source, or if available, from a pre-compiled binary package. OTPasswd has no external runtime dependencies except for PAM. Additional packages are required when OTPasswd is compiled from source, namely, the CMake cross-platform build system, as well as the corresponding development packages for PAM. To generate documentation of internal API one is required to install Doxygen. All of these packages should be available in your distribution's repositories. The following table provides a number of known configurations under which OTPasswd is known to compile and run. This table is not intended to be comprehensive, but merely to serve as a point of reference. Distribution Type Package Comment --------------- ------- ------------ --------------------- Gentoo ArchLinux Debian Ubuntu 8.04 Ubuntu 10.04 Runtime libpam0g Build cmake build-essential libpam-dev To ensure you have all required dependencies when using either Debian or Ubuntu you may want to use command: # apt-get install cmake libpam-dev build-essential Future versions of OTPasswd may optionally use MySQL and LDAP. It is also possible that a GNU Autotools build system will eventually either replace, or serve as an alternative to CMake. These options may therefore introduce a different set of package dependencies. 3. Installation (Source Package) ================================ Check to see if a pre-compiled binary package is available for OTPasswd in your distribution's package manager. If so, then install it as you would any other package. Otherwise, you will need to compile OTPasswd from source, as follows: $ cd otpasswd $ cmake . # Generate makefiles (You can add -DDEBUG=1) $ make # Compile everything On Linux distributions you can install OTPasswd into the system by running as root a following command: $ make install If you would prefer to perform the final installation step manually, then instead of using 'make install' you can copy the following files: a) PAM module 'pam_otpasswd.so' Linux: /lib/security/ FreeBSD: /usr/lib b) Utility program 'otpasswd' Linux: /usr/bin/ FreeBSD: /usr/local/bin/ c) OTP agent executable 'otp_agent' Linux: /usr/bin FreeBSD: /usr/local/bin/ c) PAM configuration Copy into /etc/pam.d one of files: Linux: example/otpasswd-login FreeBSD: example/otpasswd-login_FreeBSD d) OTPasswd configuration 'example/otpasswd.conf.dist' -> /etc/otpasswd/otpasswd.conf When using 'GLOBAL DB' mode you should create a unique system user exclusively for OTPasswd, 'otpasswd' is recommended. Directory /etc/otpasswd should be owned by this user and otpasswd agent (not utility) binary should be SUID-root. By default, no OTPasswd binaries are SUID. If choosing a non-standard name for user please remember to update config file accordingly. 4. Installation (Binary Package) ================================ Currently we're working on getting OTPasswd into sunrise repository of Gentoo. You can get .ebuild and build otpasswd for Gentoo yourself. 5. System Configuration ======================= OTPasswd is configured via the /etc/otpasswd/otpasswd.conf file. Upon initial installation, otpasswd.conf.dist located in this directory will contain a template of all valid configuration options along with copious commentary. A pristine version of this file should be available in the OTPasswd package documentation directory of your system's /usr/share hierarchy. You should copy the otpasswd.conf.dist to otpasswd.conf and proceed with its configuration. ** Configure/select user ** adduser --system --no-create-home otpasswd The most important configuration setting is the "DB" option. The DB option can be set as follows: DB=user ------- In this mode, OTPasswd stores user state information in the user's home directory. As a result, the OTPasswd agent doesn't require any SUID privilege, and can be run in the user's security context. Note that even if the agent is installed with the SUID flag, it will drop privileges immediately after reading the configuration file. The major disadvantage of this mode is that since the user has complete access to his state file, it is impossible to guarantee all aspects of system security policy compliance. Among other things, a user could cause passcode recycling/reuse through manipulation of state file information. DB=global --------- This mode uses a system-wide configuration database. The default location for this database is /etc/otpasswd/otshadow. The database file and directory which contains it must be owned by a special user created for OTPasswd use, and it MUST not be readable for normal users. Since all critical data is under system control, system security policies can be enforced. However, the OTPasswd agent must be granted SUID privilege to the OTPasswd UID to enable access to this database on the user's behalf. DB=mysql -------- (Not currently implemented) The user state information is stored in a MySQL database. The database access password is stored in the OTPasswd configuration file /etc/otpasswd/otpasswd.conf, so this file must be readable only by the special OTPasswd UID described above. The OTPasswd utility must be run with SUID privilege to gain access the configuration file, however privileges are dropped promptly after reading the file. DB=ldap ------- (Not currently implemented) The user state information is stored in an LDAP database. See the DB=mysql description above for more information. 6. User Configuration ===================== Generate OTPasswd Key & Print Passcard ----------------------------------------- To use OTPasswd, a user is required to have a cryptographic key, which is then used to generate the user's passcodes. To generate this key, ensure that you are logged in as the user for whom you want to create the key, then issue the following command: $ otpasswd --key An administrator may generate a key for any user, as follows: $ otpasswd --key --user tux Be aware that OTPasswd, by default, generates a key which is not compatible with the PPPv3.1 specification. If you would like to retain compatibility with the specification and thereby also retain interoperability with other PPPv3 applications, you may either change the default behavior by modifying the SALT_DEF parameter in the otpasswd.conf configuration file, or add the --config salt=off flag during key generation as in the following example: $ otpasswd --config salt=off --key You may also combine other flags with key generation (-k), to set contact or label like this: $ otpasswd -c label=Home -c contact=012689 -c alphabet=2 -c codelength=6 -k Note: As mentioned above, if OTPasswd is being configured over an SSH session, it is conceivable that one can lose one's ability to log back in after any key change since one will not yet have any valid passcodes. Because of this, the OTPasswd utility will immediately print a passcard upon key generation. The prudent user would be wise to either print this passcard, or minimally jot down the first few passcodes. You have been warned. 7. PAM Configuration - General ============================== To enable OTPasswd use with SSH, one line must be changed in the SSH daemon's PAM configuration '/etc/pam.d/sshd', as follows: From: auth include system-remote-login to: auth include otpasswd-login Consult the section titled 'About PAM' in the document for more detailed information. Keep in mind that /etc/pam.d/otpasswd-login file must exist. 8. PAM Configuration - OpenSSH ============================== While it would technically also be possible for OTPasswd to be used in GUI-based PAM applications, as one might find in the KDE or Gnome desktops, the necessary GUI layers do not presently exist. The typical use case for OTPasswd by far, however, is to secure non-publickey SSH logins, which is what will be described in this section. Configure SSHD to Use PAM Authentication ------------------------------------------- The OpenSSH daemon's (SSHD) configuration is usually located in the file '/etc/ssh/sshd_config'. Ensure that this file contains the following two lines: ChallengeResponseAuthentication yes UsePAM yes It is entirely possible that these two configuration settings are already enabled, and that no modification is required. If the file must be modified, it should contain no other uncommented instances of either keyword. Note that it is always advisable to make a backup copy of configuration files prior to making any changes. 9. PAM Configuration - su ========================= As an example of the flexibility that OTPasswd is able to offer by using the PAM (Pluggable Authentication Modules) Library, once OTPasswd has been configured it is easy to incorporate OTP authentication with other PAM-aware applications. The su(1) command is easily secured by OTPasswd by modifying its PAM configuration, as is described in this section. (FIXME) 10. Copyright ============= Copyright (c) 2010 Tomasz bla Fortuna This file is part of OTPasswd. OTPasswd is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version. OTPasswd 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 General Public License for more details. You should have received a copy of the GNU General Public License along with OTPasswd. If not, see . ###