otpasswd - One-time password management utility



otpasswd [options]



The otpasswd utility serves as the primary management tool for the OTPasswd one-time password authentication package for both users and administrators. It allows the user to generate a key, print passcards, and manage various configuration options.

In general, once OTPasswd has been installed, the system administrator must determine where the system will keep the user configuration data (user state). The administrator will likely also configure the system by making various policy choices, such as how long passcodes must be, how complicated the static password should be, which passcode alphabet will be used, etc. Subsequently, users will probably also make some configuration choices - to the degree they are permitted by policy - and then they will generate a key and print some passcards. All of these activities involve the use of the otpasswd(1) utility. Once this initial configuration is complete, the OTPasswd system will operate virtually autonomously. Each time a user attempts to login to the system, or otherwise authenticate with some service which uses the pam_otpasswd(8) module, the previously configured data is consulted, a one-time passcode challenge will be issued, and the user will have a chance to authenticate.  



User Administration

-k, --key
Generate a new key. May be combined with the --config (-c) option. If the user already has state information present, otpasswd can either use the system default user state configuration, or it can continue to use the the previously configured user state. In this situation, the user is asked to express a preference. Regardless, the user configuration may subsequently be modified through the use of option flags to the otpasswd utility. Once key generation is complete and the user state has been prepared, otpasswd prints the first passcard and waits until the user has made a note of the first few passcodes.
-r, --remove
Remove user state. This completely removes any existing user configuration. Note that if system policy requires OTPasswd use, this action will effectively disable the user's login. Furthermore, if policy also prohibits user key generation, only the administrator will be able to restore access.

Passcard Printing

-t, --text ( card | code )
Generate either one ASCII passcard, or a single passcode.
-l, --latex ( card | code )
Generate six (6) LaTeX passcards beginning with the specified passcard.

Miscellaneous Passcode Operations

-P, --prompt ( card | code )
Display authentication prompt for the specified passcode.
-a, --authenticate passcode
Attempt authentication with the actual passcode specified. This might be used for testing or scripted authentication.
-s, --skip ( card | code )
Skip forward to a specific point in the passcode sequence. The next authentication will request either the specified passcode, or the first passcode on the specified passcard.
-w, --warning
Display any current warnings. For example, if the user is currently on the last printed passcard. It is useful to include this option in the user shell start-up commands to stay informed of any OTPasswd system conditions which may affect the user's ability to login.


-i, --info
Display current user state configuration.
Display private sequence key and passcode counter.
-c, --config item
Set various flags which regulate OTPasswd system behavior:
show=( on | off )
Configure passcode visibility during authentication.
alphabet=( ID | list )
Sets the ID of the alphabet to be used. The list keyword may be used to display a list of all available alphabets. By default, a 64-character alphabet is used.
Set the number of passcode characters to length. length may be any value between 2 and 16. Four (4) character passcodes are used by default.
salt=( on | off )
Meaningful only during key generation. Enables or disables salting of the passcode counter. Setting this option to off will make OTPasswd compatible with the PPPv3.1 specification. This has the additional consequence of increasing the number of available passcards while (theoretically) lowering the security of the system.
disable=( on | off )
Disable the user. Unlike --remove, this will not delete the user's state information.
Set contact information to string. This is used when passcodes are sent via an out-of-band channel. The exact interpretation of string will depend on the user configuration, but could be a phone number, IM username, email address, etc. Use an empty string ("") to unset this value.
Set a title for the generated passcards. This will be displayed at the top of every passcard. Use an empty string ("") to clear this value, in which case the current hostname will be used by default.
-p, --password[=password]
Set the static password. Argument is optional, if not given otpasswd will ask you for password in a secure manner. Enter twice the empty password to delete it.
-u, --user ( username | UID )
Specify the user account upon which to operate. Normal users may only change their own account, while the superuser may change any account with this option. Either a symbolic username or a numeric UID may be specified. (Administrator only)


-v, --verbose
Display more information about program operation. Use twice for even more information.
Display license, warranty, version and author information.
-h, --help
Program usage and option help information.
Obsolete option, moved to the agent_otp executable.

Parameter References

When an option accepts a passcode reference (code), it can be specified in any of the following ways:
Passcode number. Each passcode has a unique decimal number, starting with the first passcode generated.
Passcode address. Each passcode has a unique address comprised of the column C (a letter) and row RR (one or more digits) on a specific passcard number (#). For example, 'F3[45]' refers to the passcode at column F and row 3 of passcard 45.
The passcode which will be used for the next authentication.
Passcard references (card) may be specified as follows:
Passcard number.
The passcard containing the current passcode.
The first unprinted passcard. Brackets are optional.



This section needs to be completed (FIXME). Until this section is written, see the docs/security file which is distributed with the OTPasswd sources.



otpasswd will return zero on success and non-zero on failure. This can be used for scripting (e.g. see the --authenticate/-a option).



The directory for OTPasswd configuration files. If OTPasswd is configured to use a global flat-file database, then this file resides here, also. The directory should be owned by the special otpasswd system user, and should not be accessible for normal users (mode 0700).
The main OTPasswd system configuration file. This file contains key-value configuration parameters that govern the operation of the system. In particular, it contains the state database configuration, system-wide defaults, PAM configuration and policy configuration. When the backend user database is configured to use MySQL or LDAP, this file will contain privileged information and must be not be accessible for normal users.
The system-wide user database, used only when the otpasswd.conf(5) configuration file specifies the use of a global database backend. The file contains state information for all users, including keys, flags, etc, and must not be accessible to normal users.
This file is only used when the system configuration file otpasswd.conf(5) specifies that state information is to be maintained in user home directories. This has the same format as the otshadow(5) file above, except it only contains information for a single user.
The PAM prototype configuration for OTPasswd. If this file is included in a PAM configuration for any service (like SSH), the pam_otpasswd(8) PAM module will be used to ask the user for a passcode just after the normal pam_unix(8) authentication mechanisms are applied.
The OTPasswd system PAM module. This module is dynamically loaded by PAM(7) when an OTPasswd one-time password authentication has been configured. Various runtime options exist for this module to modify operation. For more information, see pam_otpasswd(8).



The OTPasswd authentication system is compatible with the "Perfect Paper Passwords" specification version 3 (PPPv3) as developed by the Gibson Research Corporation. See DOCUMENTATION, below.

Note that for OTPasswd to operate in a manner which is strictly compatible with PPPv3, it is important to specify the --config salt=no option during key generation. A compatible key will generate passcards and passcodes which are interoperable with other PPPv3-compliant applications. For a list of such applications, see <http://www.grc.com/ppp/software.htm>.

OTPasswd does not support any earlier versions of the PPP specification.



Every user must generate a key in order to use OTPasswd. Depending on the value of the SALT_DEF parameter in the otpasswd.conf(5) file, a cryptographic salt may be used to generate the passcode counter by default. The use of a salt may also be affected by the salt parameter to the otpasswd --config option. A salted key is not compatible with the PPPv3 specification, however. To generate a new salted key and print the first passcard, use:

     $ otpasswd --config salt=on --key

To inspect the current user state configuration, which contains information relating to the passcode length, contact information, passcode alphabet choice, passcard label, etc, you may use the following command:

     $ otpasswd --info

Typically, to use the OTPasswd authentication system, a user will carry a series of passcards to consult during system login. Specific passcards may be printed in either LaTeX or plain ASCII text. The '[' character may be a shell metacharacter, so it may need to be quoted or backslash-escaped. To print the third passcard in ASCII text, use:

     $ otpasswd --text '[3]'

And the current passcard may be printed with:

     $ otpasswd --text '[current]'

To configure a passcode length of five (5) characters, use:

     $ otpasswd --config codelength=5

The --config option may be used at any time, including during key generation.

While plain ASCII passcards are perfectly useful, LaTeX enables much more attractively formatted passcards and provides an easy approach to printing a few passcards at a time. One way to efficiently print a LaTeX file is to use the pdflatex utility from the texlive-latex-base package. To generate the next six (6) passcards on an A4 page using LaTeX, use:

$ otpasswd --latex next > tmp.latex
$ pdflatex tmp.latex
$ lp tmp.pdf

# Remember to remove any temporary files
# to keep your passcards secret!

$ rm tmp.latex tmp.pdf


pam_otpasswd(8), otpasswd(5) agent_otp(1)



The documentation for otpasswd is also maintained as a Texinfo manual. If the info and otpasswd programs are properly installed at your site, the following command should give you access to the manual:

     $ info otpasswd

In addition to this manual, various other documents are included with the source to this package. Depending upon the OTPasswd package that was installed, these documents may be available in the /usr/share hierarchy of your system.

An excellent description of PPPv3 is available on the Gibson Research Corporation website at <https://www.grc.com/ppp.htm>.

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 <http://www.grc.com/discussions.htm>. To view the grc.thinktank newsgroup itself, point your favorite NNTP newsreader at <news://news.grc.com/grc.thinktank>.



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. Initially, contributions were made to ppp-pam, however ultimately it was decided to do a complete rewrite. The two projects share some code, such as locking functions, but nothing more. It would be reasonable to think of OTPasswd as a fork of ppp-pam.



Copyright (c) 2009, 2010 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 this program in a LICENSE file.



The latest version of the OTPasswd package is available in source form at the project website https://savannah.nongnu.org/projects/otpasswd



User Administration
Passcard Printing
Miscellaneous Passcode Operations
Parameter References

This document was created by man2html, using the manual pages.
Time: 22:16:42 GMT, November 02, 2013