source: openpam/branches/oath/bin/oathkey/oathkey.1 @ 911

Last change on this file since 911 was 911, checked in by Dag-Erling Smørgrav, 4 years ago

merge r910: correct markup for email addresses

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 4.3 KB
Line 
1.\"-
2.\" Copyright (c) 2013-2014 The University of Oslo
3.\" Copyright (c) 2016 Dag-Erling Smørgrav
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\" 3. The name of the author may not be used to endorse or promote
15.\"    products derived from this software without specific prior written
16.\"    permission.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28.\" SUCH DAMAGE.
29.\"
30.\" $Id: oathkey.1 911 2017-01-21 12:37:15Z des $
31.\"
32.Dd January 9, 2016
33.Dt OATHKEY 1
34.Os
35.Sh NAME
36.Nm oathkey
37.Nd OATH key management tool
38.Sh SYNOPSIS
39.Nm
40.Op Fl hnrvw
41.Op Fl u Ar user
42.Op Fl k Ar keyfile
43.Ar command
44.Op Ar args
45.Sh DESCRIPTION
46The
47.Nm
48utility creates and manages OATH keys, and can be used to validate an
49OATH response.
50.Pp
51The following options are available:
52.Bl -tag -width Fl
53.It Fl h
54Print a usage message and exit.
55.It Fl k Ar keyfile
56Specify the location of the keyfile on which to operate.
57The default is
58.Pa /var/oath/ Ns Ar user Ns Pa .otpauth .
59.It Fl n
60When printing codes with the
61.Cm calc
62command, print the counter or timestamp along with each code.
63.It Fl r
64Disable writeback mode.
65.It Fl u Ar user
66Specify the user on which to operate.
67The default is the current user.
68Only root may operate on other users.
69.It Fl v
70Enable verbose mode.
71.It Fl w
72Enable writeback mode (see below).
73This is the default.
74.El
75.Pp
76The commands are:
77.Bl -tag -width 6n
78.It Cm calc Op Ar count
79Compute and display the current code for the given key.
80If a count is specified, compute and display
81.Ar count
82codes in total, starting with the current code, up to a maximum of
831,000 codes.
84If writeback mode is enabled, the user's keyfile is updated to prevent
85reuse.
86.It Cm genkey Ar hotp | totp
87Generate a new key for the specified OATH mode.
88If writeback mode is enabled, the user's key is set; otherwise, it is
89printed to standard output.
90.It Cm getkey
91Print the user's key.
92.It Cm geturi
93Print the user's key in otpauth URI form.
94.It Cm resync Ar code1 Ar code2 Op Ar code3
95Resynchronize an event-mode token that has moved too far ahead of the
96validation server.
97The codes provided must be consecutive codes within the
98resynchronization window.
99The resynchronization window is 100 if two codes are provided and 1000
100if three codes are provided.
101.It Cm setkey Ar uri
102Set the user's key to the given otpauth URI.
103.It Cm uri
104Deprecated synonym for
105.Cm geturi .
106.It Cm verify Ar code
107Verify that the given code is the correct current response for the
108user's key.
109If writeback mode is enabled and the response matched, the user's
110keyfile is updated to prevent reuse.
111.El
112.Sh EXIT STATUS
113The
114.Cm verify
115command exits 0 if the code is valid, 1 if it is invalid and >1 if an
116error occurred.
117.Pp
118The
119.Cm resync
120command exits 0 if resynchronization was successful, 1 if it failed or
121the specified key does not support resynchronization, and >1 if an
122error occurred.
123.Pp
124All other commands exit 0 if successful and >1 if an error occurred.
125.Sh SEE ALSO
126.Xr oath_hotp 3 ,
127.Xr oath_key 3 ,
128.Xr oath_totp 3 ,
129.Xr pam_oath 8
130.Sh AUTHORS
131The
132.Nm
133utility and this manual page were written by
134.An Dag-Erling Sm\(/orgrav Aq Mt des@des.no
135for the University of Oslo.
136.Sh BUGS
137For TOTP keys, the
138.Cm calc Ar count
139command will only work correctly for a
140.Ar count
141of 1.
Note: See TracBrowser for help on using the repository browser.