otpw-gen.1

.TH OTPW-GEN 1 "2014-08-07"
.SH NAME
otpw-gen \- one-time password generator
.SH SYNOPSIS
.B otpw-gen
[
.I options
]
.SH DESCRIPTION
.I OTPW
is a one-time password authentication system. It can be plugged into
any application that needs to authenticate users interactively.
One-time password authentication is a valuable protection against
password eavesdropping, especially for logins from untrusted
terminals.

Before you can use
.I OTPW
to log into your system, two preparation steps are necessary. Firstly,
your system administrator has to enable it. (This is usually done by
configuring your login software (e.g., sshd) to use
.I OTPW
via the Pluggable Authentication Module (PAM) configuration files in
/etc/pam.d/.)

Secondly, you need to generate a list of one-time passwords and print
it out. This can be done by calling
.IP
.B otpw-gen | lpr
.PP
or something like
.IP
.B otpw-gen -h 70 -s 2 | a2ps -1B -L 70 --borders no
.PP
if more control over the layout is desired.

You will be asked for a
.IR "prefix password" ,
which you need to memorize. It has to be entered immediately before
the one-time password. The prefix password reduces the risk that
anyone who finds or steals your password printout can use that alone
to impersonate you.

Each one-time password will be printed behind a three digit password
number. Such a number will appear in the password prompt when
.I OTPW
has been activated:
.IP
.B Password 026:
.PP
When you see this prompt, enter the memorized prefix password,
followed immediately by the one-time password identified by the
number. Any spaces within a password have only been inserted to
improve legibility and do not have to be copied.
.I OTPW
will ignore the difference between the easily confused characters
.B 0O
and
.B Il1
in passwords.

In some situations, for example if multiple logins occur
simultaneously for the same user,
.I OTPW
defends itself against the possibility of various attacks by asking
for three random passwords simultaneously.
.IP
.B Password 047/192/210:
.PP
You then have to enter the prefix password, followed immediately by
the three requested one-time passwords. This fall-back mode is
activated by the existence of the lock file
.BR ~/.otpw.lock .
If it was left over by some malfunction, it can safely be deleted
manually using option
.BR -l .

Call
.B otpw-gen
again when you have used up about half of the printed one-time
passwords or when you have lost your password sheet. This will disable
all remaining passwords on the previous sheet.

.SH OPTIONS
.TP 14
.BI \-h " number"
Specify the total number of lines per page to be sent to standard
output. This number minus four header lines determines the number of
rows of passwords on each page. The maximum number of passwords that
can be printed is 1000. (Minimum: 5, default: 60)
.TP
.BI \-w " number"
Specify the maximum width of lines to be sent to standard output. This
parameter determines together with the password length the number of
columns in the printed password matrix. (Minimum: 64, default: 79)
.TP
.BI \-s " number"
Specify the number of form-feed separated pages to be sent to standard
output. (Default: 1)
.TP
.BI \-e " number"
Specify the minimum entropy of each one-time password in bits. The
length of each password will be chosen automatically, such that there
are at least two to the power of the specified number possible
passwords. A value below 30 might make the passwords vulnerable to
a brute-force guessing attack. If the attacker might have read access to
the
.B ~/.otpw
file, the value should be at least 48. Paranoid users might prefer
long high-security passwords with at least 60 bits of entropy.
(Default: 48)
.TP
.BI \-p 0
Generate passwords by transforming a random bit string into a sequence
of letters and digits, using a form of base-64 encoding (6 bits per
character). (Default)
.TP
.BI \-p 1
Generate passwords by transforming a random bit string into a sequence
of English four-letter words, each chosen from a fixed list of 2048
words (2.75 bits per character).
.TP
.BI \-p 2
Generate passwords by transforming a random bit string into a sequence
of lowercase letters and digits (5 bits per character). These are easier
to communicate by voice (e.g., using the NATO alphabet).
.TP
.BI \-f " filename"
Specify a file to be used instead of
.I ~/.otpw
for storing the hash values of the generated one-time passwords.
.TP
.BI \-n
Suppress the addition of a header and footer line to each output page.
This reduces the minimum value for option
.I \-h
to 1.
.TP
.BI \-m
Instead of generating each password randomly, generate a random
.I master key
and then derive each password from that in a deterministic way.  The
master key will be printed to standard error. It can later be used
with option
.I \-k
to recreate another copy of the same one-time password list. (Each
password is generated from the output of a secure hash function
applied to the master key and the challenge string.)
.TP
.BI \-E " number"
Specify the minimum entropy of the master key in bits. (It contains in
addition four bits redundancy for error checking.)
.TP
.BI \-P " number"
Choose the text format in which the master key will be displayed.
The supported values are the same as with option
.IR \-p .
.TP
.BI \-k
Ask for a master key, as it was generated by option
.IR -m ,
and then recreate the same password list from that. With this option,
only a password list will be generated; the hash values in
.I ~/.otpw
remain unmodified.
.TP
.BI \-r
Output a suggestion for a random password, then exit. The length and
type of password can be selected with options
.I \-e
and
.IR \-p .
.TP
.BI \-l
Remove any lock file left by previous authentication attempts, then exit.

.SH PSEUDO-USER INSTALLATION
If the
.B otpw-gen
binary, owned by some system pseudo user (e.g., “otpw”), has the
SETUID bit set, then the password hash file will be owned by and
stored in the home directory of that pseudo user (e.g.,
“/var/lib/otpw”), using the user's name instead of “.otpw”. This way,
the hash files are out of reach from the users, and cannot be
manipulated by tools other than
.BR otpw-gen ,
which can help to enforce policies about how passwords are generated.
Storing the password hash files outside the user's home directory can
also be useful where the home directory may not yet be accessible
during login.

.SH AUTHOR
The
.I OTPW
package, which includes the
.I otpw-gen
progam, has been developed by Markus Kuhn. The most recent version is
available from <http://www.cl.cam.ac.uk/~mgk25/otpw.html>.
.SH SEE ALSO
pam(8), pam_otpw(8)