From: Tobias Brunner Date: Wed, 4 Dec 2024 14:14:21 +0000 (+0100) Subject: swanctl: Document keX_ prefix and replace DH with KE X-Git-Tag: android-2.5.3~39 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c8f16d18d8f42790e9bfeb12735526e2afe00bbe;p=thirdparty%2Fstrongswan.git swanctl: Document keX_ prefix and replace DH with KE --- diff --git a/src/swanctl/swanctl.opt b/src/swanctl/swanctl.opt index ffac64c5db..cb61210656 100644 --- a/src/swanctl/swanctl.opt +++ b/src/swanctl/swanctl.opt @@ -66,15 +66,20 @@ connections..remote_port = 500 connections..proposals = default Comma separated proposals to accept for IKE. - A proposal is a set of algorithms. For non-AEAD algorithms, this includes - for IKE an encryption algorithm, an integrity algorithm, a pseudo random - function and a Diffie-Hellman group. For AEAD algorithms, instead of - encryption and integrity algorithms, a combined algorithm is used. - - In IKEv2, multiple algorithms of the same kind can be specified in a single - proposal, from which one gets selected. In IKEv1, only one algorithm per + A proposal is a set of algorithms. For non-AEAD IKE proposals, this includes + an encryption algorithm, an integrity algorithm, a pseudo-random function + and a key exchange method. For AEAD proposals, instead of encryption and + integrity algorithms, a combined mode algorithm is used. + + With peers that support multiple IKEv2 key exchanges (RFC 9370), up to seven + additional key exchanges may be negotiated. They can be configured by + prefixing the algorithm keyword with **keX_** (where X is a number between + 1 and 7). + + For IKEv2, multiple algorithms of the same kind can be specified in a single + proposal, from which one gets selected. For IKEv1, only one algorithm per kind is allowed per proposal, more algorithms get implicitly stripped. Use - multiple proposals to offer different algorithms combinations in IKEv1. + multiple proposals to offer different algorithm combinations with IKEv1. Algorithm keywords get separated using dashes. Multiple proposals may be separated by commas. The special value _default_ forms a default proposal @@ -173,7 +178,7 @@ connections..childless = allow Use childless IKE_SA initiation (RFC 6023) for IKEv2, with the first CHILD_SA created with a separate CREATE_CHILD_SA exchange (e.g. to use an - independent DH exchange for all CHILD_SAs). Acceptable values are _allow_ + independent key exchange for all CHILD_SAs). Acceptable values are _allow_ (the default), _prefer_, _force_ and _never_. If set to _allow_, responders will accept childless IKE_SAs (as indicated via notify in the IKE_SA_INIT response) while initiators continue to create regular IKE_SAs with the first @@ -690,15 +695,20 @@ connections..children..ah_proposals = AH proposals to offer for the CHILD_SA. AH proposals to offer for the CHILD_SA. A proposal is a set of algorithms. - For AH, this includes an integrity algorithm and an optional Diffie-Hellman - group. If a DH group is specified, CHILD_SA/Quick Mode rekeying and initial - negotiation uses a separate Diffie-Hellman exchange using the specified - group (refer to _esp_proposals_ for details). - - In IKEv2, multiple algorithms of the same kind can be specified in a single - proposal, from which one gets selected. In IKEv1, only one algorithm per + 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). + + With peers that support multiple IKEv2 key exchanges (RFC 9370), up to seven + additional key exchanges may be negotiated. They can be configured by + prefixing the algorithm keyword with **keX_** (where X is a number between + 1 and 7). + + For IKEv2, multiple algorithms of the same kind can be specified in a single + proposal, from which one gets selected. For IKEv1, only one algorithm per kind is allowed per proposal, more algorithms get implicitly stripped. Use - multiple proposals to offer different algorithms combinations in IKEv1. + multiple proposals to offer different algorithm combinations with IKEv1. Algorithm keywords get separated using dashes. Multiple proposals may be separated by commas. The special value _default_ forms a default proposal @@ -710,29 +720,34 @@ connections..children..esp_proposals = default ESP proposals to offer for the CHILD_SA. ESP proposals to offer for the CHILD_SA. A proposal is a set of algorithms. - For ESP non-AEAD proposals, this includes an integrity algorithm, an - encryption algorithm, an optional Diffie-Hellman group and an optional + 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 indicator. For AEAD proposals, a combined mode algorithm is used instead of the separate encryption/integrity algorithms. - If a DH group is specified, CHILD_SA/Quick Mode rekeying and initial - negotiation use a separate Diffie-Hellman exchange using the specified - group. However, for IKEv2, the keys of the CHILD_SA created implicitly with - the IKE_SA will always be derived from the IKE_SA's key material. So any DH - group specified here will only apply when the CHILD_SA is later rekeyed or - is created with a separate CREATE_CHILD_SA exchange. A proposal mismatch - might, therefore, not immediately be noticed when the SA is established, but - may later cause rekeying to fail. + If a key exchange method is specified, CHILD_SA/Quick Mode rekeying and + initial negotiation use a separate key exchange using the specified method. + However, for IKEv2, the keys of the CHILD_SA created implicitly with the + IKE_SA will always be derived from the IKE_SA's key material. So any key + exchange method specified here will only apply when the CHILD_SA is later + rekeyed or is created with a separate CREATE_CHILD_SA exchange. A proposal + mismatch might, therefore, not immediately be noticed when the SA is + established, but may later cause rekeying to fail. + + With peers that support multiple IKEv2 key exchanges (RFC 9370), up to seven + additional key exchanges may be negotiated. They can be configured by + prefixing the algorithm keyword with **keX_** (where X is a number between + 1 and 7). Extended Sequence Number support may be indicated with the _esn_ and _noesn_ values, both may be included to indicate support for both modes. If omitted, _noesn_ is assumed. - In IKEv2, multiple algorithms of the same kind can be specified in a single - proposal, from which one gets selected. In IKEv1, only one algorithm per + For IKEv2, multiple algorithms of the same kind can be specified in a single + proposal, from which one gets selected. For IKEv1, only one algorithm per kind is allowed per proposal, more algorithms get implicitly stripped. Use - multiple proposals to offer different algorithms combinations in IKEv1. + multiple proposals to offer different algorithm combinations with IKEv1. Algorithm keywords get separated using dashes. Multiple proposals may be separated by commas. The special value _default_ forms a default proposal