rework IPsec intro

[Andrew Cagney <andrew.cagney%gmail.com@localhost>]

Hi,
This patch reworks the Ipsec intro section of the IPsec FAQ.  It tries
to use IKEv2 terminology (but does still mention IKEv1 terms that
refuse to die).
It also notes some notable successes and gaps in NetBSD's
implementation of ESP/AH.
Andrew

commit 57cf781ff20ebd8c258cf8b5870adc91549c8480
Author: Andrew Cagney <andrew.cagney%gmail.com@localhost>
Date:   Tue Jun 11 19:32:20 2024 +0000

    refresh IPsec overview, be more IKEv2 like

diff --git a/docs/network/ipsec/index.xml b/docs/network/ipsec/index.xml
index 9325cfb..e9b1936 100644
--- a/docs/network/ipsec/index.xml
+++ b/docs/network/ipsec/index.xml
@@ -47,62 +47,204 @@
       </sect3>
 
       <sect3 id="ipsec_breakdown">
-	<title>IPsec = AH + ESP + IPcomp + IKE</title>
+	<title>IPsec = IKE + ESP || AH</title>
+
+	<para>
+	  IPsec consists of two parts: the Internet Key Exchange
+	  daemon (RFC 7296) that establishes and maintains secure
+	  associations between peers, and the ESP/RFC protocols used
+	  to secure IP datagrams.
+	</para>
+
+	<para>
+	  Internet Key Exchange daemon first establishes a secure IKE
+	  SA between peers.  This involves the following:
+	</para>
+
+	<variablelist>
+	  <varlistentry>
+	    <term>
+	      Establish a secured channel
+	    </term>
+	    <listitem>
+	      <para>
+		A Diffie-Hellman-Merkle exchange is used to establish
+		a secured channel between the peers.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>
+	      Authenticate, proving the channel is between peers
+	    </term>
+	    <listitem>
+	      <para>
+		Using the secured channel established above, each end
+		proves their identity to their the peer.  For instance
+		using Public and Private keys, or a pre-shared key.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	</variablelist>
+
+	<para>
+	  In IKEv2 this is the IKE_SA_INIT and IKE_AUTH exchanges
+	  (IKEv1 referred to this as Phase 1, using either Main or
+	  Aggressive Mode).
+	</para>
 
-	<para>IPsec consists of a couple of separate protocols, listed below:</para>
+	<note>
+	  <para>
+	    While IKE is technically optional (you can configure
+	    secret keys manually for ESP/AH), it is not recommended.
+	    The keys used by ESP/AH have a limited life (both time and
+	    byte count) and need to be regularly replaced.  The IKE
+	    daemon handles this.
+	  </para>
+	</note>
 
-	<itemizedlist>
-	  <listitem>Authentication Header (AH): provides authenticity guarantee for packets,
-	    by attaching strong crypto checksum to packets.
-	    If you receive a packet with AH and the checksum operation was
-	    successful, you can be sure about two things <emphasis>if you and the
-	      peer share a secret key, and no other party knows the key</emphasis>:
-	    <itemizedlist>
-	      <listitem>The packet was originated by the expected peer.
-	        The packet was not generated by impersonator.
+	<para>
+	  The Internet Key Exchange Daemons then use the IKE SA
+	  between peers to negotiate, establish, and maintain ESP/AH
+	  Child SAs that are used to secure IP Datagrams.  Two types
+	  of Child SA are supported:
+	</para>
+
+	<variablelist>
+	  <varlistentry>
+	    <term>Encapsulating Security Payload (ESP, RFC 4302)</term>
+	    <listitem>
+	      <para>
+		ESP provides both confidentiality and authenticity
+		guarantees for packets.  Using a key shared with the
+		peer, each IP datagram is encrypted and then an
+		integrity hash is appended.  On receipt, the peer uses
+		the same key to verify the integrity and decrypt the
+		packet.
+	      </para>
+	      <note>
+		<para>
+		  Combined Algorithms (aka Authenticated Encryption
+		  with Associated Data or AEAD), such as AES_GCM and
+		  ChaCha20, that combine encryption and integrity have
+		  largely replaced separate encryption and integrity
+		  algorithms.
+		</para>
+	      </note>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>Authentication Header (AH, RFC 4303)</term>
+	    <listitem>
+	      <para>
+		AH provides authenticity guarantee for packets.  Using
+		a key shared by the peer, an integrity hash is
+		appended to each packet.  On receipt, the peer then
+		uses that same key to verify the integrity of the IP
+		datagram.
+	      </para>
+	      <para>
+		Unlike other protocols, AH in transport mode (see
+		below), covers the whole packet, from the IP header to
+		the end of the packet.  In tunnel mode, however,
+		there's little to differentiate between AH and the ESP
+		combined with NULL encryption.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	</variablelist>
+
+	<para>
+	  In IKEv2 this is the CREATE_CHILD_SA exchange (the first
+	  Child SA is is typically created by including the
+	  CREATE_CHILD_SA exchange contents in the IKE_AUTH exchange,
+	  thus avoiding a round trip) (IKEv1 referred to this as Phase
+	  2, Quick Mode).
+	</para>
+
+	<para>
+	  When establishing ESP or AH additional parameters, such as
+	  the following, can be negotiated:
+	  <variablelist>
+	    <varlistentry>
+	      <term>IP compression (IPcomp)</term>
+	      <listitem>
+		<para>
+		  Instead of encapsulating the raw IP datagram, the
+		  peers may agree to compress the raw payload.  If the
+		  compression reduces the size of a given raw IP
+		  datagram then it is sent compressed of the
+		  uncompressed payload is sent (which typically leads
+		  to wasted effort).
+		</para>
+		<para>
+		  NetBSD 10 supports IPcomp (including combinations
+		  such as an IPv4 packet being compressed,
+		  encapsulated and then sent using IPv6!).
+		</para>
 	      </listitem>
-
-	      <listitem>The packet was not modified in transit.
+	    </varlistentry>
+	    <varlistentry>
+	      <term>Transport Mode</term>
+	      <listitem>
+		<para>
+		  Instead of tunneling the ESP and/or AH payload
+		  inside UDP, the peers may agree to send the packets
+		  directly using Transport Mode.
+		</para>
+		<para>
+		  NetBSD 10 supports Transport Mode.
+		</para>
 	      </listitem>
-	    </itemizedlist>
-	    Unlike other protocols, AH covers the whole packet, from the IP header
-	    to the end of the packet.
-	  </listitem>
-
-	  <listitem>Encapsulating Security Payload (ESP): provides confidentiality guarantee
-	    for packets, by encrypting packets with encryption algorithms.
-	    If you receive a packet with ESP and successfully decrypted it,
-	    you can be sure that the packet was not wiretapped in the middle,
-	    <emphasis>if you and the peer share a secret key, and no other party
-	      knows the key</emphasis>.
-	  </listitem>
-
-	  <listitem>IP payload compression (IPcomp): ESP provides encryption service to the
-	    packets.
-	    However, encryption tend to give negative impact to compression on
-	    the wire (such as ppp compression).
-	    IPcomp provides a way to compress packet before encryption by ESP
-	    (Of course, you can use IPcomp alone if you wish to).
-	  </listitem>
-
-	  <listitem>Internet Key Exchange (IKE): As noted above, AH and ESP needs shared
-	    secret key between peers.
-	    For communication between distant location, we need to provide ways
-	    to negotiate keys in secrecy.
-	    IKE will make it possible.
-	  </listitem>
-	</itemizedlist>
+	    </varlistentry>
+	    <varlistentry>
+	      <term>Extended Sequence Numbers</term>
+	      <listitem>
+		<para>
+		  Instead of using a 32-bit sequence counter, peers
+		  may agree to use a 64-bit sequence counter (only
+		  32-bits go over the wire).  The larger sequence
+		  counter means more time between rekeys.
+		</para>
+		<para>
+		  NetBSD 10 does not support Extended Sequence
+		  Numbers.
+		</para>
+	      </listitem>
+	    </varlistentry>
+	    <varlistentry>
+	      <term>ESP in TCP (RFC 9329)</term>
+	      <listitem>
+		<para>
+		  Instead of transferring ESP packets using UDP, the
+		  peers may agree to transfer the encapsulated packets
+		  using a TCP data stream.  This provides a way to get
+		  around firewalls that block UDP traffic.
+		</para>
+		<para>
+		  NetBSD 10 does not support ESP in TCP.
+		</para>
+	      </listitem>
+	    </varlistentry>
+	    <varlistentry>
+	      <term>IP Traffic Flow Confidentially (IP-TFC, RFC 9347)</term>
+	      <listitem>
+		Instead of directly transforming each IP datagram into
+		an ESP packet, peers can agree to aggregate, pad, and
+		fragment traffic obscuring traffic flow.
+	      </listitem>
+	      <para>
+		NetBSD 10 does not support IP-TFC.
+	      </para>
+	    </varlistentry>
+	  </variablelist>
+	</para>
 
 	<para>AH, ESP and IPcomp are implemented in the kernel code.
 	  IKE is implemented as daemon process in the userland.
 	  Kernel part and userland part will cooperate by using key management table
 	  in between.</para>
 
-	<para>IKE is actually optional, you can configure secret keys manually for AH/ESP.
-	  However, please understand it: you cannot use the same secret key forever.
-	  If you use the same secret key for a long period of time,
-	  your traffic become more and more likely to get compromised.</para>
-
 	<note>
 	  <para><emphasis role="bold">security of IPsec protocols depend on the secrecy of secret keys.
 	    </emphasis>
@@ -111,10 +253,6 @@
 	    key database files, or whatever they may lead to information leakage.</para>
 	</note>
 
-	<para>There two set of RFCs published; old IPsec suite starts from <!--RFC-->RFC1825,
-	  and new IPsec suite starts from <!--RFC-->RFC2401.
-	  Though NetBSD implements both, it is recommended to use new IPsec suite.</para>
-
 	<programlisting>
 
         userland programs               IKE daemon