OTPasswd - One-Time Password Authentication System -------------------------------------------------- https://savannah.nongnu.org/projects/otpasswd Updated: 15-Sep-10 (v0.7beta) README Contents ======== 0. Package Status 1. Motivation 2. Introduction 3. Package Features 4. Security Advisory 5. Installation 6. Demo (Screenshot!) 7. Documentation 8. Contact Information 9. History 10. Licensing 0. Package Status ================= OTPasswd is under development. In the ChangeLog there's a list of things I'd like to implement before publishing the package as version 1.0. Most features currently work (as of v0.7) but, of course, testing is still required. Think of this as a beta software. It is a goal of OTPasswd development to create a source package which can readily be compiled on a variety of *nix platforms, including Linux, BSD, Mac OSX, and Solaris. In addition, it is hoped that pre-compiled binary packages can be maintained for major Linux distributions, as well as a Gentoo ebuild. View the most recent version of this document on the web at: http://git.savannah.gnu.org/cgit/otpasswd.git/plain/README 1. Motivation ============= FIXME: To be written. 2. Introduction =============== A one-time password (OTP) is a password that is only valid for a single login session or transaction (normally used along with a normal static password). Using an OTP reduces the risks associated with logging into your system from insecure (eg, key logged) workstations. The OTPasswd package consists of three primary components, a user utility, agent which performs operation on behalf of the utility, and a PAM module (Pluggable Authentication Module). The utility allows the management of a user's interaction with the OTPasswd system. Its primary functions are to generate the user's cryptographic key, manage options affecting OTPasswd behavior, and to print passcards with one-time passwords. The user's OTPasswd configuration is known as the user's "state", and can either be stored in the user's home directory or in a system-wide database. User never interacts directly with the agent. Instead utility calls agent functions each time user runs utility. It's existance is solely due to security. The third primary component of the OTPasswd system, the PAM module, enables "PAM aware" applications, such as OpenSSH, to do OTP authentications using the user's OTPasswd "state" information. OTPasswd is written in C (C99) and implements an OTP system as described by Steve Gibson's "Perfect Paper Passwords" specification. An excellent description may be found at: . While OTPasswd is designed to be completely compliant with the PPPv3.1 specification, it does optionally extend the specification by allowing the use of a cryptographic "salt" to the passcode counter. OTPasswd does not support earlier versions of the PPP specification. 3. Package Features =================== Current: * Use of Pluggable Authentication Module (PAM) allows great flexibility * Rijndael (AES) cipher is modern, robust, and efficient * User state information may be maintained in global DB, or in user home * Compatible with the well-documented PPP (Perfect Paper Passwords) standard * Interoperable with other PPP-compliant applications * Capable of enforcing system OTP security policy decisions * User-selectable passcode entry alphabet to suit language, or keyboard * High entropy passcodes for rapid entry, reducing Over-The-Shoulder attacks * Passcards may be generated in either plain ASCII or LaTeX * Secure locking of state files to resolve race conditions * Many user options: display entered passcodes, passcode length, etc. * Many sysadmin options: enforcement or overriding user options, etc. * Warnings issued when user passcard supply is running low * Support for cryptographic salt to increase attack resistance (optional) * Designed and written with emphasis on secure code * Out-of-band passcode transmission with customizable scripts (SMS, IM, etc) Planned: * Wide variety of supported platforms (Linux, Unix, BSD, Solaris) * Comprehensive documentation * Pre-compiled binary packages for major distributions; Also, Gentoo ebuild * Flexible layout of printed passcards through customizable scripts * Flexible choice of DB backend, including flat file, MySQL & LDAP 4. Security Advisory ==================== It is very important that the user has a good understanding of the following issues related to any system security software: A. The intent and purpose of the design B. The limitations of the implementation C. The points of vulnerability D. The general principles of operation The user is encouraged to read the documentation provided in the directory of this package. In particular, the document covers a number of security concerns related to this package. The user is also encouraged to read the information on the GRC website (above) regarding PPP. The user is also advised to take the following two warnings to heart: CAUTION #1. OTPasswd is NOT designed to replace standard system passwords, rather, it is intended to provide a "second factor" to a "first factor" authentication system. Do not use it as your only authentication system. Really. CAUTION #2. No OTP authentication system can protect you if you have not first authenticated the endpoint of your communication channel. Prior to providing your password, it is essential to authenticate the host. Failure to do so exposes you to the risk of a Man-In-The-Middle attack. In other words: use SSH and validate the host key fingerprint! 5. Installation =============== OTPasswd installation is covered in the INSTALLATION GUIDE, included with this distribution in the INSTALL file. A few of the more important issues related to OTPasswd installation are worth noting, however. Operational Mode ---------------- OTPasswd is able to run in two slightly different modes, which are distinguished by the location of the stored user state configuration. 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 configuration 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 configuration. As a consequence, however, the user's configuration 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 configuration 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 in the /etc filesystem hierarchy, an LDAP database, or a MySQL database. The user has no read/write access to the configuration 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. 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. 6. Demo (Screenshot!) ===================== Everybody loves it, so here is an example of key generation, run by a user who has previously generated a key, and has also set some optional flags (3-character long passcodes, extended algorithm): %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% reactor ~ % otpasswd -c codelength=3 -c label=Home -k ********************************************************* * This will irreversibly erase your current key, making * * all already printed passcards worthless! * ********************************************************* Are you sure you want to continue? (yes/no): yes Your current set of flags: show=on disabled=off alphabet=1 code_length=3 (salt=on) Passcard label="Home", no contact information. HINT: To generate key we need to gather lots of random data. To make this process faster you can move your mouse or cause some network or disc activity Key generated successfully. ***************************************************** * Print following passcard or at least make a note * * with a few first passcodes so you won't loose * * ability to log into your system! * ***************************************************** Home [1] A B C D E F G H 1: 2dM =78 o6! f8A uHF uHP Y%P :e+ 2: bq@ ff6 wSu ?LY TZf MB% coe MKR 3: Xt8 R%r thT kav pmH zLo =mD V%? 4: XhN %jD 8Fd dfs 56t qGR pDr %uy 5: +y! 9s? 7?r MCC +By U=9 2A= ECC 6: e8F Ejk n#i i#w e6R :Xm HhP XbK 7: DPJ #3s D!p qTD d#x khz CF8 Jt% 8: bLK MV: %Jr Vp4 rF@ Fby 8!! VTV 9: cvJ 7z: kwR A=3 RmC tMh NT? u6o 10: 8Fg 6qa JRD u4P =F@ #Y2 SsR SPA Are you ready to start using this one-time passwords? (yes/no): yes Key stored! One-time passwords enabled for this account. To display the current user configuration: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% * Your current state: Current card = 1 Current code = 0 Latest printed card = 1 Max card = 53687090 Max code = 4294967200 All auth failures = 0 Recent failures = 0 * Your current flags: show=on disabled=off alphabet=1 code_length=3 (salt=on) Passcard label="Home", no contact information. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Example usage: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% user@host $ ssh user@cirrus Password: Passcode G6 [1]: Jw% user@cirrus $ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 7. Documentation ================ In addition to this README, various other documents are included with the source distribution of this package. Depending upon the OTPasswd package that was installed, these documents may be available in the /usr/share hierarchy of your system. OTPasswd also is documented by a series of on-line man pages: otpasswd(7) - OTPasswd Principles of Operation otpasswd(1) - OTP Management Utility pam_otpasswd(8) - PAM Module otpasswd.conf(5) - System Configuration File otpasswd(5) - User State Information File otshadow(5) - System User State Information File An excellent description of PPPv3 is available on the Gibson Research Corporation website at . The evolving design of Perfect Paper Passwords was discussed extensively by Steve Gibson and Leo LaPorte on the TWiT Security Now! netcast in episodes #113, #115, and #117 during the fall of 2007. The GRC grc.thinktank newsgroup was the site of a great deal of activity regarding the design and development of Perfect Paper Passwords during this same time period. Quite a number of developers posted articles, as did Steve Gibson, himself. More information regarding GRC newsgroups is available at . To view the grc.thinktank newsgroup itself, point your favorite NNTP newsreader at . Most of the documentation we owe to Hannes Beinert who has devoted plenty of his time to make it look good. 8. Contact Information ====================== You may contact the author with questions, support, praise or curses at . Any feedback will be welcomed (even faint praise). And no, I don't get a lot of feedback, so don't think "nah, I won't write anything since he's probably pissed at us anyway". 9. History ========== The creation of this program was inspired by the ppp-pam project (http://code.google.com/p/ppp-pam/). The idea is basically the same. I started development by contributing to ppp-pam, but there were plenty of things to fix, and when the author didn't respond (during first month) I just decided I'd be better off rewriting everything from scratch. The two projects share some of my code, like locking functions, but nothing more. It would be reasonable to think of OTPasswd as a remote fork of ppp-pam. 10. Licensing ============= This README file, the examples and the source code of the OTPasswd program are all licensed under GNU General Public License version 3. The license should be included with the project inside LICENSE file. Copyright notice follows: Copyright (C) 2009, 2010 by Tomasz bla Fortuna This program 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 (at your option) any later version. This program 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 . ###