OTPasswd - One-Time Password Authentication System -------------------------------------------------- http://otpasswd.thera.be Updated: 26-Oct-2013 (v0.8) README Contents ======== 1. Package Status 2. Documentation 3. Introduction 4. Package Features 5. Security Advisory 6. Installation 7. Demo (Screenshot!) 8. Contact Information 9. History 10. Licensing 1. 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.8) 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 https://github.com/blaa/OTPasswd/blob/master/README 2. 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. Documentation Index: README - Generic system information INSTALL - Source installation hints Project Webpage - http://otpasswd.thera.be README.Debian - Things you need to know after Debian installation. OTPasswd is documented by a following man pages: otpasswd(1) - OTP Management Utility pam_otpasswd(8) - PAM Module otpasswd(5) - 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. 3. Introduction =============== A one-time password (OTP) is a password that is only valid for a single login session or transaction. It is normally used along with a normal password to create a two-factor authentication using something you have (mobile or passcard) and something you know (a password). Using an OTP reduces the risks associated with logging into your system from insecure (eg, key logged) workstations. The OTPasswd package consists of two primary components, a user utility (otpasswd + agent_otp) 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_otp. 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. When SSH uses certificates for authentication it bypasses the whole PAM stack. That gives user a great opportunity - one can configure key authentication from all trusted workstations and get asked one-time passwords only when logging in from external, untrusted machines. OTPasswd is written in C (C99) and implements an OTP system as described by Steve Gibson's "Perfect Paper Passwords" specification version 3.1. In a nutshell one-time passwords are generated using AES cipher in a counter mode. 4. Main package features ======================== Main features: * Use of Pluggable Authentication Module (PAM) allows great flexibility * Modern set of crypto algorithms: Rijndael (AES) and SHA-2. * Compatible with the well-documented PPP (Perfect Paper Passwords) * Highly customizable: - user-selectable alphabets, - passcode lengths - passcard labels, OOB contact - key salting on/off * Warnings issued when user passcard supply is running low * Passcards may be generated in either plain ASCII or LaTeX * Out-of-band transmission of codes using external script (Email, SMS) * Support for cryptographic salt to increase attack resistance (optional) * Designed and written with emphasis on secure code - Plenty of testcases - Tested with valgrind for memory problems - Locking of state files to resolve race conditions - Implemented correct-configuration checkers User mode: * Does not require additional SUID binaries in USER mode. * Works almost out-of-the-box. Global mode: * Capable of enforcing system OTP security policy decisions: * Users can be forced to use OTP * Users can't directly access their state and can't easily break security. 5. Security Advisory ==================== It is very important that the user has a good understanding of the OTPasswd intent, purpose and limitations. The user is encouraged to read the documentation provided in the (or /usr/share/doc/otpasswd/SECURITY if installed). The user is advised to take the following basic 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. If you are willing to use it as a first or single authentication factor - make sure you know what you are doing. 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! 6. Installation =============== OTPasswd installation instructions and description of operational modes is covered in the INSTALL file. 7. 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 $ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 8. Contact Information ====================== You may contact the author with questions, support, praise or curses at . Any feedback will be welcomed and keeps us going (even a 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-2013 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 . IMPORTANT: It was always planned to relicense this software under BSD-like license one day. Most changes required for relicensing are already complete. To contribute to the project you have to agree to relicense your contribution as well. ###