Document the pws commands

This patch adds documentation and examples for the pws commands to the
README and to the man page.

2 files changed, 64 insertions, 1 deletions

diff --git a/nitrocli/README.md b/nitrocli/README.md
index 308fbf2..96ae3a5 100644
--- a/nitrocli/README.md
+++ b/nitrocli/README.md
@@ -28,6 +28,11 @@ The following commands are currently supported:
   - clear: Remove the user and admin PIN from gpg-agent's cache.
   - set: Change the admin or the user PIN.
   - unblock: Unblock and reset the user PIN.
+- pws: Access the password safe (PWS).
+  - get: Query the data on a PWS slot.
+  - set: Set the data on a PWS slot.
+  - status: List all PWS slots.
+  - clear: Delete a PWS slot.
 
 
 Usage
diff --git a/nitrocli/doc/nitrocli.1 b/nitrocli/doc/nitrocli.1
index 4e59352..fc993f1 100644
--- a/nitrocli/doc/nitrocli.1
+++ b/nitrocli/doc/nitrocli.1
@@ -8,7 +8,8 @@ nitrocli \- access Nitrokey devices
 .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 and the one-time password generator.
+It can be used to access the encrypted volume, the one-time password generator,
+and the password safe.
 .SH COMMANDS
 .SS General
 .TP
@@ -118,6 +119,45 @@ 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
@@ -186,3 +226,21 @@ Query the configuration:
 .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