[PATCH iproute2-next] man8: ip-sr: Document that passphrase must be high-entropy

[PATCH iproute2-next] man8: ip-sr: Document that passphrase must be high-entropy

[Eric Biggers]

'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>
---
 man/man8/ip-sr.8 | 20 ++++++++++++++++----
 1 file changed, 16 insertions(+), 4 deletions(-)

diff --git a/man/man8/ip-sr.8 b/man/man8/ip-sr.8
index 6be1cc54..78a87646 100644
--- a/man/man8/ip-sr.8
+++ b/man/man8/ip-sr.8
@@ -1,6 +1,6 @@
-.TH IP\-SR 8 "14 Apr 2017" "iproute2" "Linux"
+.TH IP\-SR 8 "15 Aug 2025" "iproute2" "Linux"
 .SH "NAME"
 ip-sr \- IPv6 Segment Routing management
 .SH SYNOPSIS
 .sp
 .ad l
@@ -32,13 +32,21 @@ internal parameters.
 .PP
 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
+\fBtr -dC a-z < /dev/random | head -c 32\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,
 it is recommended to set a non-default address.
 
@@ -52,7 +60,11 @@ it is recommended to set a non-default address.
 .nf
 # ip sr tunsrc set 2001:db8::1
 .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>

base-commit: 0ad8fef322365b7bafd052f416fc972bea49d362
-- 
2.50.1

Re: [PATCH iproute2-next] man8: ip-sr: Document that passphrase must be high-entropy

[Eric Biggers]

On Fri, Aug 15, 2025 at 08:01:29PM -0700, Eric Biggers wrote:
> '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>
> ---
>  man/man8/ip-sr.8 | 20 ++++++++++++++++----
>  1 file changed, 16 insertions(+), 4 deletions(-)

Sorry, please disregard this version.  I had a (small) unstaged change
that I meant to include.  I'll send v2 with it included.

- Eric