diff options
Diffstat (limited to 'nitrocli/doc')
| -rw-r--r-- | nitrocli/doc/CONTRIBUTING.md | 23 | ||||
| -rw-r--r-- | nitrocli/doc/nitrocli.1 | 355 | ||||
| -rw-r--r-- | nitrocli/doc/nitrocli.1.pdf | bin | 18442 -> 0 bytes | |||
| -rw-r--r-- | nitrocli/doc/packaging.md | 58 |
4 files changed, 0 insertions, 436 deletions
diff --git a/nitrocli/doc/CONTRIBUTING.md b/nitrocli/doc/CONTRIBUTING.md deleted file mode 100644 index 3ebdfce..0000000 --- a/nitrocli/doc/CONTRIBUTING.md +++ /dev/null @@ -1,23 +0,0 @@ -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/nitrocli/doc/nitrocli.1 b/nitrocli/doc/nitrocli.1 deleted file mode 100644 index 75f5960..0000000 --- a/nitrocli/doc/nitrocli.1 +++ /dev/null @@ -1,355 +0,0 @@ -.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/nitrocli/doc/nitrocli.1.pdf b/nitrocli/doc/nitrocli.1.pdf Binary files differdeleted file mode 100644 index cd15a66..0000000 --- a/nitrocli/doc/nitrocli.1.pdf +++ /dev/null diff --git a/nitrocli/doc/packaging.md b/nitrocli/doc/packaging.md deleted file mode 100644 index 7ed302a..0000000 --- a/nitrocli/doc/packaging.md +++ /dev/null @@ -1,58 +0,0 @@ -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, update the `TODO.rst` 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. - -Ubuntu ------- - -The `nitrocli` package for Ubuntu is automatically generated from the Debian -package. - -[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 |