man8: ip-sr: Document that passphrase must be high-entropy

'ip sr hmac set' takes a newline-terminated "passphrase", but it fails
to stretch it.  The "passphrase" actually gets used directly as the key.
This makes it difficult to use securely.

I recommend deprecating this command and replacing it with a command
that either stretches the passphrase or explicitly takes a key instead
of a passphrase.  But for now, let's at least document this pitfall.

Signed-off-by: Eric Biggers <ebiggers@kernel.org>
Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>

diff --git a/man/man8/ip-sr.8 b/man/man8/ip-sr.8
index 6be1cc54902f4120de86506d6b9381750ee20604..962fb0d1305bbbd076ae06ee7ac989d7c2e365c0 100644 (file)
--- a/man/man8/ip-sr.8
+++ b/man/man8/ip-sr.8
@@ -34,9 +34,17 @@ Those parameters include the mapping between an HMAC key ID and its associated
 hashing algorithm and secret, and the IPv6 address to use as source for encapsulated
 packets.
 .PP
-The \fBip sr hmac set\fR command prompts for a passphrase that will be used as the
-HMAC secret for the corresponding key ID. A blank passphrase removes the mapping.
-The currently supported algorithms for \fIALGO\fR are \fBsha1\fR and \fBsha256\fR.
+The \fBip sr hmac set\fR command prompts for a newline-terminated "passphrase"
+that will be used as the HMAC secret for the corresponding key ID. This
+"passphrase" is \fInot\fR stretched, and it is used directly as the HMAC key.
+Therefore it \fImust\fR have enough entropy to be used as a key. For example, a
+correct use would be to use a passphrase that was generated using
+\fBhead\~-c\~32\~/dev/random\~|\~base64\~-w\~0\fR.
+.PP
+A blank "passphrase" removes the mapping.
+.PP
+The currently supported algorithms for \fIALGO\fR are \fBsha1\fR and
+\fBsha256\fR.
 .PP
 If the tunnel source is set to the address :: (which is the default), then an address
 of the egress interface will be selected. As this operation may hinder performances,
@@ -54,5 +62,9 @@ it is recommended to set a non-default address.
 .SH SEE ALSO
 .br
 .BR ip-route (8)
+
+.SH BUGS
+\fBip sr hmac set\fR does not stretch the passphrase.
+
 .SH AUTHOR
 David Lebrun <david.lebrun@uclouvain.be>