From nobody Wed Apr 27 19:23:39 2022 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 8F327199A4B5; Wed, 27 Apr 2022 19:23:39 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4KpTF73RNxz3HZy; Wed, 27 Apr 2022 19:23:39 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1651087419; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=L7Fewefl0F7iNWaplVCqHptH0+9rGAj9i/JDBFySna8=; b=YKpZ5uq7ilu1ilqKPgzqFQk0f6LwjJgI4rDKSS6ZPixz0D6mIv3G9ARS+ycwBw21hy+4rL iDbrbYlTRIbZ2NHwzw3urK2PX+4qRb19PfKnhsyr393/1pL0rZbXvRQ66qJDHI+YnMMIga T0JDc/fq3f2KsOJ/1l8joKtc8FcMnN8BwQYpHVvZSb9kO3fwbkTufdDCMWE+iS87NSv2JY zGrAYZx3ceW4I7Z0LMAQ9ANSLBLWAalyWNc0nqlVUfE/FNRpKTr6laweugeiZE1FrgUUs7 Xgk1h4klo1UTkWmpE4UBQEhLFBCuZ32oNMMId3YPvPQmANFj0evlnBFulNgV9Q== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 565D01B2D; Wed, 27 Apr 2022 19:23:39 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 23RJNd7U047466; Wed, 27 Apr 2022 19:23:39 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 23RJNdFS047465; Wed, 27 Apr 2022 19:23:39 GMT (envelope-from git) Date: Wed, 27 Apr 2022 19:23:39 GMT Message-Id: <202204271923.23RJNdFS047465@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: John Baldwin Subject: git: e6dede145616 - main - setkey(8): Clarify language around AEAD ciphers. List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-src-all@freebsd.org X-BeenThere: dev-commits-src-all@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: jhb X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: e6dede145616ed8f98c629c23a2ba206b812c921 Auto-Submitted: auto-generated ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1651087419; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=L7Fewefl0F7iNWaplVCqHptH0+9rGAj9i/JDBFySna8=; b=DcU7/ZPNVryMs9q08IBrbWqRL0/1QZLXPlVXUI+nNV1cHp2J6ra5dQi2jJI+ubVUpqdF4Z lZjJbLRXTdy9gDiH2g9lHn9L9c8suCnVgoRcF6vAC/Bjsg7FyrsE2nQWtvGydLmDTRwB+M 8az1nKLXau95ahYlfHVHz39mOxHUvJoQrGoQsCghdqothzat5xJtLfHDHLSCPzCoZkiFEA jzxhJiPbeUkWdpV6JgIuIrucaT3qBrvuVOSsj9HvCB+vvmboqwzO8JycrzROoNsPpTPgn7 7xtis7s/kpxdSlmhLWyxtsNYPtw/LXucilylPzf4zXrGvAFm0s1quOzvdy2D6w== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1651087419; a=rsa-sha256; cv=none; b=kW6RakuetcKYN8IICcMIMklwEo3DC6MeMtOn6TdN8mYpCbzO9XhsAD7IzNeYZdQtqr4QgJ 9PRxJrJuMnbaKxOR/hXrSmEMmOgTaZqeSLrszfpyu9eCgpZvw70YQ2Y1WyoYyiMn1iNvMc ERg798NzoBrf51vbbY8Y/WqEStval+EnPyra1lBMpYn+bfXgyuarpSbTG0IAxoXxYtFDH8 n+hIVvp+u/ojYAXbEi5R/LwBYmyfRkCqnmYgChHKKvp9JkPaN78nxKhK+wYo3lYod6SxCH l0I05y7YSOb0wo2DkdNejIDs3VKFcwGs8OWhmkLO1i5c/iNRydSIH9fMsyjWsw== ARC-Authentication-Results: i=1; mx1.freebsd.org; none X-ThisMailContainsUnwantedMimeParts: N The branch main has been updated by jhb: URL: https://cgit.FreeBSD.org/src/commit/?id=e6dede145616ed8f98c629c23a2ba206b812c921 commit e6dede145616ed8f98c629c23a2ba206b812c921 Author: John Baldwin AuthorDate: 2022-04-27 19:18:52 +0000 Commit: John Baldwin 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 , 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 ;