.\"-
.\" Copyright (c) 2013-2014 The University of Oslo
.\" Copyright (c) 2016 Dag-Erling Smørgrav
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. The name of the author may not be used to endorse or promote
.\"    products derived from this software without specific prior written
.\"    permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $Id$
.\"
.Dd January 9, 2016
.Dt OATHKEY 1
.Os
.Sh NAME
.Nm oathkey
.Nd OATH key management tool
.Sh SYNOPSIS
.Nm
.Op Fl hnrvw
.Op Fl u Ar user
.Op Fl k Ar keyfile
.Ar command
.Op Ar args
.Sh DESCRIPTION
The
.Nm
utility creates and manages OATH keys, and can be used to validate an
OATH response.
.Pp
The following options are available:
.Bl -tag -width Fl
.It Fl h
Print a usage message and exit.
.It Fl k Ar keyfile
Specify the location of the keyfile on which to operate.
The default is
.Pa /var/oath/ Ns Ar user Ns Pa .otpauth .
.It Fl n
When printing codes with the
.Cm calc
command, print the counter or timestamp along with each code.
.It Fl r
Disable writeback mode.
.It Fl u Ar user
Specify the user on which to operate.
The default is the current user.
Only root may operate on other users.
.It Fl v
Enable verbose mode.
.It Fl w
Enable writeback mode (see below).
This is the default.
.El
.Pp
The commands are:
.Bl -tag -width 6n
.It Cm calc Op Ar count
Compute and display the current code for the given key.
If a count is specified, compute and display
.Ar count
codes in total, starting with the current code, up to a maximum of
1,000 codes.
If writeback mode is enabled, the user's keyfile is updated to prevent
reuse.
.It Cm genkey Ar hotp | totp
Generate a new key for the specified OATH mode.
If writeback mode is enabled, the user's key is set; otherwise, it is
printed to standard output.
.It Cm getkey
Print the user's key.
.It Cm geturi
Print the user's key in otpauth URI form.
.It Cm resync Ar code1 Ar code2 Op Ar code3
Resynchronize an event-mode token that has moved too far ahead of the
validation server.
The codes provided must be consecutive codes within the
resynchronization window.
The resynchronization window is 100 if two codes are provided and 1000
if three codes are provided.
.It Cm setkey Ar uri
Set the user's key to the given otpauth URI.
.It Cm uri
Deprecated synonym for
.Cm geturi .
.It Cm verify Ar code
Verify that the given code is the correct current response for the
user's key.
If writeback mode is enabled and the response matched, the user's
keyfile is updated to prevent reuse.
.El
.Sh EXIT STATUS
The
.Cm verify
command exits 0 if the code is valid, 1 if it is invalid and >1 if an
error occurred.
.Pp
The
.Cm resync
command exits 0 if resynchronization was successful, 1 if it failed or
the specified key does not support resynchronization, and >1 if an
error occurred.
.Pp
All other commands exit 0 if successful and >1 if an error occurred.
.Sh SEE ALSO
.Xr oath_hotp 3 ,
.Xr oath_key 3 ,
.Xr oath_totp 3 ,
.Xr pam_oath 8
.Sh AUTHORS
The
.Nm
utility and this manual page were written by
.An Dag-Erling Sm\(/orgrav Aq des@des.no
for the University of Oslo.
.Sh BUGS
For TOTP keys, the
.Cm calc Ar count
command will only work correctly for a
.Ar count
of 1.