updated manual to reflect final stage of gpg asymmetric encryption

doc/tomb.1

@@ -37,17 +37,18 @@ low-quality random data (/dev/urandom).
 .B
 .IP "forge"
 Creates a new \fIkey\fR and prompts the user for a \fIpassword\fR to
-protect its usage. This operation requires high quality random data
+protect its usage using symmetric encryption. This operation requires
-(/dev/random) which can take quite some time to be gathered on a
+high quality random data using /dev/random and can take long when run
-server: it works better on a desktop where the mouse can be moved
+on a server with low entropy. The \fI-g\fR option switches on the use
-around for entropy. The default cipher to protect the key is AES256, a
+of a GPG key instead of a password (asymmetric encryption), then the
-custom one can be specified using the \fI-o\fR option, for a list of
+\fI-r\fR option indicates the recipient key; more recipient GPG ids
+can be indicated (comma separated) if the option is followed by the
+\fI--shared\fR flag. The default cipher to protect the key is AES256,
+a custom one can be specified using the \fI-o\fR option, for a list of
 supported ciphers use \fI-v\fR. For additional protection against
-dictionary attacks on keys, the (experimental) \fI--kdf\fR option can
+dictionary attacks on keys, the \fI--kdf\fR option can be used when
-be used when forging a key, making sure that the \fItomb-kdb-pbkdf2\fR
+forging a key, making sure that the \fItomb-kdb-pbkdf2\fR binaries in
-binaries in \fIextras/kdf\fR were compiled and installed on the
+\fIextras/kdf\fR were compiled and installed on the system.
-system. Use the \fI-r\fR option to encrypt the key with a GPG key
-instead of a password.
 
 .B
 .IP "lock"
@@ -55,25 +56,27 @@ Initializes and locks an empty tomb (made with \fIdig\fR) using a key
 (made with \fIforge\fR), making it ready for usage. After this
 operation, the tomb can only be opened in possession of the key and
 knowing its password. As in any other command requiring a key, the
-option \fI-k\fR should be used to specify a key file. The \fI-o\fR
+option \fI-k\fR should be used to specify a key file; in case of
+encryption to GPG recipients the \fI-g\fR flag should be used followed
+by \fI-r\fR and the recipient's secret GPG key id.  The \fI-o\fR
 option can be used to specify the cipher specification: default is
-"aes-xts-plain64:sha256", old versions of Tomb used "aes-cbc-essiv:sha256".
+"aes-xts-plain64:sha256", old versions of Tomb used
-If you are looking for something exotic, also try "serpent-xts-plain64".
+"aes-cbc-essiv:sha256".  If you are looking for something exotic, also
-More options may be found in cryptsetup(8) and Linux documentation.
+try "serpent-xts-plain64".  More options may be found in cryptsetup(8)
-This operation requires root privileges to loopback mount, format the tomb (using
+and Linux documentation.  This operation requires root privileges to
-LUKS and Ext4), then set the key in its first LUKS slot. Use the \fI-r\fR
+loopback mount, format the tomb (using LUKS and Ext4), then set the
-option to lock the tomb using a GPG key.
+key in its first LUKS slot.
 
 .B
 .IP "open"
-Opens an existing \fI.tomb\fR (first argument) using a key (\fI-k\fR)
+Opens an existing \fItomb file\fR (first argument) using a key
-which can also be an \fIjpeg image\fR (see
+(\fI-k\fR) which can also be an \fIjpeg image\fR (see
 \fIbury\fR/\fIexhume\fR). If a second argument is given it will
 indicate the \fImountpoint\fR where the tomb should be made
 accessible, else the tomb is mounted in a directory inside /media (if
 not available it uses /run/media/$USER).  The option \fI-o\fR can be
-used to pass mount(8) options (default: rw,noatime,nodev). Use the
+used to pass mount(8) options (default: rw,noatime,nodev). The
-\fI-r\fR option to open the tomb using a GPG key.
+\fI-g\fR option is needed when using GPG encryption to recipients.
 
 .B
 .IP "list"
@@ -122,21 +125,25 @@ situations. It requires \fIlsof\fR else it falls back to \fIclose\fR.
 .B
 .IP "passwd"
 Changes the password protecting a key file specified using
-\fI-k\fR. The user will need to know the key's current password, then
+\fI-k\fR. With keys encrypted for GPG recipients use \fI-g\fR followed
-its content will be decoded and reencoded using the new one. This
+by \fI-r\fR to indicate the new recipient key, or a comma separated
-action can't be forced if the current password is not known. If the
+list followed by the \fI--shared\fR flag if more than one. The user
+will need to know the key's current password, or possess at least one
+of the current recipients GPG secret keys, because the key contents
+will be decoded and reencoded using the new passwords or keys. If the
 key file is broken (missing headers) this function also attempts its
-recovery. Use the \fI-r\fR option to unlock the tomb using your old
+recovery.
-GPG key and the \fI-R\fR option to provide the new GPG key.
 
 .B
 .IP "setkey"
 Changes the key file that locks a tomb, substituting the old one with
 a new one. Both the old and the new key files are needed for this
-operation and their passwords must be known. The new key must be
+operation and their passwords or GPG recipient(s) secret keys must be
-specified using the \fI-k\fR option, the first argument should be the old
+available. The new key must be specified using the \fI-k\fR option,
-key and the second and last argument the tomb file. Use the \fI-r\fR
+the first argument should be the old key and the second and last
-option to unlock the tomb with a GPG key.
+argument the tomb file. Use the \fI-g\fR option to unlock the tomb
+with a GPG key, the \fI-r\fR to indicate the recipient and the
+\fI--shared\fR option if encrypting for more than one recipient.
 
 .B
 .IP "resize"
@@ -163,8 +170,9 @@ Hides a tomb key (\fI-k\fR) inside a \fIjpeg image\fR (first argument)
 using \fIsteganography\fR: the image will change in a way that cannot
 be noticed by human eye and hardly detected by data analysis. This
 option is useful to backup tomb keys in unsuspected places; it depends
-from the availability of \fIsteghide\fR. Use the \fI-r\fR
+from the availability of \fIsteghide\fR. Use the \fI-g\fR flag and
-option to unlock the tomb with a GPG key.
+\fI-r\fR option followed by recipient id to use GPG asymmetric
+encryption.
 
 .B
 .IP "exhume"
@@ -206,20 +214,19 @@ what you are doing if you force an operation.
 When digging or resizing a tomb, this option must be used to specify
 the \fIsize\fR of the new file to be created. Units are megabytes (MiB).
 .B
-.IP "-r \fI<gpg_id>[,<gpg_id2>]\fR"
+.IP "-g"
-Tell tomb to use a asymmetric GnuPG key instead of a passphrase to
+Tell tomb to use a asymmetric GnuPG key encryption instead of a
-encrypt a tomb key. \fIgpg_id\fR is the key recipient in your GPG
+symmetric passphrase to protect a tomb key. This option can be followed by \fI-r\fR when the command needs to specify recipient(s) and by the \fI--shared\fR flag when recipients are more than one.
-database, you must hold both the public and the private key. If more
-than one recipient is present the --shared flag must be present.
-The recipients are separed by a ','.
 .B
-.IP "-R \fI<gpg_id>[,<gpg_id2>]\fR"
+.IP "-r \fI<gpg_id>[,<gpg_id2>]\fR"
-Provide a new set of recipient to encrypt a tomb key. This option is
+Provide a new set of recipient to encrypt a tomb key. \fIgpg_ids\fR
-only used in the \fIpasswd\fR command.
+can be one or more (comma separated), if more than one recipient is
+present the --shared flag must be present.
 .B
 .IP "--shared"
-Activate the capability to share a tomb. This flag must be enabled
+Activate the capability to share an asymmetrically encrypted tomb key
-when using the \fI-r\fR option with more than one recipient.
+among multiple recipients. When this flag is enabled the \fI-r\fR
+option should indicate more than one recipient, comma separated.
 .B
 .IP "--kdf \fI<itertime>\fR"
 Activate the KDF feature against dictionary attacks when creating a