Merge branch 'master' of github.com:strongswan/strongswan-docs

docs/modules/ROOT/nav.adoc

@@ -34,7 +34,7 @@
 ** xref:features/integrityTests.adoc[]
 ** xref:features/ietf.adoc[]
 
-.Howtos
+.How-tos
 ** xref:config/quickstart.adoc[]
 ** xref:pki/pkiQuickstart.adoc[]
 ** xref:pki/caManagement.adoc[]
@@ -52,7 +52,7 @@
 ** xref:daemons/charon-svc.adoc[]
 ** xref:daemons/charon-cmd.adoc[]
 
-.OS
+.Portability / OS
 ** xref:os/android.adoc[Android]
 *** xref:os/androidVpnClient.adoc[Android VPN Client]
 *** xref:os/androidVpnClientProfiles.adoc[Android VPN Client Profiles]

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

@@ -586,6 +586,84 @@ Cryptography) {NISTPQC}/selected-algorithms-2022[Selected Algorithms] and
 {NISTPQC}/round-4-submissions[Round 4 Submissions] Key Exchange Method (KEM)
 candidates.
 
+== Signature Algorithms
+
+Signature algorithms *are not negotiated* with proposals. But some of them are
+implemented only by certain plugins.
+
+[cols="4,2,5,3,3"]
+|===
+|Algorithm |Hash |OID |xref:#ike-support[IKE] | Plugins
+
+|*RSA PKCS#1 v1.5*
+|MD5
+|1.2.840.113549.1.1.4|*s* x w o g |gmp, md5
+
+|*RSA PKCS#1 v1.5*
+|SHA-1
+|1.2.840.113549.1.1.5|*s* x b w o g |gmp, sha1
+
+|*RSA PKCS#1 v1.5*
+|SHA-2 224
+|1.2.840.113549.1.1.14|x b w o g |gmp, sha2
+
+|*RSA PKCS#1 v1.5*
+|SHA-2 256
+|1.2.840.113549.1.1.11|x b w o g |gmp, sha2
+
+|*RSA PKCS#1 v1.5*
+|SHA-2 384
+|1.2.840.113549.1.1.12|x b w o g |gmp, sha2
+
+|*RSA PKCS#1 v1.5*
+|SHA-2 512
+|1.2.840.113549.1.1.13|x b w o g |gmp, sha2
+
+|*RSA PKCS#1 v1.5*
+|SHA-3 224
+|2.16.840.1.101.3.4.3.13|x b w o |gmp, sha3
+
+|*RSA PKCS#1 v1.5*
+|SHA-3 256
+|2.16.840.1.101.3.4.3.14|x b w o |gmp, sha3
+
+|*RSA PKCS#1 v1.5*
+|SHA-3 384
+|2.16.840.1.101.3.4.3.15|x b w o |gmp, sha3
+
+|*RSA PKCS#1 v1.5*
+|SHA-3 512
+|2.16.840.1.101.3.4.3.16|x b w o |gmp, sha3
+
+|*RSA PKCS#1 PSS*
+|Various
+|1.2.840.113549.1.1.10|x b w o g |gmp, mgf1, ...
+
+|*ECDSA*
+|SHA-1
+|1.2.840.10045.4.1|b w o |
+
+|*ECDSA*
+|SHA-2 256
+|1.2.840.10045.4.3.2|b w o |
+
+|*ECDSA*
+|SHA-2 384
+|1.2.840.10045.4.3.3|b w o |
+
+|*ECDSA*
+|SHA-2 512
+|1.2.840.10045.4.3.4|b w o |
+
+|*Ed25519*
+|
+|1.3.101.112|x b w o |curve25519, sha2
+
+|*Ed448*
+|
+|1.3.101.113|w o |
+|===
+
 == Commercial National Security Algorithm Suite
 
 The *Suite B* cryptographic suites for IPsec ({RFC6379}[RFC 6379]) have been

docs/modules/ROOT/pages/devs/devs.adoc

@@ -191,6 +191,9 @@ The {SRC}[`src`] directory in the strongSwan distribution contains the following
 |`*aikgen*`
 |Utility to generate an Attestation Identity Key bound to a TPM 1.2
 
+|xref:tools/cert-enroll.adoc[`*cert-enroll*`]
+|Automated certificate enrollment tool
+
 |xref:daemons/charon.adoc[`*charon*`]
 |The IKE keying daemon
 
@@ -272,7 +275,10 @@ The {SRC}[`src`] directory in the strongSwan distribution contains the following
 |Implements the xref:tnc/tnc.adoc[`IF-TNCCS`] interface
 
 |`*libtncif*`
-|Implmements the xref:tnc/tnc.adoc[`IF-IMC/IF-IMV`] interfaces
+|Implements the xref:tnc/tnc.adoc[`IF-IMC/IF-IMV`] interfaces
+
+|`*libtpmtss*`
+|Provides access to TPM 1.2 and xref:tpm/tpm2.adoc[TPM 2.0]
 
 |`*manager*`
 |A deprecated graphical management application for
@@ -291,9 +297,6 @@ The {SRC}[`src`] directory in the strongSwan distribution contains the following
 |xref:tnc/pt-tls-client.adoc[`*pt-tls-client*`]
 |Integrity measurement client using the `*PT-TLS*` protocol
 
-|xref:tools/scepclient.adoc[`*scepclient*`]
-|Utility to enroll certificates using the SCEP protocol
-
 |xref:tnc/sec-updater.adoc[`*sec-updater*`]
 |Utility extracting information about security updates and backports of Linux
  repositories (e.g. Debian or Ubuntu)
@@ -321,5 +324,5 @@ The {SRC}[`src`] directory in the strongSwan distribution contains the following
  tunnel up/down events
 
 |`*xfrmi*`
-|Create an `XFRM` interface
+|Utility to create `XFRM` interfaces
 |===

docs/modules/ROOT/pages/pki/pki.adoc

@@ -40,20 +40,17 @@ private key of a CA and containing `subjectAltNames`, CRL distribution points an
 URIs of OCSP servers. You can also extract raw public keys from private keys,
 certificate requests and certificates and compute two kinds of SHA1-based key IDs.
 
-[NOTE]
-====
 Starting with version 5.9.8, the `*pki*` command supports certificate enrollment
 via the *Simple Certificate Enrollment Protocol* (SCEP) as defined by
 {RFC8894}[RFC 8894], replacing the obsoleted
 xref:tools/scepclient.adoc[`*ipsec scepclient*`] tool.
 
-Additionally, with version 5.9.8 the newer `*https*` based *Enrollment over Secure
-Transport* (EST) protocol ({RFC7030}[RFC 7030]) is being offered, too.
-====
+Additionally, since version 5.9.8, the newer `*HTTPS/TLS*` based *Enrollment over
+Secure Transport* (EST) protocol ({RFC7030}[RFC 7030]) is being offered, too.
 
-Version 5.9.12 introduces an *Online Certificate Status Protocol* (OCSP) responder
+Version 5.9.12 introduced an *Online Certificate Status Protocol* (OCSP) responder
 as defined by {RFC6960}[RFC 6960], interoperating with an {OPENXPKI}[OpenXPKI]
-server by directly accessing its internal `*certificate*` datebase.
+server by directly accessing its internal `*certificate*` database.
 
 == Subcommands
 

docs/modules/ROOT/pages/plugins/eap-radius.adoc

@@ -311,6 +311,65 @@ negotiated identity. This is useful, as some RADIUS servers interpret such a
 prefix as a request for a specific EAP method (e.g. `*0*` as `*EAP-SIM*`, `*1*`
 as `*EAP-AKA*`).
 
+=== Identity Matching
+
+[WARNING]
+====
+The *client's IKE or EAP identity* might be *completely unauthenticated* when
+the authentication is delegated to a RADIUS server. So *switching connections*
+or basing other policy decisions on that identity is potentially unsafe.
+Consider using xref:#_group_selection[*group selection*] instead.
+====
+
+The plugin sends the IKE identity (or EAP identity if the IKE daemon is
+instructed to do an EAP-Identity exchange) as `*User-Name*` attribute to the
+RADIUS server. As described in the previous section, that *same identity* is
+also sent as `*EAP-Identity*` response in the first `*Access-Request*` message
+if `*eap_start=no*` is configured (the default).
+
+However, whether that identity is validated in any way depends on the RADIUS
+server's behavior and configuration. For instance, whether it enforces a match
+against the client certificate if EAP-TLS is used, or whether it uses it as a
+lookup key to find a password in case of EAP-MD5/MSCHAPv2. *If it doesn't, the
+IKE daemon can't trust that identity*.
+
+Moreover, with `*eap_start=yes*`, the RADIUS server may perform its own
+`*EAP-Identity*` exchange. This identity can be *completely unrelated* to the
+IKE identity that's passed in the `*User-Name*` attribute (e.g. with Windows
+clients that send their IP as IKE identity). And the IKE daemon won't know about
+this even if the RADIUS server changes the `*User-Name*` attribute in the
+`*Access-Accept*` reply as the plugin currently doesn't process this attribute.
+
+Therefore, *switching connections* or basing other policy decisions on the
+IKE/EAP identity (e.g. in a script or plugin like
+xref:plugins/ext-auth.adoc[`*ext-auth*`] or
+xref:plugins/whitelist.adoc[`*whitelist*`])
+is potentially unsafe when RADIUS servers are involved. Instead, consider using
+xref:#_group_selection[*group selection*] based on attributes provided by the
+RADIUS server in the `*Access-Accept*` message. However, unless validated, the
+RADIUS server shouldn't base this attribute assignment on the `*User-Name*`
+attribute either, but instead use e.g. information extracted from the verified
+client certificate.
+
+****
+When using EAP-TLS with *FreeRADIUS*, it's easily possible to match the IKE/EAP
+identity passed in the `User-Name` attribute against the Common Name (CN) RDN
+in the client certificate's subject distinguished name (DN) by setting:
+
+    check_cert_cn = %{User-Name}
+
+Even more flexibility is offered by the `virtual_server` offered by the
+`rlm_eap_tls` module, which can also match against other and even multiple
+attributes extracted from the client certificate such as CN (`TLS-Client-Cert-Common-Name`
+attribute) and SANs (e.g. `TLS-Client-Cert-Subject-Alt-Name-Email` or
+`TLS-Client-Cert-Subject-Alt-Name-Dns`).
+
+However, if the IKE/EAP identity is the certificate's subject DN, matching
+`TLS-Client-Cert-Subject` generally won't work because the string value it
+contains does not match the binary ASN.1-encoded value that's sent in the
+`User-Name` attribute.
+****
+
 === Group Selection
 
 The plugin optionally interprets the `*class*` attribute sent in the

docs/modules/ROOT/pages/support/commercial.adoc

@@ -1,7 +1,6 @@
 = Commercial Support
 
 :TOBIAS_MAIL:   mailto:tobias@strongswan.org
-:NOEL_MAIL:     mailto:noel.kuntze@thermi.consulting
 :CONTAURO_MAIL: mailto:vpn.support@contauro.com
 :CONTAURO_WEB:  https://www.contauro.com/
 :SYS4_MAIL:     mailto:ms@sys4.de
@@ -15,10 +14,6 @@ can contact them directly. They agreed to be listed here.
   ({TOBIAS_MAIL}[tobias@strongswan.org])
   - **Only development work and licensing, no commercial configuration support**
 
-. {NOEL_MAIL}[Noel Kuntze], Volketswil, Switzerland, a long time supporter and
-  IRC operator ({NOEL_MAIL}[noel.kuntze@thermi.consulting])
-  - **Businesses only, no private persons**
-
 . {CONTAURO_WEB}[Contauro AG], Zug, Switzerland,
   contact {CONTAURO_MAIL}[vpn.support@contauro.com]
   - **Businesses only, no private persons**

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

@@ -24,10 +24,42 @@ syntax (referencing sections, since version 5.7.0, and including other files is
 supported as well) and is located in the xref:swanctl/swanctlDir.adoc[`*swanctl*`]
 configuration directory, usually `*/etc/swanctl*`.
 
-Many examples can be found in our testing environment, eg. as used by the
-{TESTS}/ikev2[IKEv2 scenarios].
-
-include::partial$config/number_formats.adoc[]
+TIP: Examples are provided in the xref:config/quickstart.adoc[*Quickstart guide*].
+Many more can be found in our {TESTS}[testing environment] (but make sure to
+read xref:config/configExamplesNotes.adoc[the notes on these] before using them).
+
+=== dot-Notation / Placeholders
+
+In this manual, the options are documented in dot-notation and with generic
+placeholders, for instance:
+
+----
+connections.<conn>.remote<suffix>.auth=... <1> <2>
+connections.<conn>.children.<child>.local_ts=... <3>
+----
+<1> `*<conn>*` designates an arbitrary connection name
+<2> `*<suffix>*` is an optional extension to the given section name, it can be
+    omitted in many cases, except when e.g. defining secondary authentication
+    rounds or multiple secrets of the same type
+<3> `*<child>*` is an arbitrary child name
+
+The two options above as they might appear in an actual config file:
+----
+connections {
+    connection_a {
+        remote {
+            auth=...
+        }
+        children {
+            child_1 {
+                local_ts=...
+            }
+        }
+    }
+}
+----
+
+include::partial$config/number_formats.adoc[leveloffset=+1]
 
 == Keys
 

docs/modules/ROOT/pages/tools/scepclient.adoc

@@ -24,9 +24,9 @@ implemented an old version of the SCEP Internet Draft (version 10/11 of
 {IDSCEP}[draft-nourse-scep]) and used the broken `MD5` hash and single `DES`
 encryption algorithms as defaults.
 
-With strongSwan version 5.9.8 `*ipsec scepclient*` will be replaced by the
+With strongSwan version 5.9.8, `*ipsec scepclient*` was replaced by the
 xref:pki/pki.adoc[`*pki*`] subcommands xref:pki/pkiScep.adoc[`*pki --scep*`] and
-xref:pki/pkiScepCa.adoc[`*pki --scepca*`] which implement the new SCEP
-{RFC8894}[RFC 8894] standard that was released in September 2020 and which
-supports trusted *certificate renewal* based on the existing client certificate.
-====
+xref:pki/pkiScepCa.adoc[`*pki --scepca*`], which implement the new SCEP
+{RFC8894}[RFC 8894] standard that was released in September 2020 and supports
+trusted *certificate renewal* based on the existing client certificate.
+====