The branch stable/12 has been updated by jhb:
URL:
https://cgit.FreeBSD.org/src/commit/?id=6aaf8a8b1bcf500aa7342043d43007ff9c52cd65
commit 6aaf8a8b1bcf500aa7342043d43007ff9c52cd65
Author: John Baldwin <j...@freebsd.org>
AuthorDate: 2022-04-27 19:18:52 +0000
Commit: John Baldwin <j...@freebsd.org>
CommitDate: 2022-05-20 00:42:24 +0000
setkey(8): Clarify language around AEAD ciphers.
AEAD ciphers for IPsec combine both encryption and authentication. As
such, ESP configurations using an AEAD cipher should not use a
seperate authentication algorithm via -A. However, this was not
apparent from the setkey manpage and 12.x and earlier did not perform
sufficient argument validation permitting users to pair an explicit -A
such as SHA256-HMAC with AES-GCM. (The result was a non-standard
combination of AES-CTR with the specified MAC, but with the wrong
initial block counter (and thus different keystream) compared to using
AES-CTR as the cipher.)
Attempt to clarify this in the manpage by explicitly calling out AEAD
ciphers (currently only AES-GCM) and noting that AEAD ciphers should
not use -A.
While here, explicitly note which authentication algorithms can be
used with esp vs esp-old. Also add subsection headings for the
different algorithm lists and tidy some language.
I did not convert the tables to column lists (Bl -column) though that
would probably be more correct than using literal blocks (Bd
-literal).
PR: 263379
Reviewed by: Pau Amma <paua...@gundo.com>, markj
Differential Revision: https://reviews.freebsd.org/D34947
(cherry picked from commit e6dede145616ed8f98c629c23a2ba206b812c921)
---
sbin/setkey/setkey.8 | 74 ++++++++++++++++++++++++++++------------------------
1 file changed, 40 insertions(+), 34 deletions(-)
diff --git a/sbin/setkey/setkey.8 b/sbin/setkey/setkey.8
index a9653a3b25d4..38e04aa412ed 100644
--- a/sbin/setkey/setkey.8
+++ b/sbin/setkey/setkey.8
@@ -29,7 +29,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd June 4, 2020
+.Dd April 27, 2022
.Dt SETKEY 8
.Os
.\"
@@ -328,7 +328,8 @@ Specify hard/soft life time duration of the SA.
.It Ar algorithm
.Bl -tag -width Fl -compact
.It Fl E Ar ealgo Ar key
-Specify an encryption algorithm
+Specify an encryption or Authenticated Encryption with Associated Data
+(AEAD) algorithm
.Ar ealgo
for ESP.
.It Xo
@@ -573,13 +574,9 @@ for details.
.El
.\"
.Sh ALGORITHMS
-The following list shows the supported algorithms.
-The
-.Sy protocol
-and
-.Sy algorithm
-are almost completely orthogonal.
-The following list of authentication algorithms can be used as
+The following lists show the supported algorithms.
+.Ss Authentication Algorithms
+The following authentication algorithms can be used as
.Ar aalgo
in the
.Fl A Ar aalgo
@@ -588,29 +585,29 @@ of the
parameter:
.Bd -literal -offset indent
algorithm keylen (bits) comment
-hmac-md5 128 ah: rfc2403
- 128 ah-old: rfc2085
-hmac-sha1 160 ah: rfc2404
- 160 ah-old: 128bit ICV (no document)
-keyed-md5 128 ah: 96bit ICV (no document)
- 128 ah-old: rfc1828
-keyed-sha1 160 ah: 96bit ICV (no document)
- 160 ah-old: 128bit ICV (no document)
+hmac-md5 128 ah/esp: rfc2403
+ 128 ah-old/esp-old: rfc2085
+hmac-sha1 160 ah/esp: rfc2404
+ 160 ah-old/esp-old: 128bit ICV (no document)
+keyed-md5 128 ah/esp: 96bit ICV (no document)
+ 128 ah-old/esp-old: rfc1828
+keyed-sha1 160 ah/esp: 96bit ICV (no document)
+ 160 ah-old/esp-old: 128bit ICV (no document)
null 0 to 2048 for debugging
-hmac-sha2-256 256 ah: 128bit ICV (RFC4868)
- 256 ah-old: 128bit ICV (no document)
-hmac-sha2-384 384 ah: 192bit ICV (RFC4868)
- 384 ah-old: 128bit ICV (no document)
-hmac-sha2-512 512 ah: 256bit ICV (RFC4868)
- 512 ah-old: 128bit ICV (no document)
-hmac-ripemd160 160 ah: 96bit ICV (RFC2857)
- ah-old: 128bit ICV (no document)
-aes-xcbc-mac 128 ah: 96bit ICV (RFC3566)
- 128 ah-old: 128bit ICV (no document)
+hmac-sha2-256 256 ah/esp: 128bit ICV (RFC4868)
+ 256 ah-old/esp-old: 128bit ICV (no document)
+hmac-sha2-384 384 ah/esp: 192bit ICV (RFC4868)
+ 384 ah-old/esp-old: 128bit ICV (no document)
+hmac-sha2-512 512 ah/esp: 256bit ICV (RFC4868)
+ 512 ah-old/esp-old: 128bit ICV (no document)
+hmac-ripemd160 160 ah/esp: 96bit ICV (RFC2857)
+ ah-old/esp-old: 128bit ICV (no document)
+aes-xcbc-mac 128 ah/esp: 96bit ICV (RFC3566)
+ 128 ah-old/esp-old: 128bit ICV (no document)
tcp-md5 8 to 640 tcp: rfc2385
.Ed
-.Pp
-The following is the list of encryption algorithms that can be used as the
+.Ss Encryption Algorithms
+The following encryption algorithms can be used as the
.Ar ealgo
in the
.Fl E Ar ealgo
@@ -627,15 +624,24 @@ cast128-cbc 40 to 128 rfc2451
des-deriv 64 ipsec-ciph-des-derived-01
aes-cbc 128/192/256 rfc3602
aes-ctr 160/224/288 rfc3686
-aes-gcm-16 160/224/288 rfc4106
+aes-gcm-16 160/224/288 AEAD; rfc4106
camellia-cbc 128/192/256 rfc4312
.Ed
.Pp
Note that the first 128/192/256 bits of a key for
-.Li aes-ctr or aes-gcm-16
-will be used as AES key, and remaining 32 bits will be used as nonce.
-.Pp
-The following are the list of compression algorithms that can be used
+.Li aes-ctr
+or
+.Li aes-gcm-16
+will be used as the AES key,
+and the remaining 32 bits will be used as the nonce.
+.Pp
+AEAD encryption algorithms such as
+.Li aes-gcm-16
+include authentication and should not be
+paired with a separate authentication algorithm via
+.Fl A .
+.Ss Compression Algorithms
+The following compression algorithms can be used
as the
.Ar calgo
in the
