Document the otp commands

This patch adds the otp commands to the README and describes them in the
nitrocli(1) man page.

1 files changed, 68 insertions, 9 deletions

diff --git a/nitrocli/doc/nitrocli.1 b/nitrocli/doc/nitrocli.1
index 98f6b28..e345cdb 100644
--- a/nitrocli/doc/nitrocli.1
+++ b/nitrocli/doc/nitrocli.1
@@ -1,28 +1,87 @@
-.TH NITROCLI 1 2018-12-26
+.TH NITROCLI 1 2018-12-27
 .SH NAME
 nitrocli \- access Nitrokey devices
 .SH SYNOPSIS
 .B nitrocli
-\fBclear\fR|\fBclose\fR|\fBopen\fR|\fBstatus\fR
+\fIcommand\fR
+[\fIarguments\fR]
 .SH DESCRIPTION
 \fBnitrocli\fR provides access to Nitrokey devices.
-Currently, \fBnitrocli\fR only supports accessing the encrypted volume of a
-Nitrokey Storage.
+It supports the Nitrokey Pro and the Nitrokey Storage.
+It can be used to access the encrypted volume and the one-time password generator.
 .SH COMMANDS
+.SS General
 .TP
-.B open
+.B nitrocli open
 Open the encrypted volume on the Nitrokey Storage.
 The user PIN that is required to open the volume is queried using 
 \fBpinentry\fR(1) and cached by \fBgpg-agent\fR(1).
 .TP
-.B close
+.B nitrocli close
 Close the encrypted volume on the Nitrokey Storage.
 .TP
-.B status
+.B nitrocli status
 Print the status of the connected Nitrokey device, including the stick serial
 number, SD card serial number, the firmware version and the PIN retry count.
 For the Nitrokey Storage, it also includes the encryption status and the status
 of the volumes.
 .TP
-.B clear
-Clear the passphrase cached by the \fBopen\fR command.
+.B nitrocli clear
+Clear the passphrases cached by the other commands.
+.SS One-time passwords
+.TP
+\fBnitrocli otp get \fIslot \fR[\fB-a\fR|\fB--algorithm \fIalgorithm\fR]
+Generate a one-time password.
+\fIslot\fR is the number of the slot to generate the password on.
+\fIalgorithm\fR is the OTP algorithm to use.
+Possible values are \fBhotp\fR for the HOTP algorithm according to RFC 4226 and
+\fBtotp\fR for the TOTP algorithm according to RFC 6238 (default).
+.TP
+\fBnitrocli otp set \fIslot name secret \
+\fR[\fB-a\fR|\fB--algorithm \fIalgorithm\fR] \
+[\fB-d\fR|\fB--digits \fI digits\fR] [\fB-c\fR|\fB--counter \fIcounter\fR] \
+[\fB-t\fR|\fB--time-window \fItime window\fR] [\fB--ascii\fR]
+Configure a one-time password slot.
+\fIslot\fR is the number of the slot to configure.
+\fIname\fR is the name of the slot (may not be empty).
+\fIsecret\fR is the secret value to store on that slot.
+If \fB--ascii\fR is set, each character of the given secret is interpreted as
+the ASCII code of one byte.
+Otherwise, every two characters are interpreted as the hexadecimal value of one
+byte.
+
+\fIalgorithm\fR is the OTP algorithm to use.
+Possible values are \fBhotp\fR for the HOTP algorithm according to RFC 4226 and
+\fBtotp\fR for the TOTP algorithm according to RFC 6238 (default).
+\fIdigits\fR is the number of digits the one-time password should have.
+Allowed values are 6 and 8 (default: 6).
+\fIcounter\fR is the initial counter if the HOTP algorithm is used (default: 0).
+\fItime window\fR is the time window used with TOTP in seconds (default: 30).
+.TP
+\fBnitrocli otp get \fIslot \fR[\fB-a\fR|\fB--algorithm \fIalgorithm\fR]
+Delete the name and the secret stored on a one-time password slot.
+\fIslot\fR is the number of the slot to generate the password on.
+\fIalgorithm\fR is the OTP algorithm to use.
+Possible values are \fBhotp\fR for the HOTP algorithm according to RFC 4226 and
+\fBtotp\fR for the TOTP algorithm according to RFC 6238 (default).
+.TP
+\fBnitrocli otp status \fR[\fB-a\fR|\fB--all\fR]
+List all OTP slots.
+If \fB--all\fR is not set, empty slots are ignored.
+
+.SH EXAMPLE
+.SS One-time passwords
+Configure a one-time password slot with a hexadecimal secret representation:
+    $ \fBnitrocli otp set 0 test-rfc4226 3132333435363738393031323334353637383930 --algorithm hotp\fR
+    $ \fBnitrocli otp set 1 test-foobar 666F6F626172 --algorithm hotp\fR
+.P
+Configure a one-time password slot with an ASCII secret representation:
+    $ \fBnitrocli otp set 0 test-rfc4226 12345678901234567890 --ascii --algorithm hotp\fR
+    $ \fBnitrocli otp set 1 test-foobar foobar --ascii --algorithm hotp\fR
+.P
+Generate a one-time password:
+    $ \fBnitrocli otp get 0 --algorithm hotp\fR
+    755224
+.P
+Clear a one-time password slot:
+    $ \fBnitrocli otp clear 0 --algorithm hotp\fR