1 files changed, 90 insertions, 55 deletions

diff --git a/man/ipsec.conf.5.in b/man/ipsec.conf.5.in
index fe37dff83..39c3b2b79 100644
--- a/man/ipsec.conf.5.in
+++ b/man/ipsec.conf.5.in
@@ -23,8 +23,7 @@ as are empty lines which are not within a section.
 A line which contains
 .B include
 and a file name, separated by white space,
-is replaced by the contents of that file,
-preceded and followed by empty lines.
+is replaced by the contents of that file.
 If the file name is not a full pathname,
 it is considered to be relative to the directory containing the
 including file.
@@ -61,12 +60,9 @@ indicates what type of section follows, and
 .I name
 is an arbitrary name which distinguishes the section from others
 of the same type.
-Names must start with a letter and may contain only
-letters, digits, periods, underscores, and hyphens.
 All subsequent non-empty lines
-which begin with white space are part of the section;
-comments within a section must begin with white space too.
-There may be only one section of a given type with a given name.
+which begin with white space are part of the section.
+Sections of the same type that share the same name are merged.
 .PP
 Lines within the section are generally of the form
 .PP
@@ -75,24 +71,30 @@ Lines within the section are generally of the form
 (note the mandatory preceding white space).
 There can be white space on either side of the
 .BR = .
-Parameter names follow the same syntax as section names,
-and are specific to a section type.
-Unless otherwise explicitly specified,
-no parameter name may appear more than once in a section.
+Parameter names are specific to a section type.
 .PP
 An empty
 .I value
 stands for the system default value (if any) of the parameter,
-i.e. it is roughly equivalent to omitting the parameter line entirely.
+i.e. it is roughly equivalent to omitting the parameter line entirely. This may
+be useful to clear a setting inherited from a
+.B %default
+section or via
+.B also
+parameter (see below).
 A
 .I value
-may contain white space only if the entire
-.I value
-is enclosed in double quotes (\fB"\fR);
-a
+may contain single spaces (additional white space is reduced to one space).
+To preserve white space as written enclose the entire
 .I value
-cannot itself contain a double quote,
-nor may it be continued across more than one line.
+in double quotes (\fB"\fR); in such values double quotes themselves may be
+escaped by prefixing them with
+.B \\\\
+characters. A double-quoted string may span multiple lines by ending them with
+.B \\\\
+characters (following lines don't have to begin with white space, as that will
+be preserved). Additionally, the following control characters may be encoded in
+double-quoted strings: \\n, \\r, \\t, \\b, \\f.
 .PP
 Numeric values are specified to be either an ``integer''
 (a sequence of digits) or a ``decimal number''
@@ -102,38 +104,24 @@ There is currently one parameter which is available in any type of
 section:
 .TP
 .B also
-the value is a section name;
-the parameters of that section are appended to this section,
-as if they had been written as part of it.
-The specified section must exist, must follow the current one,
-and must have the same section type.
-(Nesting is permitted,
-and there may be more than one
+the value is a section name; the parameters of that section are inherited by
+the current section. Parameters in the current section always override inherited
+parameters, even if an
+.B also
+follows after them.
+The specified section must exist and must have the same section type; it doesn't
+if it is defined before or after the current section.
+Nesting is permitted, and there may be more than one
+.B also
+in a single section (parameters from referenced sections are inherited and
+overridden in the order of these
 .B also
-in a single section,
-although it is forbidden to append the same section more than once.)
+parameters).
 .PP
 A section with name
 .B %default
-specifies defaults for sections of the same type.
-For each parameter in it,
-any section of that type which does not have a parameter of the same name
-gets a copy of the one from the
-.B %default
-section.
-There may be multiple
-.B %default
-sections of a given type,
-but only one default may be supplied for any specific parameter name,
-and all
-.B %default
-sections of a given type must precede all non-\c
-.B %default
-sections of that type.
-.B %default
-sections may not contain the
-.B also
-parameter.
+specifies defaults for sections of the same type. All parameters in it, are
+inherited by all other sections of that type.
 .PP
 Currently there are three types of sections:
 a
@@ -446,19 +434,20 @@ This may help to surmount restrictive firewalls. In order to force the peer to
 encapsulate packets, NAT detection payloads are faked.
 .TP
 .BR fragmentation " = yes | force | " no
-whether to use IKE fragmentation (proprietary IKEv1 extension).  Acceptable
-values are
+whether to use IKE fragmentation (proprietary IKEv1 extension or IKEv2
+fragmentation as per RFC 7383).  Acceptable values are
 .BR yes ,
 .B force
 and
 .B no
-(the default). Fragmented messages sent by a peer are always accepted
+(the default). Fragmented IKE messages sent by a peer are always accepted
 irrespective of the value of this option. If set to
 .BR yes ,
 and the peer supports it, larger IKE messages will be sent in fragments.
 If set to
 .B force
-the initial IKE message will already be fragmented if required.
+(only supported for IKEv1) the initial IKE message will already be fragmented
+if required.
 .TP
 .BR ike " = <cipher suites>"
 comma-separated list of IKE/ISAKMP SA encryption/authentication algorithms
@@ -583,6 +572,7 @@ for pre-shared key authentication,
 to (require the) use of the Extensible Authentication Protocol in IKEv2, and
 .B xauth
 for IKEv1 eXtended Authentication.
+
 To require a trustchain public key strength for the remote side, specify the
 key type followed by the minimum strength in bits (for example
 .BR ecdsa-384
@@ -595,6 +585,20 @@ or a key strength definition (for example
 .BR pubkey-sha1-sha256
 or
 .BR rsa-2048-ecdsa-256-sha256-sha384-sha512 ).
+Unless disabled in
+.BR strongswan.conf (5)
+such key types and hash algorithms are also applied as constraints against IKEv2
+signature authentication schemes used by the remote side.
+
+If both peers support RFC 7427 ("Signature Authentication in IKEv2") specific
+hash algorithms to be used during IKEv2 authentication may be configured.
+The syntax is the same as above. For example, with
+.B pubkey-sha384-sha256
+a public key signature scheme with either SHA-384 or SHA-256 would get used for
+authentication, in that order and depending on the hash algorithms supported by
+the peer.  If no specific hash algorithms are configured, the default is to
+prefer an algorithm that matches or exceeds the strength of the signature key.
+
 For
 .BR eap ,
 an optional EAP method can be appended. Currently defined methods are
@@ -613,7 +617,9 @@ Alternatively, IANA assigned EAP method numbers are accepted. Vendor specific
 EAP methods are defined in the form
 .B eap-type-vendor
 .RB "(e.g. " eap-7-12345 ).
-For
+To specify signature and trust chain constraints for EAP-(T)TLS, append a colon
+to the EAP method, followed by the key type/size and hash algorithm as discussed
+above. For
 .B xauth,
 an XAuth authentication backend can be specified, such as
 .B xauth-generic
@@ -750,11 +756,36 @@ defaults to
 .B left
 or the subject of the certificate configured with
 .BR leftcert .
-Can be an IP address, a fully-qualified domain name, an email address, or
-a keyid. If
+If
 .B leftcert
 is configured the identity has to be confirmed by the certificate.
 
+Can be an IP address, a fully-qualified domain name, an email address or a
+Distinguished Name for which the ID type is determined automatically and the
+string is converted to the appropriate encoding. To enforce a specific identity
+type, a prefix may be used, followed by a colon (:). If the number sign (#)
+follows the colon, the remaining data is interpreted as hex encoding, otherwise
+the string is used as-is as the identification data. Note that this implies
+that no conversion is performed for non-string identities. For example,
+\fIipv4:10.0.0.1\fP does not create a valid ID_IPV4_ADDR IKE identity, as it
+does not get converted to binary 0x0a000001. Instead, one could use
+\fIipv4:#0a000001\fP to get a valid identity, but just using the implicit type
+with automatic conversion is usually simpler. The same applies to the ASN1
+encoded types. The following prefixes are known:
+.BR ipv4 ,
+.BR ipv6 ,
+.BR rfc822 ,
+.BR email ,
+.BR userfqdn ,
+.BR fqdn ,
+.BR dns ,
+.BR asn1dn ,
+.B asn1gn
+and
+.BR keyid .
+Custom type prefixes may be specified by surrounding the numerical type value by
+curly brackets.
+
 For IKEv2 and
 .B rightid
 the prefix
@@ -828,13 +859,15 @@ an address of the given address family will be requested explicitly.
 If an IP address is configured, it will be requested from the responder,
 which is free to respond with a different address.
 .TP
-.BR rightsourceip " = %config | <network>/<netmask> | %poolname"
+.BR rightsourceip " = %config | <network>/<netmask> | <from>-<to> | %poolname"
 Comma separated list of internal source IPs to use in a tunnel for the remote
 peer. If the value is
 .B %config
 on the responder side, the initiator must propose an address which is then
 echoed back. Also supported are address pools expressed as
 \fInetwork\fB/\fInetmask\fR
+and
+\fIfrom\fB-\fIto\fR
 or the use of an external IP address pool using %\fIpoolname\fR,
 where \fIpoolname\fR is the name of the IP address pool used for the lookup.
 .TP
@@ -959,7 +992,9 @@ sets an XFRM mark in the inbound and outbound
 IPsec SAs and policies. If the mask is missing then a default
 mask of
 .B 0xffffffff
-is assumed.
+is assumed. The special value
+.B %unique
+assigns a unique value to each newly created IPsec SA.
 .TP
 .BR mark_in " = <value>[/<mask>]"
 sets an XFRM mark in the inbound IPsec SA and