From c3e536419436eabdc0667691def82e2541082bd0 Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Wed, 4 Dec 2024 19:38:45 +0100 Subject: [PATCH] Rename page on algorithm keywords and document proposal format and selection --- docs/modules/ROOT/nav.adoc | 2 +- ...{IKEv2CipherSuites.adoc => proposals.adoc} | 91 ++++++++++++++++++- .../pages/howtos/securityRecommendations.adoc | 6 +- .../ROOT/pages/swanctl/swanctlConf.adoc | 12 +-- 4 files changed, 96 insertions(+), 15 deletions(-) rename docs/modules/ROOT/pages/config/{IKEv2CipherSuites.adoc => proposals.adoc} (80%) diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index fa8a8a46..ad6ce39a 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/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[] diff --git a/docs/modules/ROOT/pages/config/IKEv2CipherSuites.adoc b/docs/modules/ROOT/pages/config/proposals.adoc similarity index 80% rename from docs/modules/ROOT/pages/config/IKEv2CipherSuites.adoc rename to docs/modules/ROOT/pages/config/proposals.adoc index cb6ff01e..17b445b3 100644 --- a/docs/modules/ROOT/pages/config/IKEv2CipherSuites.adoc +++ b/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 diff --git a/docs/modules/ROOT/pages/howtos/securityRecommendations.adoc b/docs/modules/ROOT/pages/howtos/securityRecommendations.adoc index a5e26ada..25cccdd4 100644 --- a/docs/modules/ROOT/pages/howtos/securityRecommendations.adoc +++ b/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. diff --git a/docs/modules/ROOT/pages/swanctl/swanctlConf.adoc b/docs/modules/ROOT/pages/swanctl/swanctlConf.adoc index d28e4f04..7ef77db5 100644 --- a/docs/modules/ROOT/pages/swanctl/swanctlConf.adoc +++ b/docs/modules/ROOT/pages/swanctl/swanctlConf.adoc @@ -151,7 +151,7 @@ an arbitrary yet unique name (denoted `` below). automatic IKE port floating to port `*4500*` is used to work around NAT issues |.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 `` 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 |.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 |.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