summaryrefslogtreecommitdiff
path: root/man/ipsec.conf.5.in
diff options
context:
space:
mode:
Diffstat (limited to 'man/ipsec.conf.5.in')
-rw-r--r--man/ipsec.conf.5.in145
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