OTPasswd - One-Time Password Authentication System -------------------------------------------------- https://savannah.nongnu.org/projects/otpasswd Updated: 02-Oct-13 (v0.8) INSTALLATION GUIDE Contents ======== 0. Introduction 1. Installation Overview 2. Package Dependencies 3. Installation - Source Package 4. System Configuration 5. User Configuration 6. PAM Configuration 9. Copyright 0. Introduction =============== 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. Short installation steps: $ cmake . -DNLS=1 $ make # make install # Set ChallengeResponseAuthentication and UsePAM to yes in sshd_config # Enable otpasswd in PAM (see examples). You need cmake and libpam-dev. In case of problems you can always check your configuration with: $(which agent_otp) --check-config 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'). By default OTPasswd works in a less intrusive mode called `USER DB'. Changing mode is an essential configuration choice that must be understood well by the system administrator. In the 'USER DB' mode, a user's state is stored in the user's home directory. Because of this, the OTPasswd agent 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. 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. Prefer distribution packages if possible. 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. Packages you need: * cmake * libpam-dev (usually libpam0g-dev) * compilers (build-essential for Debian / Ubuntu) * doxygen 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 -DNLS=1 . # 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' and agent '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' -> /etc/otpasswd/otpasswd.conf Using GLOBAL DB --------------- When using 'GLOBAL DB' mode you should: * Create a unique system user exclusively for OTPasswd, 'otpasswd' is recommended. ** adduser --system --no-create-home otpasswd * Directory /etc/otpasswd should be owned by this selected user. * `agent_otp' and `otpasswd' should be owned by root. * `agent_otp' should be SETUID root. * Set DB option to GLOBAL in otpasswd configuration file. By default, no OTPasswd binaries are SUID. If choosing a non-standard name for user please remember to update config file accordingly. To run test suite you'd best install the otpasswd in the system (before updating PAM configuration) and then run tests. To run them in the source directory you need to compile otpasswd with -DDEBUG and place default config in /etc directory. 4. System Configuration ======================= OTPasswd is configured via the /etc/otpasswd/otpasswd.conf file. Upon initial installation, otpasswd.conf 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. Default file should allow for out-of-the-box usage with USER DB mode. 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. 5. 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. 6. PAM Configuration ==================== Debian package comes with a PAM otpasswd profile in which after installation in can be easily enabled and disabled using `pam-auth-update' command. This method of PAM installation is preferred on all systems which support it. To enable OTPasswd use with SSH, pam_otpasswd must be called inside the `auth' PAM stack, right after the default pam_unix module. An example pam.d configuration file is in . One can move otpasswd-login example to /etc/pam.d directory and set it up for ssh instead of the original authentication stack by substituting: From: auth include system-remote-login to: auth include otpasswd-login Consult the section titled 'About PAM' in the document for more detailed information. 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. 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. 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. OTPasswd also works with xscreensaver. 9. Copyright ============ Copyright (c) 2010-2013 Tomasz bla Fortuna This file is part of OTPasswd. See README file for licensing information. ###