On Wed, Nov 01, 2017 at 03:05:44AM +0100, Daniel Kahn Gillmor wrote:
> Package: e2fsprogs
> Version: 1.43.7-1
> Severity: normal
>
> e4crypt(8) says:
>
> e4crypt add_key -S [ -k keyring ] [-v] [-q] [ path ... ]
>
> but "e4crypt add_key -h" says:
>
> e4crypt add_key -S salt [ -k keyring ] [-v] [-q] [ path ... ]
>
> (note that presence of salt).
>
> neither of these documentation locations describes what format the
> salt should take, or whether it references any particular type of
> salt.
>
> Please make the documentation match the executable!
Thanks for the bug report. I've checked in a fix and a man page
update will be in the next release of e2fsprogs.
- Ted
commit 18e921a5a0916159742c2ba6a8d7191db590d44c
Author: Theodore Ts'o <ty...@mit.edu>
Date: Mon Jan 1 16:29:56 2018 -0500
Add documentation for e4crypt's add_key command in the man page
Correctly document that the -S option takes an argument, and describe
what arguments to the -S, -k, and -p options.
Addresses-Debian-Bug: #880483
Signed-off-by: Theodore Ts'o <ty...@mit.edu>
diff --git a/misc/e4crypt.8.in b/misc/e4crypt.8.in
index 169ab587d..75b968a0f 100644
--- a/misc/e4crypt.8.in
+++ b/misc/e4crypt.8.in
@@ -14,14 +14,41 @@ e4crypt \- ext4 filesystem encryption utility
performs encryption management for ext4 file systems.
.SH COMMANDS
.TP
-.B e4crypt add_key -S \fR[\fB -k \fIkeyring\fR ] [\fB-v\fR] [\fB-q\fR] \fR[\fB
-p \fIpad\fR ] [ \fIpath\fR ... ]
+.B e4crypt add_key \fR[\fB-vq\fR] [\fB-S\fI salt\fR ] [\fB-k \fIkeyring\fR ]
[\fB -p \fIpad\fR ] [ \fIpath\fR ... ]
Prompts the user for a passphrase and inserts it into the specified
keyring. If no keyring is specified, e4crypt will use the session
keyring if it exists or the user session keyring if it does not.
.IP
+The
+.I salt
+argument is interpreted in a number of different ways, depending on how
+its prefix value. If the first two characters are "s:", then the rest
+of the argument will be used as an text string and used as the salt
+value. If the first two characters are "0x", then the rest of the
+argument will be parsed as a hex string as used as the salt. If the
+first characters are "f:" then the rest of the argument will be
+interpreted as a filename from which the salt value will be read. If
+the string begins with a '/' character, it will similarly be treated as
+filename. Finally, if the
+.I salt
+argument can be parsed as a valid UUID, then the UUID value will be used
+as a salt value.
+.IP
+The
+.I keyring
+argument specifies the keyring to which the key should be added.
+.IP
+The
+.I pad
+value specifies the number of bytes of padding will be added to
+directory names for obfuscation purposes. Valid
+.I pad
+values are 4, 8, 16, and 32.
+.IP
If one or more directory paths are specified, e4crypt will try to
-set the policy of those directories to use the key just entered by
-the user.
+set the policy of those directories to use the key just added by the
+.B add_key
+command.
.TP
.B e4crypt get_policy \fIpath\fR ...
Print the policy for the directories specified on the command line.
