From 8185f1652668b71ada7cd4b32d92de2c752f0a1b Mon Sep 17 00:00:00 2001 From: Robin Krahl Date: Thu, 27 Dec 2018 22:41:06 +0100 Subject: Document the otp commands This patch adds the otp commands to the README and describes them in the nitrocli(1) man page. --- nitrocli/README.md | 7 ++++- nitrocli/doc/nitrocli.1 | 77 +++++++++++++++++++++++++++++++++++++++++++------ 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 -- cgit v1.2.3