git: e6dede145616 - main - setkey(8): Clarify language around AEAD ciphers.

The branch main has been updated by jhb:

URL: https://cgit.FreeBSD.org/src/commit/?id=e6dede145616ed8f98c629c23a2ba206b812c921

commit e6dede145616ed8f98c629c23a2ba206b812c921
Author:     John Baldwin <jhb@FreeBSD.org>
AuthorDate: 2022-04-27 19:18:52 +0000
Commit:     John Baldwin <jhb@FreeBSD.org>
CommitDate: 2022-04-27 19:23:18 +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 <pauamma@gundo.com>, markj
    Differential Revision:  https://reviews.freebsd.org/D34947
---
 sbin/setkey/setkey.8 | 58 +++++++++++++++++++++++++++++-----------------------
 1 file changed, 32 insertions(+), 26 deletions(-)

diff --git a/sbin/setkey/setkey.8 b/sbin/setkey/setkey.8
index 67786c82b7a7..79e28b99f950 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,21 +585,21 @@ of the
 parameter:
 .Bd -literal -offset indent
 algorithm	keylen (bits)	comment
-hmac-sha1	160		ah: rfc2404
-		160		ah-old: 128bit ICV (no document)
+hmac-sha1	160		ah/esp: rfc2404
+		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)
-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)
+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
@@ -614,14 +611,23 @@ algorithm	keylen (bits)	comment
 null		0 to 2048	rfc2410
 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
 .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.
+.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
-The following are the list of compression algorithms that can be used
+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
@@ -639,7 +645,7 @@ deflate		rfc2394
 .\"
 .Sh EXAMPLES
 Add an ESP SA between two IPv6 addresses using the
-AES-GCM encryption algorithm.
+AES-GCM AEAD algorithm.
 .Bd -literal -offset indent
 add 3ffe:501:4819::1 3ffe:501:481d::1 esp 123457
 	-E aes-gcm-16 0x3ffe050148193ffe050148193ffe050148193ffe ;