diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/CONTRIBUTING.md | 23 | ||||
| -rw-r--r-- | doc/nitrocli.1 | 355 | ||||
| -rw-r--r-- | doc/nitrocli.1.pdf | bin | 0 -> 18442 bytes | |||
| -rw-r--r-- | doc/packaging.md | 64 |
4 files changed, 442 insertions, 0 deletions
diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md new file mode 100644 index 0000000..3ebdfce --- /dev/null +++ b/doc/CONTRIBUTING.md @@ -0,0 +1,23 @@ +The following rules generally apply for pull requests and code changes: + +**Submit Pull Requests to the `devel` branch** + +The `devel` branch is where experimental features reside. After some +soak time they may be ported over to `master` and a release will be cut +that includes them. + +**Keep documentation up-to-date** + +Please make an effort to keep the documentation up-to-date to the extent +possible and necessary for the change at hand. That includes adjusting +the [README](../README.md) and [`man` page](nitrocli.1) as well as +regenerating the PDF rendered version of the latter by running `make +doc`. + +**Blend with existing patterns and style** + +To keep the code as consistent as possible, please try not to diverge +from the existing style used in a file. Specifically for Rust source +code, use [`rustfmt`](https://github.com/rust-lang/rustfmt) and +[`clippy`](https://github.com/rust-lang/rust-clippy) to achieve a +minimum level of consistency and prevent known bugs, respectively. diff --git a/doc/nitrocli.1 b/doc/nitrocli.1 new file mode 100644 index 0000000..75f5960 --- /dev/null +++ b/doc/nitrocli.1 @@ -0,0 +1,355 @@ +.TH NITROCLI 1 2019-06-08 +.SH NAME +nitrocli \- access Nitrokey devices +.SH SYNOPSIS +.B nitrocli +[\fB\-m\fR|\fB\-\-model pro\fR|\fBstorage\fR] \fR[\fB\-v\fR|\fB\-\-verbose\fR] +[\fB\-V\fR|\fB\-\-version\fR] +\fIcommand\fR +[\fIarguments\fR] +.SH DESCRIPTION +\fBnitrocli\fR provides access to Nitrokey devices. +It supports the Nitrokey Pro and the Nitrokey Storage. +It can be used to access the encrypted volume, the one-time password generator, +and the password safe. +.SH OPTIONS +.TP +\fB\-m\fR, \fB\-\-model pro\fR|\fBstorage\fR +Restrict connections to the given device model. +If this option is not set, nitrocli will connect to any connected Nitrokey Pro +or Nitrokey Storage device. +.TP +\fB\-v\fR, \fB\-\-verbose\fR +Enable additional logging and control its verbosity. Logging enabled through +this option will appear on the standard error stream. This option can be +supplied multiple times. A single occurrence will show additional warnings. +Commands sent to the device will be shown when supplied three times and full +device communication is available with four occurrences. Supplying this option +five times enables the highest verbosity. +.TP +\fB\-V\fR, \fB\-\-version\fR +Print the nitrocli version and exit. +.SH COMMANDS +.SS General +.TP +.B nitrocli status +Print the status of the connected Nitrokey device, including the stick serial +number, the firmware version, and the PIN retry count. If the device is a +Nitrokey Storage, also print storage related information including the SD card +serial number, the encryption status, and the status of the volumes. +.TP +.B nitrocli lock +Lock the Nitrokey. +This command locks the password safe (see the Password safe section). On the +Nitrokey Storage, it will also close any active encrypted or hidden volumes (see +the Storage section). +.TP +.B nitrocli reset +Perform a factory reset on the Nitrokey. +This command performs a factory reset on the OpenPGP smart card, clears the +flash storage and builds a new AES key. +The user PIN is reset to 123456, the admin PIN to 12345678. + +This command requires the admin PIN. +To avoid accidental calls of this command, the user has to enter the PIN even +if it has been cached. + +.SS Storage +The Nitrokey Storage comes with a storage area. This area is comprised of an +\fIunencrypted\fR region and an \fIencrypted\fR one of fixed sizes, each made +available to the user in the form of block devices. The encrypted region can +optionally further be overlayed with up to four \fIhidden\fR volumes. Because of +this overlay (which is required to achieve plausible deniability of the +existence of hidden volumes), the burden of ensuring that data on the encrypted +volume does not overlap with data on one of the hidden volumes is on the user. +.TP +\fBnitrocli unencrypted set \fImode\fR +Change the read-write mode of the volume. +\fImode\fR is the type of the mode to change to: \fBread-write\fR to make the +volume readable and writable or \fBread-only\fR to make it only readable. +This command requires the admin PIN. + +Note that this command requires firmware version 0.51 or higher. Earlier +versions are not supported. +.TP +\fBnitrocli encrypted 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 +\fBnitrocli encrypted close +Close the encrypted volume on the Nitrokey Storage. +.TP +\fBnitrocli hidden create \fIslot\fR \fIstart\fR \fIend\fR +Create a new hidden volume inside the encrypted volume. \fIslot\fR must indicate +one of the four available slots. \fIstart\fR and \fIend\fR represent, +respectively, the start and end position of the hidden volume inside the +encrypted volume, as a percentage of the encrypted volume's size. +This command requires a password which is later used to look up the hidden +volume to open. Unlike a PIN, this password is not cached by \fBgpg\-agent\fR(1). +.TP +\fBnitrocli hidden open +Open a hidden volume. The volume to open is determined based on the password +entered, which must have a minimum of six characters. Only one hidden volume can +be active at any point in time and previously opened volumes will be +automatically closed. Similarly, the encrypted volume will be closed if it was +open. +.TP +\fBnitrocli hidden close +Close a hidden volume. + +.SS One-time passwords +The Nitrokey Pro and the Nitrokey Storage support the generation of one-time +passwords using the HOTP algorithm according to RFC 4226 or the TOTP algorithm +according to RFC 6238. +The required data \(en a name and the secret \(en is stored in slots. +Currently, the Nitrokey devices provide three HOTP slots and 15 TOTP slots. +The slots are numbered per algorithm starting at zero. +.P +The TOTP algorithm is a modified version of the HOTP algorithm that also uses +the current time. +Therefore, the Nitrokey clock must be synchronized with the clock of the +application that requests the one-time password. +.TP +\fBnitrocli otp get \fIslot \fR[\fB\-a\fR|\fB\-\-algorithm \fIalgorithm\fR] \ +\fB[\-t\fR|\fB\-\-time \fItime\fR] +Generate a one-time password. +\fIslot\fR is the number of the slot to generate the password from. +\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). +Per default, this commands sets the Nitrokey's time to the system time if the +TOTP algorithm is selected. +If \fB\-\-time\fR is set, it is set to \fItime\fR instead, which must be a Unix +timestamp (i.e., the number of seconds since 1970-01-01 00:00:00 UTC). +This command might require the user PIN (see the Configuration section). +.TP +\fBnitrocli otp set \fIslot name secret \ +\fR[\fB\-a\fR|\fB\-\-algorithm \fIalgorithm\fR] \ +[\fB\-d\fR|\fB\-\-digits \fIdigits\fR] [\fB\-c\fR|\fB\-\-counter \fIcounter\fR] \ +[\fB\-t\fR|\fB\-\-time-window \fItime-window\fR] \ +[\fB-f\fR|\fB\-\-format ascii\fR|\fBbase32\fR|\fBhex\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 in that slot. + +The \fB\-\-format\fR option specifies the format of the secret. +If it is set to \fBascii\fR, each character of the given secret is interpreted +as the ASCII code of one byte. +If it is set to \fBbase32\fR, the secret is interpreted as a base32 string +according to RFC 4648. +If it is set to \fBhex\fR, every two characters are interpreted as the +hexadecimal value of one byte. +The default value is \fBhex\fR. + +\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 clear \fIslot \fR[\fB\-a\fR|\fB\-\-algorithm \fIalgorithm\fR] +Delete the name and the secret stored in a one-time password slot. +\fIslot\fR is the number of the slot to clear. +\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. + +.SS Configuration +Nitrokey devices have four configuration settings: the numlock, capslock and +scrollock keys can be mapped to an HOTP slot, and OTP generation can be set to +require the user PIN. +.TP +\fBnitrocli config get\fR +Print the current configuration. +.TP +\fBnitrocli config set \fR\ +[[\fB\-n\fR|\fB\-\-numlock \fIslot\fR] | [\fB\-N\fR|\fB\-\-no\-numlock\fR]] \ +[[\fB\-c\fR|\fB\-\-capslock \fIslot\fR] | [\fB\-C\fR|\fB\-\-no\-capslock\fR]] \ +[[\fB\-s\fR|\fB\-\-scrollock \fIslot\fR] | [\fB\-S\fR|\fB\-\-no\-scrollock\fR]] \ +[[\fB\-o\fR|\fB\-\-otp\-pin\fR] | [\fB\-O\fR|\fB\-\-no\-otp\-pin\fR]] +Update the Nitrokey configuration. +This command requires the admin PIN. + +With the \fB\-\-numlock\fR, \fB\-\-capslock\fR and \fB\-\-scrollock\fR options, +the respective bindings can be set. +\fIslot\fR is the number of the HOTP slot to bind the key to. +If \fB\-\-no\-numlock\fR, \fB\-\-no\-capslock\fR or \fB\-\-no\-scrollock\fR is +set, the respective binding is disabled. +The two corresponding options are mutually exclusive. + +If \fB\-\-otp\-pin\fR is set, the user PIN will be required to generate one-time +passwords using the \fBotp get\fR command. +If \fB\-\-no\-otp\-pin\fR is set, OTP generation can be performed without PIN. +These two options are mutually exclusive. + +.SS Password safe +The Nitrokey Pro and the Nitrokey Storage provide a password safe (PWS) with 20 +slots. +In each of these slots you can store a name, a login, and a password. +The PWS is not encrypted, but it is protected with the user PIN by the firmware. +Once the PWS is unlocked by one of the commands listed below, it can be +accessed without authentication. +You can use the \fBlock\fR command to lock the password safe. +.TP +\fBnitrocli pws get \fIslot \fR[\fB\-n\fR|\fB\-\-name\fR] \ +[\fB\-l\fR|\fB\-\-login\fR] \ +[\fB\-p\fR|\fB\-\-password\fR] \ +[\fB\-q\fR|\fB\-\-quiet\fR] +Print the content of one PWS slot. +\fIslot\fR is the number of the slot. +Per default, this command prints the name, the login and the password (in that +order). +If one or more of the options \fB\-\-name\fR, \fB\-\-login\fR, and +\fB\-\-password\fR are set, only the selected fields are printed. +The order of the fields never changes. + +The fields are printed together with a label. +Use the \fB\-\-quiet\fR option to suppress the labels and to only output the +values stored in the PWS slot. +.TP +\fBnitrocli pws set \fIslot name login password\fR +Set the content of a PWS slot. +\fIslot\fR is the number of the slot to write. +\fIname\fR, \fIlogin\fR, and \fIpassword\fR represent the data to write to the +slot. +.TP +\fBnitrocli pws clear \fIslot\fR +Delete the data stored in a PWS slot. +\fIslot\fR is the number of the slot clear. +.TP +\fBnitrocli pws status \fR[\fB\-a\fR|\fB\-\-all\fR] +List all PWS slots. +If \fB\-\-all\fR is not set, empty slots are ignored. + +.SS PINs +Nitrokey devices have two PINs: the user PIN and the admin PIN. The user +PIN must have at least six, the admin PIN at least eight characters. The +user PIN is required for commands such as \fBotp get\fR (depending on +the configuration) and for all \fBpws\fR commands. +The admin PIN is usually required to change the device configuration. +.P +Each PIN has a retry counter that is decreased with every wrong PIN entry and +reset if the PIN was entered correctly. +The initial retry counter is three. +If the retry counter for the user PIN is zero, you can use the +\fBpin unblock\fR command to unblock and reset the user PIN. +If the retry counter for the admin PIN is zero, you have to perform a factory +reset using the \fBreset\fR command or \fBgpg\fR(1). +Use the \fBstatus\fR command to check the retry counters. +.TP +.B nitrocli pin clear +Clear the PINs cached by the other commands. Note that cached PINs are +associated with the device they belong to and the \fBclear\fR command will only +clear the PIN for the currently used device, not all others. +.TP +\fBnitrocli pin set \fItype\fR +Change a PIN. +\fItype\fR is the type of the PIN that will be changed: \fBadmin\fR to change +the admin PIN or \fBuser\fR to change the user PIN. +This command only works if the retry counter for the PIN type is at least one. +(Use the \fBstatus\fR command to check the retry counters.) +.TP +.B nitrocli pin unblock +Unblock and reset the user PIN. +This command requires the admin PIN. +The admin PIN cannot be unblocked. +This operation is equivalent to the unblock PIN option provided by \fBgpg\fR(1) +(using the \fB\-\-change\-pin\fR option). + +.SH ENVIRONMENT +The program honors a set of environment variables that can be used to +suppress interactive PIN entry through \fBpinentry\fR(1). The following +variables are recognized: +.TP +.B NITROCLI_ADMIN_PIN +The admin PIN to use. +.TP +.B NITROCLI_USER_PIN +The user PIN to use. +.TP +.B NITROCLI_NEW_ADMIN_PIN +The new admin PIN to set. This variable is only used by the \fBpin set\fR +command for the \fBadmin\fR type. +.TP +.B NITROCLI_NEW_USER_PIN +The new user PIN to set. This variable is only used by the \fBpin set\fR command +for the \fBuser\fR type. +.TP +.B NITROCLI_PASSWORD +A password used by commands that require one (e.g., \fBhidden open\fR). +.TP +.B NITROCLI_NO_CACHE +If this variable is present in the environment, do not cache any inquired +secrets using \fBgpg\-agent\fR(1) but ask for them each time they are needed. +Note that this variable does not cause any cached secrets to be cleared. If a +secret is already in the cache it will be ignored, but left otherwise untouched. +Use the \fBpin clear\fR command to clear secrets from the cache. + +.SH EXAMPLES +.SS Storage +Create a hidden volume in the first available slot, starting at half the size of +the encrypted volume (i.e., 50%) and stretching all the way to its end (100%): + $ \fBnitrocli hidden create 0 50 100\fR + +.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 + $ \fBnitrocli otp set 0 test\-rfc6238 3132333435363738393031323334353637383930 \-\-algorithm totp \-\-digits 8\fR +.P +Configure a one-time password slot with an ASCII secret representation: + $ \fBnitrocli otp set 0 test\-rfc4226 12345678901234567890 \-\-format ascii \-\-algorithm hotp\fR + $ \fBnitrocli otp set 1 test\-foobar foobar \-\-format ascii \-\-algorithm hotp\fR + $ \fBnitrocli otp set 0 test\-rfc6238 12345678901234567890 \-\-format ascii \-\-algorithm totp \-\-digits 8\fR +.P +Configure a one-time password slot with a base32 secret representation: + $ \fBnitrocli otp set 0 test\-rfc4226 gezdgnbvgy3tqojqgezdgnbvgy3tqojq \-\-format base32 \-\-algorithm hotp\fR + $ \fBnitrocli otp set 1 test\-foobar mzxw6ytboi====== \-\-format base32 \-\-algorithm hotp\fR + $ \fBnitrocli otp set 0 test\-rfc6238 gezdgnbvgy3tqojqgezdgnbvgy3tqojq \-\-format base32 \-\-algorithm totp \-\-digits 8\fR +.P +Generate a one-time password: + $ \fBnitrocli otp get 0 \-\-algorithm hotp\fR + 755224 + $ \fBnitrocli otp get 0 \-\-algorithm totp \-\-time 1234567890\fR + 89005924 +.P +Clear a one-time password slot: + $ \fBnitrocli otp clear 0 \-\-algorithm hotp\fR + +.SS Configuration +Query the configuration: + $ \fBnitrocli config get\fR + Config: + numlock binding: not set + capslock binding: not set + scrollock binding: not set + require user PIN for OTP: true +.P +Change the configuration: + $ \fBnitrocli config set \-\-otp\-pin\fR + +.SS Password safe +Configure a PWS slot: + $ \fBnitrocli pws set 0 example.org john.doe passw0rd\fR + +Get the data from a slot: + $ \fBnitrocli pws get 0\fR + name: example.org + login: john.doe + password: passw0rd + +Copy the password to the clipboard (requires \fBxclip\fR(1)). + $ \fBnitrocli pws get 0 \-\-password \-\-quiet | xclip \-in\fR + +Query the PWS slots: + $ \fB nitrocli pws status\fR + slot name + 0 example.org diff --git a/doc/nitrocli.1.pdf b/doc/nitrocli.1.pdf Binary files differnew file mode 100644 index 0000000..cd15a66 --- /dev/null +++ b/doc/nitrocli.1.pdf diff --git a/doc/packaging.md b/doc/packaging.md new file mode 100644 index 0000000..5ff4089 --- /dev/null +++ b/doc/packaging.md @@ -0,0 +1,64 @@ +How to package nitrocli +======================= + +This document describes how to update the packaged versions of nitrocli. + +Arch Linux +---------- + +1. Clone the Git repository at ssh://aur@aur.archlinux.org/nitrocli.git. +2. Edit the `PKGBUILD` file: + - Update the `pkgver` variable to the current nitrocli version. + - If the `pkgrel` variable is not 1, set it to 1. + - Update the SHA512 hash in the `sha512sums` variable for the new tarball. +3. Update the `.SRCINFO` file by running `makepkg --printsrcinfo > .SRCINFO`. +4. Verify that the package builds successfully by running `makepkg`. +5. Verify that the package was built as expected by running `pacman -Qlp $f` + and `pacman -Qip $f`, where `$f` is `nitrocli-$pkgver.pkg.tar.gz`. +6. Check the package for errors by running `namcap PKGBUILD` and `namcap + nitrocli-$pkgver.pkg.tar.gz`. +7. Add, commit, and push your changes to publish them in the AUR. + +If you have to release a new package version without a new nitrocli version, +do not change the `pkgver` variable and instead increment the `pkgrel` +variable. + +For more information, see the [Arch User Repository][] page in the Arch Wiki. + +Debian +------ + +1. Clone or fork the Git repository at + https://salsa.debian.org/rust-team/debcargo-conf. +2. Execute `./update.sh nitrocli`. +3. Check and, if necessary, update the Debian changelog in the file + `src/nitrocli/debian/changelog`. +4. Verify that the package builds successfully by running `./build.sh nitrocli` + in the `build` directory. (This requires an `sbuild` environment as + described in the `README.rst` file.) +5. Inspect the generated package by running `dpkg-deb --info` and `dpkg-deb + --contents` on it. +6. If you have push access to the repository, create the + `src/nitrocli/debian/RFS` file to indicate that `nitrocli` can be updated. +7. Add and commit your changes. If you have push access, push them. + Otherwise create a merge request and indicate that `nitrocli` is ready for + upload in its description. + +For more information, see the [Teams/RustPackaging][] page in the Debian Wiki +and the [README.rst file][] in the debcargo-conf repository. + +For detailed information on the status of the Debian package, check the [Debian +Package Tracker][]. + +Ubuntu +------ + +The `nitrocli` package for Ubuntu is automatically generated from the Debian +package. For detailed information on the status of the Ubuntu package, check +[Launchpad][]. + +[Arch User Repository]: https://wiki.archlinux.org/index.php/Arch_User_Repository +[Teams/RustPackaging]: https://wiki.debian.org/Teams/RustPackaging +[README.rst file]: https://salsa.debian.org/rust-team/debcargo-conf/blob/master/README.rst +[Debian Package Tracker]: https://tracker.debian.org/pkg/rust-nitrocli +[Launchpad]: https://launchpad.net/ubuntu/+source/rust-nitrocli |