aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--nitrocli/README.md7
-rw-r--r--nitrocli/doc/nitrocli.177
2 files changed, 74 insertions, 10 deletions
diff --git a/nitrocli/README.md b/nitrocli/README.md
index 2beee00..946df21 100644
--- a/nitrocli/README.md
+++ b/nitrocli/README.md
@@ -14,7 +14,12 @@ The following commands are currently supported:
- open: Open the encrypted volume. The user PIN needs to be entered.
- close: Close the encrypted volume.
- status: Report status information about the Nitrokey.
-- clear: Remove the user PIN from gpg-agent's cache.
+- clear: Remove the user and admin PIN from gpg-agent's cache.
+- otp: Access one-time passwords (OTP).
+ - get: Generate a one-time password.
+ - set: Set an OTP slot.
+ - status: List all OTP slots.
+ - clear: Delete an OTP slot.
### *Note:*
----------------------------------------------------------------------
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