mirror of
https://github.com/adulau/ootp.git
synced 2024-11-24 02:57:10 +00:00
532 lines
13 KiB
Text
532 lines
13 KiB
Text
<!DOCTYPE refentry PUBLIC "-//Davenport//DTD DocBook V3.0//EN">
|
|
|
|
<!-- $Id: otp-control.sgml 169 2011-05-11 04:10:57Z maf $ -->
|
|
|
|
<refentry>
|
|
|
|
<refmeta>
|
|
<refentrytitle>
|
|
<application>otp-control</application>
|
|
</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>
|
|
<application>otp-control</application>
|
|
</refname>
|
|
<refpurpose>
|
|
Local user database configuration for One Time Password package.
|
|
</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>otp-control</command>
|
|
<arg>-?hnv</arg>
|
|
<arg>-c<replaceable> count</replaceable></arg>
|
|
<arg>-C<replaceable> count_ceiling</replaceable></arg>
|
|
<arg>-f<replaceable> format</replaceable></arg>
|
|
<arg>-F<replaceable> flag</replaceable></arg>
|
|
<arg>-H<replaceable> sc_hostname</replaceable></arg>
|
|
<arg>-I<replaceable> sc_index</replaceable></arg>
|
|
<arg>-k<replaceable> key</replaceable></arg>
|
|
<arg>-l<replaceable> location</replaceable></arg>
|
|
<arg>-m<replaceable> command_mode</replaceable></arg>
|
|
<arg>-o<replaceable> otp_db</replaceable></arg>
|
|
<arg>-s<replaceable> status</replaceable></arg>
|
|
<arg>-S<replaceable> sc_flags</replaceable></arg>
|
|
<arg>-t<replaceable> type</replaceable></arg>
|
|
<arg>-u<replaceable> username</replaceable></arg>
|
|
<arg>-V<replaceable> service_name</replaceable></arg>
|
|
<arg>-w<replaceable> window</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
|
|
<refsect1>
|
|
<title>DESCRIPTION</title>
|
|
<para>
|
|
The <command>otp-control</command> command is a front end to the
|
|
local One Time Password database. Users can be added, modified
|
|
and removed by <command>otp-control.</command>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>OPTIONS</title>
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term>-c, --count= <replaceable> count</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
User count. The count increases with each OTP transaction.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-C, --count-ceil= <replaceable> count_ceiling</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
User count ceiling. Highest count allowed for this user. Configuring
|
|
the count_ceiling allows a user key to be shared among multiple
|
|
systems each with a unique count window, where count <= count_ceiling.
|
|
</para><para>
|
|
A count value must only be allowed for authentication once.
|
|
</para><para>
|
|
Example:
|
|
</para><para>
|
|
host=h1, user=bob, count_current=0, count_ceiling=10000.
|
|
</para><para>
|
|
host=h2, user=bob, count_current=10001, count_ceiling=20000.
|
|
</para><para>
|
|
The number of keys a user must possess is decreased at the expense
|
|
of security dependencies among multiple systems. If system A is
|
|
compromised, OTP's can be generated for the user(s) on system B from
|
|
the shared keys on system A. To generate an OTP out of sequence the count
|
|
must be presented to the OTP generator. The additional step of entering
|
|
the count to the OTP generator is not necessary when keys are not
|
|
shared, as the currrent count will increase on the OTP generator and
|
|
system database during authentication.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-f, --format=</term>
|
|
<listitem>
|
|
<para>
|
|
OTP format. One of hex40 dhex40 dec31.6 dec31.7 dec31.8 dec31.9 dec31.10.
|
|
hex40 (40 bit hex) is the default. dec31.6 (31 bit decimal truncated to 6
|
|
digits) is suggested by RFC 4226 and may be required to interoperate with
|
|
other HOTP implementations. dhex40 uses the dynamic truncate function
|
|
in RFC 4226, where hex40 always uses the top 40 bits. dhex40 may be the
|
|
default in future releases.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-F, --flag=</term>
|
|
<listitem>
|
|
<para>
|
|
OTP flag. All flags are unset by default.
|
|
<screen>
|
|
Flag Description
|
|
-----------------------------------------------------------------
|
|
display-count : Display HOTP count when prompted for challenge.
|
|
send-token : Send token to user out of band.
|
|
</screen>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry>
|
|
<term>-h, --help</term>
|
|
<listitem>
|
|
<para>
|
|
Help.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry>
|
|
<term>-H, --sc_hostname=<replaceable> sc_hostname</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Set the SC hostname for the list-sc command mode.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-I, --sc_index=<replaceable> sc_index</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Set the SC index for the list-sc command mode.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-k, --key=<replaceable> key</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
160 bit shared secret key in ASCII HEX. The secret key is shared between
|
|
the OTP generation hardware/software for a user and the local OTP database.
|
|
Each user typically will have a unique key unless a shared key with
|
|
unique count space is provisioned. Use - for stdin. Example key:
|
|
C0C3D47F1CC68ECE0DF81D008F0C0D72D43EB745
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-l, --location=<replaceable> location</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Location to send token to when SEND_TOKEN flag is set.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-m, --command_mode=<replaceable> command_mode</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
</para>
|
|
<screen>
|
|
Mode Description
|
|
-------------------------------------------------
|
|
add - Add user
|
|
create - Create database
|
|
dump - ASCII dump user record(s)
|
|
generate - Generate HOTP for user
|
|
list - List user record (printable)
|
|
list-sc - List user record (SC friendly)
|
|
load - ASCII load user record(s)
|
|
remove - Remove user
|
|
send-token - Send token to user
|
|
set-count - Set user count
|
|
set-count-ceil - Set user count ceiling
|
|
set-flags - Set user flags
|
|
set-format - Set user format
|
|
set-status - Set user status
|
|
set-type - Set user OTP type
|
|
test - Test user
|
|
</screen>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-n, --create_database</term>
|
|
<listitem>
|
|
<para>
|
|
Create new database if one does not exist.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-o, --otp-db=<replaceable> otp_db</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Pathname of OTP database.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-s, --status=<replaceable> status</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
OTP Status. The default status is active.
|
|
<screen>
|
|
Status Description
|
|
-----------------------------------------------------------------
|
|
active : OTP is required for succesful authentication.
|
|
inactive : OTP may not be required for successful authentication.
|
|
The OTP authentication module may be configured to allow
|
|
inactive accounts to authenticate. This may be used to
|
|
temporarily remove the OTP authentication method for a
|
|
user.
|
|
disabled : Account is disabled. OTP authentication will fail.
|
|
</screen>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry>
|
|
<term>-S, --sc-flags=<replaceable> sc_flags</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Set the SC flags for the list-sc command mode. 0=CHALLENGE, 1=READERKEY.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-t, --type=<replaceable> type</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
OTP Type. RFC 4226 HOTP is only supported type.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-u, --username=<replaceable> username</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Username to perform database operation on.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-v, --verbose</term>
|
|
<listitem>
|
|
<para>
|
|
Enable verbose output (debugging).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-V, --service-name=<replaceable> service_name</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Set service name for send-token function.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>--version</term>
|
|
<listitem>
|
|
<para>
|
|
Display software version.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-w, --challenge-window=<replaceable> window</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Set the maximum window (count above the system count) where an OTP
|
|
will successfully authenticate. For user bob with with OTP generator
|
|
count_current=30, and system OTP database for bob count_current 15, the
|
|
default window (10) will not allow the user to authenticate, even though
|
|
the OTP is computed with a valid shared key. This can be caused by the
|
|
user repeatedly generating an OTP which is not used for authentication.
|
|
</para><para>
|
|
When generating an OTP (mode generate) the window will configure the number
|
|
of tokens generated.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>OTP-CONTROL COMMANDS</title>
|
|
|
|
<para>
|
|
<command>add</command>
|
|
: add user to OTP database. count_cur and count_ceiling may optionally
|
|
be specified with -c and -C respectively. A random key will be generated
|
|
if no key is specified with -k. The format, flags, status, and type
|
|
may be altered from the defaults with -f, -F, -s, and -t respectively.
|
|
</para>
|
|
|
|
<para>
|
|
<command>create</command>
|
|
: create OTP database. The OTP database is a base directory with each
|
|
user stored in a separate ASCII : delimited file in base_dir/d.
|
|
</para>
|
|
|
|
<para>
|
|
<command>dump</command>
|
|
: dump user database in ASCII. User records are separated by a newline.
|
|
Fields are : separated. All fields except the username are HEX encoded.
|
|
</para><para>
|
|
#version:user:key:status:format:type:flags:count_cur:count_ceiling:last
|
|
01:test:1111111111111111111111111111111111111111:01:01:01:00:00000000000003E8:00000000000007D0:0000000000000000
|
|
</para>
|
|
|
|
<para>
|
|
<command>generate</command>
|
|
: generate OTP for user. The -w flag may be used to generate multiple
|
|
OTP tokens.
|
|
</para>
|
|
|
|
<para>
|
|
<command>list</command>
|
|
: list user record in user friendly format.
|
|
</para>
|
|
|
|
<para>
|
|
<command>list-sc</command>
|
|
: list user record in otp-sc import friendly format. The SC hostname
|
|
must be specified with -H. The SC index and SC flags may optionally be
|
|
specified with -I and -F.
|
|
</para>
|
|
|
|
<para>
|
|
<command>load</command>
|
|
: load user record(s)s in ASCII format. See dump.
|
|
</para>
|
|
|
|
<para>
|
|
<command>remove</command>
|
|
: remove user from OTP database.
|
|
</para>
|
|
|
|
<para>
|
|
<command>set-count</command>
|
|
: set count_current for user.
|
|
</para>
|
|
|
|
<para>
|
|
<command>set-count-ceil</command>
|
|
: set count_ceiling for user. A OTP will not authenticate when
|
|
count_cur >= count_cieiling.
|
|
</para>
|
|
|
|
<para>
|
|
<command>set-flags</command>
|
|
: set flags for user. See option -F.
|
|
</para>
|
|
|
|
<para>
|
|
<command>set-format</command>
|
|
: set format for user. See option -f.
|
|
</para>
|
|
|
|
<para>
|
|
<command>set-status</command>
|
|
: set status for user. See option -s.
|
|
</para>
|
|
|
|
<para>
|
|
<command>set-type</command>
|
|
: set status for user. See option -t.
|
|
</para>
|
|
|
|
<para>
|
|
<command>test</command>
|
|
: test OTP authentication for user.
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>EXAMPLES</title>
|
|
|
|
<informalexample>
|
|
<para>
|
|
Create a new OTP database /etc/otpdb. Add user bob with random key.
|
|
</para>
|
|
<para>
|
|
<command>otp-control -n -f /etc/otpdb -u bob -m add</command>
|
|
</para>
|
|
<screen>
|
|
Generating random 160 bit key.
|
|
Adding user bob.
|
|
</screen>
|
|
</informalexample>
|
|
|
|
<informalexample>
|
|
<para>
|
|
Display user bob OTP database entry.
|
|
</para>
|
|
<para>
|
|
<command>otp-control -u bob -m list</command>
|
|
</para>
|
|
<screen>
|
|
Username.......bob
|
|
Key............C381739834A63A67B0B9F7F7D36C8C567F6BFB3D
|
|
Count..........0 (0x0)
|
|
Count Ceiling..18446744073709551615 (0xFFFFFFFFFFFFFFFF)
|
|
Version........1
|
|
Status.........active (1)
|
|
Format.........hex40 (1)
|
|
Type...........HOTP (1)
|
|
Flags..........[] (0x00)
|
|
</screen>
|
|
</informalexample>
|
|
|
|
<informalexample>
|
|
<para>
|
|
Generate OTP for user bob.
|
|
</para>
|
|
<para>
|
|
<command>otp-control -u bob -m generate</command>
|
|
</para>
|
|
<screen>
|
|
count=0 crsp=882B0E8410
|
|
</screen>
|
|
</informalexample>
|
|
|
|
<informalexample>
|
|
<para>
|
|
Test OTP for user bob.
|
|
</para>
|
|
<para>
|
|
<command>otp-control -u bob -m test</command>
|
|
</para>
|
|
<screen>
|
|
Testing authentication for user bob.
|
|
OTP challenge for user bob (0): 882B0E8410
|
|
Success.
|
|
</screen>
|
|
</informalexample>
|
|
|
|
<informalexample>
|
|
<para>
|
|
Dump OTP database to stdout. Fields other than username are hex encoded.
|
|
Use the load command to import records in this format.
|
|
</para>
|
|
<para>
|
|
<command>otp-control -m dump</command>
|
|
</para>
|
|
<screen>
|
|
#version:user:key:status:format:type:flags:count_cur:count_ceiling:last
|
|
01:bob:C381739834A63A67B0B9F7F7D36C8C567F6BFB3D:01:01:01:00:0000000000000001:FFFFFFFFFFFFFFFF:000000004AA02F9E
|
|
</screen>
|
|
</informalexample>
|
|
|
|
<informalexample>
|
|
<para>
|
|
Dump OTP user to stdout in format friendly to <command>otp-sca</command>. Note the
|
|
hostname must be set with -H. The index will default to 0 if not specified
|
|
with -I. SC flags may be set with -F.
|
|
</para>
|
|
<para>
|
|
<command>otp-control -u test -m list-sc -H dev1</command>
|
|
</para>
|
|
<screen>
|
|
<computeroutput>
|
|
#index:count:hostname:key
|
|
00:000003E8:646576310000000000000000:1111111111111111111111111111111111111111
|
|
</computeroutput>
|
|
|
|
</screen>
|
|
</informalexample>
|
|
|
|
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>AUTHOR</title>
|
|
<para>
|
|
<author>
|
|
<firstname>Mark</firstname>
|
|
<surname>Fullmer</surname>
|
|
</author>
|
|
<email>maf@splintered.net</email>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>SEE ALSO</title>
|
|
<para>
|
|
<application>otp-sca</application>(1)
|
|
<application>otp-sct</application>(1)
|
|
<application>pam_otp</application>(1)
|
|
<application>htsoft-downloader</application>(1)
|
|
<application>otp-ov-plugin</application>(1)
|
|
<application>urd</application>(1)
|
|
<application>bcload</application>(1)
|
|
<hardware>spyrus-par2</hardware>(7)
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|