Rename page on algorithm keywords and document proposal format and se…

…lection

docs/modules/ROOT/nav.adoc

@@ -18,7 +18,7 @@
 ** xref:config/strongswanDir.adoc[]
 ** xref:swanctl/swanctlConf.adoc[]
 ** xref:swanctl/swanctlDir.adoc[]
-* xref:config/IKEv2CipherSuites.adoc[]
+* xref:config/proposals.adoc[]
 * xref:config/logging.adoc[]
 * xref:config/identityParsing.adoc[]
 * xref:config/jobPriority.adoc[]

docs/modules/ROOT/pages/config/IKEv2CipherSuites.adoc → docs/modules/ROOT/pages/config/proposals.adoc

@@ -1,4 +1,5 @@
-= IKEv2 Cipher Suites
+= Algorithm Proposals (Cipher Suites)
+:page-aliases: config/IKEv2CipherSuites.adoc
 
 :NISTPQC: https://csrc.nist.gov/projects/post-quantum-cryptography
 :PQ:      https://github.com/strongX509/docker/tree/master/pq-strongswan#readme
@@ -8,10 +9,90 @@
 :RFC6379: {IETF}/rfc6379
 :RFC9370: {IETF}/rfc9370
 
-The keywords listed below can be used with the `*proposals*` attributes in
-xref:swanctl/swanctlConf.adoc[`*swanctl.conf*`] to define IKE or ESP/AH cipher
-suites. IANA provides a complete list of algorithm identifiers registered for
-{IANA}[IKEv2].
+The keywords listed below can be used with the `*proposals*` and `*ah|esp_proposals*`
+settings in xref:swanctl/swanctlConf.adoc[`*swanctl.conf*`] to define IKE and ESP/AH
+proposals/cipher suites. IANA provides a complete list of algorithm identifiers
+registered for {IANA}[IKEv2].
+
+== General Proposal Format
+
+The basic format of a proposal is simply a *list of algorithm keywords separated
+by dashes*. With IKEv2, multiple algorithms of the same kind can be specified in
+a single proposal, their order defines the *preference in descending order*.
+
+CAUTION: IKEv1 only supports one algorithm of each kind per proposal. Additional
+algorithms are implicitly stripped. Use multiple proposals to offer different
+algorithm combinations for IKEv1.
+
+For instance, the ESP proposal `*aes256gcm16-aes128gcm16*` specifies two
+authenticated encryption algorithms, of which the former is preferred over the
+latter.
+
+The following IKEv2 proposal additionally lists algorithms for the required PRF and
+key exchange methods:
+
+----
+aes256gcm16-aes192gcm16-prfsha384-prfsha256-ecp384-modp3072 <1>
+
+aes256gcm16-prfsha384-ecp384-aes192gcm16-prfsha256-modp3072 <2>
+----
+<1> `*aes256gcm16*` is preferred over `*aes192gcm16*`, `*prfsha384*` over
+`*prfsha256*`, and `*ecp384*` over `*modp3072*`.
+<2> The order of algorithms of different kinds doesn't matter, so this is the
+exact same proposal.
+
+*Multiple proposals* may be configured (separated with commas in
+xref:swanctl/swanctlConf.adoc[`*swanctl.conf*`]). This is e.g. necessary in order
+to accept AEAD and classic encryption/integrity algorithms as they must not be
+used in the same proposal. The order of the proposals defines their preference.
+
+== Proposal Selection
+
+When *selecting a proposal* as responder, based on the ones configured and those
+received from the initiator, strongSwan *prefers its own configuration by default*.
+
+That is, the *first configured* proposal (and within it the first algorithm of
+each kind) that is *accepted by the received* proposals is selected and returned
+to the initiator.
+
+[subs="+quotes"]
+.Example of Default Proposal Selection
+----
+Configured: *aes256gcm16*-aes192gcm16-*prfsha384*-prfsha256-*ecp384*-modp3072
+Received  : aes128-aes192-aes256-sha256-sha384-modp2048-modp3072-ecp384 <1>
+            aes128gcm16-aes192gcm16-*aes256gcm16*-prfsha256-*prfsha384*-modp3072-*ecp384* <2>
+Selected  : *aes256gcm16-prfsha384-ecp384* <3>
+----
+<1> This proposal is rejected as it uses classic encryption/integrity algorithms
+instead of AEAD algorithms.
+<2> While `*aes192gcm16*` is proposed earlier, the configured proposal prefers
+`*aes256gcm16*`, which is also contained in the received proposal and thus
+selected. Similarly for the other algorithms.
+<3> Because the initiator proposed `*modp3072*` first, the received KE payload
+will also be for that algorithm. By selecting `*ecp384*` as key exchange method,
+this will cause an `*INVALID_KE_PAYLOAD*` error in order to request a KE payload
+of the selected algorithm (i.e. this requires an additional roundtrip).
+
+Depending on the use case, this behavior can be changed by *disabling*
+`*charon.prefer_configured_proposals*` in xref:config/strongswanConf.adoc#[`*strongswan.conf*`].
+If this option is disabled, the *first received* proposal (and within it the
+first algorithm of each kind) that is *accepted by the configured* proposals is
+selected and returned to the initiator.
+
+[subs="+quotes"]
+.Example of Alternative Proposal Selection
+----
+Configured: aes256gcm16-*aes192gcm16*-prfsha384-*prfsha256*-ecp384-*modp3072*
+Received  : aes128-aes192-aes256-sha256-sha384-modp2048-modp3072-ecp384 <1>
+            aes128gcm16-*aes192gcm16*-aes256gcm16-*prfsha256*-prfsha384-*modp3072*-ecp384 <2>
+Selected  : *aes192gcm16-prfsha256-modp3072* <3>
+----
+<1> Again, this proposal is rejected as it does not match the configured proposal at all.
+<2> `*aes192gcm16*` is selected as it is the first proposed encryption
+algorithm that's not rejected by the configured proposal (`*aes128gcm16*` is
+not contained in it and skipped).
+<3> The selected key exchange method is the first one proposed by the initiator
+and, thus, likely matches the received KE payload.
 
 [#ike-support]
 == IKE Support Options

docs/modules/ROOT/pages/howtos/securityRecommendations.adoc

@@ -15,7 +15,7 @@ using strongSwan to set up IKE connections and policy-based IPsec tunnels.
 
 == Weak Cryptographic Algorithms
 
-The following cryptographic algorithms are *weak* and prone to attacks and 
+The following cryptographic algorithms are *weak* and prone to attacks and
 therefore *must not* be used.
 
 Encryption ::
@@ -36,7 +36,7 @@ Diffie-Hellman Groups ::
 modp512,modp768,modp1024,modp1024s160,modp1536,modp2048s224,modp2048s256,ecp192
 ----
 
-These algorithms do not directly relate to plugins. To *disable* them you must 
+These algorithms do not directly relate to plugins. To *disable* them you must
 specify a set of crypto proposals that exclude these algorithms in the connection
 definitions of xref:swanctl/swanctlConf.adoc[`*swanctl.conf*`]
 ----
@@ -99,7 +99,7 @@ may also be used where supported
 
  aes256-sha384-ecp384,aes256gcm16-prfsha384-ecp384
 
-The supported xref:config/IKEv2CipherSuites.adoc[IKEv2 cipher suites] are limited
+The supported xref:config/proposals.adoc[algorithm proposal keywords] are limited
 to what the various `*libstrongswan*` plugins implement.
 
 The supported ESP/AH cipher suites are limited to what the Linux kernel supports.

docs/modules/ROOT/pages/swanctl/swanctlConf.adoc

@@ -151,7 +151,7 @@ an arbitrary yet unique name (denoted `<conn>` below).
  automatic IKE port floating to port `*4500*` is used to work around NAT issues
 
 |<conn>.proposals          |[->]
-|A proposal is a set of xref:config/IKEv2CipherSuites.adoc[algorithms]. For
+|A proposal is a set of xref:config/proposals.adoc[algorithms]. For
  non-AEAD IKE proposals, this includes an encryption algorithm, an integrity
  algorithm, a pseudo-random function (PRF) and a key exchange method. For AEAD
  proposals, instead of encryption and integrity algorithms a combined mode
@@ -166,7 +166,7 @@ an arbitrary yet unique name (denoted `<conn>` below).
  is allowed per proposal, more algorithms get implicitly stripped. Use multiple
  proposals to offer different algorithm combinations with IKEv1.
  +
- xref:config/IKEv2CipherSuites.adoc[Algorithm keywords] get separated using dashes.
+ xref:config/proposals.adoc[Algorithm keywords] get separated using dashes.
  Multiple proposals may be separated by commas. The special value `*default*`
  adds a default proposal of supported algorithms considered safe and is usually
  a good choice for interoperability. [`default`]
@@ -601,7 +601,7 @@ of the CHILD_SA configuration, which must be unique within the connection
 
 |<child>.ah_proposals      |
 |AH proposals to offer for the CHILD_SA. A proposal is a set of
- xref:config/IKEv2CipherSuites.adoc[algorithms]. For AH, this includes an
+ xref:config/proposals.adoc[algorithms]. For AH, this includes an
  integrity algorithm and an optional key exchange method. If a KE method is
  specified, CHILD_SA/Quick Mode rekeying and initial negotiation uses a separate
  key exchange using the negotiated method (refer to `*esp_proposals*` for details).
@@ -615,7 +615,7 @@ of the CHILD_SA configuration, which must be unique within the connection
  allowed per proposal. Additional algorithms are implicitly stripped. Use multiple
  proposals to offer different algorithm combinations with IKEv1.
  +
- xref:config/IKEv2CipherSuites.adoc[Algorithm keywords] get separated using dashes.
+ xref:config/proposals.adoc[Algorithm keywords] get separated using dashes.
  Multiple proposals may be separated by commas. The special value `*default*`
  forms a default proposal of supported algorithms considered safe and is usually
  a good choice for interoperability.
@@ -624,7 +624,7 @@ of the CHILD_SA configuration, which must be unique within the connection
 
 |<child>.esp_proposals     |[->]
 |ESP proposals to offer for the CHILD_SA. A proposal is a set of
- xref:config/IKEv2CipherSuites.adoc[algorithms]. For non-AEAD ESP proposals,
+ xref:config/proposals.adoc[algorithms]. For non-AEAD ESP proposals,
  this includes an integrity algorithm, an encryption algorithm, an optional
  key exchange method and an optional Extended Sequence Number Mode (ESN)
  indicator. For AEAD proposals, a combined mode algorithm is used instead of the
@@ -652,7 +652,7 @@ of the CHILD_SA configuration, which must be unique within the connection
  allowed per proposal. Additional algorithms are implicitly stripped. Use multiple
  proposals to offer different algorithm combinations for IKEv1.
  +
- xref:config/IKEv2CipherSuites.adoc[Algorithm keywords] get separated using dashes.
+ xref:config/proposals.adoc[Algorithm keywords] get separated using dashes.
  Multiple proposals may be separated by commas. The special value `*default*`
  forms a default proposal of supported algorithms considered safe and is usually
  a good choice for interoperability. If no algorithms are specified for AH nor