# See: https://wiki.strongswan.org/projects/strongswan/wiki/Swanctlconf
#
# When strongSwan is upgraded please update the parameters in this file. You can
# see which parameters should be deleted, changed or added by diffing
# swanctl.opt:
#
# git clone https://github.com/strongswan/strongswan.git
# cd strongswan
# git diff 5.7.2..5.8.0 src/swanctl/swanctl.opt
lib: with (import ./param-constructors.nix lib);
let
certParams = {
file = mkOptionalStrParam ''
Absolute path to the certificate to load. Passed as-is to the daemon, so
it must be readable by it.
</para><para>
Configure either this or <option>handle</option>, but not both, in one section.
'';
handle = mkOptionalHexParam ''
Hex-encoded CKA_ID or handle of the certificate on a token or TPM,
respectively.
</para><para>
Configure either this or <option>file</option>, but not both, in one section.
'';
slot = mkOptionalIntParam ''
Optional slot number of the token that stores the certificate.
'';
module = mkOptionalStrParam ''
Optional PKCS#11 module name.
'';
};
in {
authorities = mkAttrsOfParams ({
cacert = mkOptionalStrParam ''
The certificates may use a relative path from the swanctl
<literal>x509ca</literal> directory or an absolute path.
</para><para>
Configure one of <option>cacert</option>,
<option>file</option>, or
<option>handle</option> per section.
'';
cert_uri_base = mkOptionalStrParam ''
Defines the base URI for the Hash and URL feature supported by
IKEv2. Instead of exchanging complete certificates, IKEv2 allows one to
send an URI that resolves to the DER encoded certificate. The certificate
URIs are built by appending the SHA1 hash of the DER encoded certificates
to this base URI.
'';
crl_uris = mkCommaSepListParam [] ''
List of CRL distribution points (ldap, http, or file URI).
'';
ocsp_uris = mkCommaSepListParam [] ''
List of OCSP URIs.
'';
} // certParams) ''
Section defining complementary attributes of certification authorities, each
in its own subsection with an arbitrary yet unique name
'';
connections = mkAttrsOfParams {
version = mkIntParam 0 ''
IKE major version to use for connection.
<itemizedlist>
<listitem><para>1 uses IKEv1 aka ISAKMP,</para></listitem>
<listitem><para>2 uses IKEv2.</para></listitem>
<listitem><para>A connection using the default of 0 accepts both IKEv1 and IKEv2 as
responder, and initiates the connection actively with IKEv2.</para></listitem>
</itemizedlist>
'';
local_addrs = mkCommaSepListParam [] ''
Local address(es) to use for IKE communication. Takes
single IPv4/IPv6 addresses, DNS names, CIDR subnets or IP address ranges.
</para><para>
As initiator, the first non-range/non-subnet is used to initiate the
connection from. As responder, the local destination address must match at
least to one of the specified addresses, subnets or ranges.
</para><para>
If FQDNs are assigned they are resolved every time a configuration lookup
is done. If DNS resolution times out, the lookup is delayed for that time.
'';
remote_addrs = mkCommaSepListParam [] ''
Remote address(es) to use for IKE communication. Takes
single IPv4/IPv6 addresses, DNS names, CIDR subnets or IP address ranges.
</para><para>
As initiator, the first non-range/non-subnet is used to initiate the
connection to. As responder, the initiator source address must match at
least to one of the specified addresses, subnets or ranges.
</para><para>
If FQDNs are assigned they are resolved every time a configuration lookup
is done. If DNS resolution times out, the lookup is delayed for that time.
To initiate a connection, at least one specific address or DNS name must
be specified.
'';
local_port = mkIntParam 500 ''
Local UDP port for IKE communication. By default the port of the socket
backend is used, which is usually <literal>500</literal>. If port
<literal>500</literal> is used, automatic IKE port floating to port
<literal>4500</literal> is used to work around NAT issues.
</para><para>
Using a non-default local IKE port requires support from the socket
backend in use (socket-dynamic).
'';
remote_port = mkIntParam 500 ''
Remote UDP port for IKE communication. If the default of port
<literal>500</literal> is used, automatic IKE port floating to port
<literal>4500</literal> is used to work around NAT issues.
'';
proposals = mkCommaSepListParam ["default"] ''
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.
</para><para>
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 kind is allowed per proposal, more algorithms get implicitly
stripped. Use multiple proposals to offer different algorithms
combinations in IKEv1.
</para><para>
Algorithm keywords get separated using dashes. Multiple proposals may be
specified in a list. The special value <literal>default</literal> forms a
default proposal of supported algorithms considered safe, and is usually a
good choice for interoperability.
'';
vips = mkCommaSepListParam [] ''
List of virtual IPs to request in IKEv2 configuration payloads or IKEv1
Mode Config. The wildcard addresses <literal>0.0.0.0</literal> and
<literal>::</literal> request an arbitrary address, specific addresses may
be defined. The responder may return a different address, though, or none
at all.
'';
aggressive = mkYesNoParam no ''
Enables Aggressive Mode instead of Main Mode with Identity
Protection. Aggressive Mode is considered less secure, because the ID and
HASH payloads are exchanged unprotected. This allows a passive attacker to
snoop peer identities, and even worse, start dictionary attacks on the
Preshared Key.
'';
pull = mkYesNoParam yes ''
If the default of yes is used, Mode Config works in pull mode, where the
initiator actively requests a virtual IP. With no, push mode is used,
where the responder pushes down a virtual IP to the initiating peer.
</para><para>
Push mode is currently supported for IKEv1, but not in IKEv2. It is used
by a few implementations only, pull mode is recommended.
'';
dscp = mkStrParam "000000" ''
Differentiated Services Field Codepoint to set on outgoing IKE packets for
this connection. The value is a six digit binary encoded string specifying
the Codepoint to set, as defined in RFC 2474.
'';
encap = mkYesNoParam no ''
To enforce UDP encapsulation of ESP packets, the IKE daemon can fake the
NAT detection payloads. This makes the peer believe that NAT takes place
on the path, forcing it to encapsulate ESP packets in UDP.
</para><para>
Usually this is not required, but it can help to work around connectivity
issues with too restrictive intermediary firewalls.
'';
mobike = mkYesNoParam yes ''
Enables MOBIKE on IKEv2 connections. MOBIKE is enabled by default on IKEv2
connections, and allows mobility of clients and multi-homing on servers by
migrating active IPsec tunnels.
</para><para>
Usually keeping MOBIKE enabled is unproblematic, as it is not used if the
peer does not indicate support for it. However, due to the design of
MOBIKE, IKEv2 always floats to port 4500 starting from the second
exchange. Some implementations don't like this behavior, hence it can be
disabled.
'';
dpd_delay = mkDurationParam "0s" ''
Interval to check the liveness of a peer actively using IKEv2
INFORMATIONAL exchanges or IKEv1 R_U_THERE messages. Active DPD checking
is only enforced if no IKE or ESP/AH packet has been received for the
configured DPD delay.
'';
dpd_timeout = mkDurationParam "0s" ''
Charon by default uses the normal retransmission mechanism and timeouts to
check the liveness of a peer, as all messages are used for liveness
checking. For compatibility reasons, with IKEv1 a custom interval may be
specified; this option has no effect on connections using IKEv2.
'';
fragmentation = mkEnumParam ["yes" "accept" "force" "no"] "yes" ''
Use IKE fragmentation (proprietary IKEv1 extension or RFC 7383 IKEv2
fragmentation). Acceptable values are <literal>yes</literal> (the default
since 5.5.1), <literal>accept</literal> (since versions:5.5.3),
<literal>force</literal> and <literal>no</literal>.
<itemizedlist>
<listitem><para>If set to <literal>yes</literal>, and the peer
supports it, oversized IKE messages will be sent in fragments.</para></listitem>
<listitem><para>If set to
<literal>accept</literal>, support for fragmentation is announced to the peer but the daemon
does not send its own messages in fragments.</para></listitem>
<listitem><para>If set to <literal>force</literal> (only
supported for IKEv1) the initial IKE message will already be fragmented if
required.</para></listitem>
<listitem><para>Finally, setting the option to <literal>no</literal> will disable announcing
support for this feature.</para></listitem>
</itemizedlist>
</para><para>
Note that fragmented IKE messages sent by a peer are always processed
irrespective of the value of this option (even when set to no).
'';
childless = mkEnumParam [ "allow" "force" "never" ] "allow" ''
Use childless IKE_SA initiation (RFC 6023) for IKEv2. Acceptable values
are <literal>allow</literal> (the default), <literal>force</literal> and
<literal>never</literal>. If set to <literal>allow</literal>, 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 CHILD_SA created during IKE_AUTH, unless the IKE_SA is initiated
explicitly without any children (which will fail if the responder does not
support or has disabled this extension). If set to
<literal>force</literal>, only childless initiation is accepted and the
first CHILD_SA is created with a separate CREATE_CHILD_SA exchange
(e.g. to use an independent DH exchange for all CHILD_SAs). Finally,
setting the option to <literal>never</literal> disables support for
childless IKE_SAs as responder.
'';
send_certreq = mkYesNoParam yes ''
Send certificate request payloads to offer trusted root CA certificates to
the peer. Certificate requests help the peer to choose an appropriate
certificate/private key for authentication and are enabled by default.
Disabling certificate requests can be useful if too many trusted root CA
certificates are installed, as each certificate request increases the size
of the initial IKE packets.
'';
send_cert = mkEnumParam ["always" "never" "ifasked" ] "ifasked" ''
Send certificate payloads when using certificate authentication.
<itemizedlist>
<listitem><para>With the default of <literal>ifasked</literal> the daemon sends
certificate payloads only if certificate requests have been received.</para></listitem>
<listitem><para><literal>never</literal> disables sending of certificate payloads
altogether,</para></listitem>
<listitem><para><literal>always</literal> causes certificate payloads to be sent
unconditionally whenever certificate authentication is used.</para></listitem>
</itemizedlist>
'';
ppk_id = mkOptionalStrParam ''
String identifying the Postquantum Preshared Key (PPK) to be used.
'';
ppk_required = mkYesNoParam no ''
Whether a Postquantum Preshared Key (PPK) is required for this connection.
'';
keyingtries = mkIntParam 1 ''
Number of retransmission sequences to perform during initial
connect. Instead of giving up initiation after the first retransmission
sequence with the default value of <literal>1</literal>, additional
sequences may be started according to the configured value. A value of
<literal>0</literal> initiates a new sequence until the connection
establishes or fails with a permanent error.
'';
unique = mkEnumParam ["no" "never" "keep" "replace"] "no" ''
Connection uniqueness policy to enforce. To avoid multiple connections
from the same user, a uniqueness policy can be enforced.
</para><para>
<itemizedlist>
<listitem><para>
The value <literal>never</literal> does never enforce such a policy, even
if a peer included INITIAL_CONTACT notification messages,
</para></listitem>
<listitem><para>
whereas <literal>no</literal> replaces existing connections for the same
identity if a new one has the INITIAL_CONTACT notify.
</para></listitem>
<listitem><para>
<literal>keep</literal> rejects new connection attempts if the same user
already has an active connection,
</para></listitem>
<listitem><para>
<literal>replace</literal> deletes any existing connection if a new one
for the same user gets established.
</para></listitem>
</itemizedlist>
To compare connections for uniqueness, the remote IKE identity is used. If
EAP or XAuth authentication is involved, the EAP-Identity or XAuth
username is used to enforce the uniqueness policy instead.
</para><para>
On initiators this setting specifies whether an INITIAL_CONTACT notify is
sent during IKE_AUTH if no existing connection is found with the remote
peer (determined by the identities of the first authentication
round). Unless set to <literal>never</literal> the client will send a notify.
'';
reauth_time = mkDurationParam "0s" ''
Time to schedule IKE reauthentication. IKE reauthentication recreates the
IKE/ISAKMP SA from scratch and re-evaluates the credentials. In asymmetric
configurations (with EAP or configuration payloads) it might not be
possible to actively reauthenticate as responder. The IKEv2
reauthentication lifetime negotiation can instruct the client to perform
reauthentication.
</para><para>
Reauthentication is disabled by default. Enabling it usually may lead to
small connection interruptions, as strongSwan uses a break-before-make
policy with IKEv2 to avoid any conflicts with associated tunnel resources.
'';
rekey_time = mkDurationParam "4h" ''
IKE rekeying refreshes key material using a Diffie-Hellman exchange, but
does not re-check associated credentials. It is supported in IKEv2 only,
IKEv1 performs a reauthentication procedure instead.
</para><para>
With the default value IKE rekeying is scheduled every 4 hours, minus the
configured rand_time. If a reauth_time is configured, rekey_time defaults
to zero, disabling rekeying; explicitly set both to enforce rekeying and
reauthentication.
'';
over_time = mkOptionalDurationParam ''
Hard IKE_SA lifetime if rekey/reauth does not complete, as time. To avoid
having an IKE/ISAKMP kept alive if IKE reauthentication or rekeying fails
perpetually, a maximum hard lifetime may be specified. If the IKE_SA fails
to rekey or reauthenticate within the specified time, the IKE_SA gets
closed.
</para><para>
In contrast to CHILD_SA rekeying, over_time is relative in time to the
rekey_time and reauth_time values, as it applies to both.
</para><para>
The default is 10% of the longer of <option>rekey_time</option> and
<option>reauth_time</option>.
'';
rand_time = mkOptionalDurationParam ''
Time range from which to choose a random value to subtract from
rekey/reauth times. To avoid having both peers initiating the rekey/reauth
procedure simultaneously, a random time gets subtracted from the
rekey/reauth times.
</para><para>
The default is equal to the configured <option>over_time</option>.
'';
pools = mkCommaSepListParam [] ''
List of named IP pools to allocate virtual IP addresses
and other configuration attributes from. Each name references a pool by
name from either the pools section or an external pool.
'';
if_id_in = mkStrParam "0" ''
XFRM interface ID set on inbound policies/SA, can be overridden by child
config, see there for details.
'';
if_id_out = mkStrParam "0" ''
XFRM interface ID set on outbound policies/SA, can be overridden by child
config, see there for details.
'';
mediation = mkYesNoParam no ''
Whether this connection is a mediation connection, that is, whether this
connection is used to mediate other connections using the IKEv2 Mediation
Extension. Mediation connections create no CHILD_SA.
'';
mediated_by = mkOptionalStrParam ''
The name of the connection to mediate this connection through. If given,
the connection will be mediated through the named mediation
connection. The mediation connection must have mediation enabled.
'';
mediation_peer = mkOptionalStrParam ''
Identity under which the peer is registered at the mediation server, that
is, the IKE identity the other end of this connection uses as its local
identity on its connection to the mediation server. This is the identity
we request the mediation server to mediate us with. Only relevant on
connections that set mediated_by. If it is not given, the remote IKE
identity of the first authentication round of this connection will be
used.
'';
local = mkPrefixedAttrsOfParams {
round = mkIntParam 0 ''
Optional numeric identifier by which authentication rounds are
sorted. If not specified rounds are ordered by their position in the
config file/vici message.
'';
certs = mkCommaSepListParam [] ''
List of certificate candidates to use for
authentication. The certificates may use a relative path from the
swanctl <literal>x509</literal> directory or an absolute path.
</para><para>
The certificate used for authentication is selected based on the
received certificate request payloads. If no appropriate CA can be
located, the first certificate is used.
'';
cert = mkPostfixedAttrsOfParams certParams ''
Section for a certificate candidate to use for
authentication. Certificates in certs are transmitted as binary blobs,
these sections offer more flexibility.
'';
pubkeys = mkCommaSepListParam [] ''
List of raw public key candidates to use for
authentication. The public keys may use a relative path from the swanctl
<literal>pubkey</literal> directory or an absolute path.
</para><para>
Even though multiple local public keys could be defined in principle,
only the first public key in the list is used for authentication.
'';
auth = mkStrParam "pubkey" ''
Authentication to perform locally.
<itemizedlist>
<listitem><para>
The default <literal>pubkey</literal> uses public key authentication
using a private key associated to a usable certificate.
</para></listitem>
<listitem><para>
<literal>psk</literal> uses pre-shared key authentication.
</para></listitem>
<listitem><para>
The IKEv1 specific <literal>xauth</literal> is used for XAuth or Hybrid
authentication,
</para></listitem>
<listitem><para>
while the IKEv2 specific <literal>eap</literal> keyword defines EAP
authentication.
</para></listitem>
<listitem><para>
For <literal>xauth</literal>, a specific backend name may be appended,
separated by a dash. The appropriate <literal>xauth</literal> backend is
selected to perform the XAuth exchange. For traditional XAuth, the
<literal>xauth</literal> method is usually defined in the second
authentication round following an initial <literal>pubkey</literal> (or
<literal>psk</literal>) round. Using <literal>xauth</literal> in the
first round performs Hybrid Mode client authentication.
</para></listitem>
<listitem><para>
For <literal>eap</literal>, a specific EAP method name may be appended, separated by a
dash. An EAP module implementing the appropriate method is selected to
perform the EAP conversation.
</para></listitem>
<listitem><para>
Since 5.4.0, if both peers support RFC 7427 ("Signature Authentication
in IKEv2") specific hash algorithms to be used during IKEv2
authentication may be configured. To do so use <literal>ike:</literal>
followed by a trust chain signature scheme constraint (see description
of the <option>remote</option> section's <option>auth</option>
keyword). For example, with <literal>ike:pubkey-sha384-sha256</literal>
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. If no constraints with
<literal>ike:</literal> prefix are configured any signature scheme
constraint (without <literal>ike:</literal> prefix) will also apply to
IKEv2 authentication, unless this is disabled in
<literal>strongswan.conf</literal>. To use RSASSA-PSS signatures use
<literal>rsa/pss</literal> instead of <literal>pubkey</literal> or
<literal>rsa</literal> as in e.g.
<literal>ike:rsa/pss-sha256</literal>. If <literal>pubkey</literal> or
<literal>rsa</literal> constraints are configured RSASSA-PSS signatures
will only be used if enabled in <literal>strongswan.conf</literal>(5).
</para></listitem>
</itemizedlist>
'';
id = mkOptionalStrParam ''
IKE identity to use for authentication round. When using certificate
authentication, the IKE identity must be contained in the certificate,
either as subject or as subjectAltName.
'';
eap_id = mkOptionalStrParam ''
Client EAP-Identity to use in EAP-Identity exchange and the EAP method.
'';
aaa_id = mkOptionalStrParam ''
Server side EAP-Identity to expect in the EAP method. Some EAP methods,
such as EAP-TLS, use an identity for the server to perform mutual
authentication. This identity may differ from the IKE identity,
especially when EAP authentication is delegated from the IKE responder
to an AAA backend.
</para><para>
For EAP-(T)TLS, this defines the identity for which the server must
provide a certificate in the TLS exchange.
'';
xauth_id = mkOptionalStrParam ''
Client XAuth username used in the XAuth exchange.
'';
} ''
Section for a local authentication round. A local authentication round
defines the rules how authentication is performed for the local
peer. Multiple rounds may be defined to use IKEv2 RFC 4739 Multiple
Authentication or IKEv1 XAuth.
</para><para>
Each round is defined in a section having <literal>local</literal> as
prefix, and an optional unique suffix. To define a single authentication
round, the suffix may be omitted.
'';
remote = mkPrefixedAttrsOfParams {
round = mkIntParam 0 ''
Optional numeric identifier by which authentication rounds are
sorted. If not specified rounds are ordered by their position in the
config file/vici message.
'';
id = mkStrParam "%any" ''
IKE identity to expect for authentication round. When using certificate
authentication, the IKE identity must be contained in the certificate,
either as subject or as subjectAltName.
'';
eap_id = mkOptionalStrParam ''
Identity to use as peer identity during EAP authentication. If set to
<literal>%any</literal> the EAP-Identity method will be used to ask the
client for an EAP identity.
'';
groups = mkCommaSepListParam [] ''
Authorization group memberships to require. The peer
must prove membership to at least one of the specified groups. Group
membership can be certified by different means, for example by
appropriate Attribute Certificates or by an AAA backend involved in the
authentication.
'';
cert_policy = mkCommaSepListParam [] ''
List of certificate policy OIDs the peer's certificate
must have. OIDs are specified using the numerical dotted representation.
'';
certs = mkCommaSepListParam [] ''
List of certificates to accept for authentication. The certificates may
use a relative path from the swanctl <literal>x509</literal> directory
or an absolute path.
'';
cert = mkPostfixedAttrsOfParams certParams ''
Section for a certificate candidate to use for
authentication. Certificates in certs are transmitted as binary blobs,
these sections offer more flexibility.
'';
cacerts = mkCommaSepListParam [] ''
List of CA certificates to accept for
authentication. The certificates may use a relative path from the
swanctl <literal>x509ca</literal> directory or an absolute path.
'';
cacert = mkPostfixedAttrsOfParams certParams ''
Section for a CA certificate to accept for authentication. Certificates
in cacerts are transmitted as binary blobs, these sections offer more
flexibility.
'';
pubkeys = mkCommaSepListParam [] ''
List of raw public keys to accept for
authentication. The public keys may use a relative path from the swanctl
<literal>pubkey</literal> directory or an absolute path.
'';
revocation = mkEnumParam ["strict" "ifuri" "relaxed"] "relaxed" ''
Certificate revocation policy for CRL or OCSP revocation.
<itemizedlist>
<listitem><para>
A <literal>strict</literal> revocation policy fails if no revocation information is
available, i.e. the certificate is not known to be unrevoked.
</para></listitem>
<listitem><para>
<literal>ifuri</literal> fails only if a CRL/OCSP URI is available, but certificate
revocation checking fails, i.e. there should be revocation information
available, but it could not be obtained.
</para></listitem>
<listitem><para>
The default revocation policy <literal>relaxed</literal> fails only if a certificate is
revoked, i.e. it is explicitly known that it is bad.
</para></listitem>
</itemizedlist>
'';
auth = mkStrParam "pubkey" ''
Authentication to expect from remote. See the <option>local</option>
section's <option>auth</option> keyword description about the details of
supported mechanisms.
</para><para>
Since 5.4.0, to require a trustchain public key strength for the remote
side, specify the key type followed by the minimum strength in bits (for
example <literal>ecdsa-384</literal> or
<literal>rsa-2048-ecdsa-256</literal>). To limit the acceptable set of
hashing algorithms for trustchain validation, append hash algorithms to
pubkey or a key strength definition (for example
<literal>pubkey-sha256-sha512</literal>,
<literal>rsa-2048-sha256-sha384-sha512</literal> or
<literal>rsa-2048-sha256-ecdsa-256-sha256-sha384</literal>).
Unless disabled in <literal>strongswan.conf</literal>, or explicit IKEv2
signature constraints are configured (refer to the description of the
<option>local</option> section's <option>auth</option> keyword for
details), such key types and hash algorithms are also applied as
constraints against IKEv2 signature authentication schemes used by the
remote side. To require RSASSA-PSS signatures use
<literal>rsa/pss</literal> instead of <literal>pubkey</literal> or
<literal>rsa</literal> as in e.g. <literal>rsa/pss-sha256</literal>. If
<literal>pubkey</literal> or <literal>rsa</literal> constraints are
configured RSASSA-PSS signatures will only be accepted if enabled in
<literal>strongswan.conf</literal>(5).
</para><para>
To specify 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 (e.g. <literal>eap-tls:ecdsa-384-sha384</literal>).
'';
} ''
Section for a remote authentication round. A remote authentication round
defines the constraints how the peers must authenticate to use this
connection. Multiple rounds may be defined to use IKEv2 RFC 4739 Multiple
Authentication or IKEv1 XAuth.
</para><para>
Each round is defined in a section having <literal>remote</literal> as
prefix, and an optional unique suffix. To define a single authentication
round, the suffix may be omitted.
'';
children = mkAttrsOfParams {
ah_proposals = mkCommaSepListParam [] ''
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).
</para><para>
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 kind is allowed per proposal, more algorithms get
implicitly stripped. Use multiple proposals to offer different algorithms
combinations in IKEv1.
</para><para>
Algorithm keywords get separated using dashes. Multiple proposals may be
specified in a list. The special value <literal>default</literal> forms
a default proposal of supported algorithms considered safe, and is
usually a good choice for interoperability. By default no AH proposals
are included, instead ESP is proposed.
'';
esp_proposals = mkCommaSepListParam ["default"] ''
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 Extended Sequence Number Mode indicator. For AEAD proposals,
a combined mode algorithm is used instead of the separate
encryption/integrity algorithms.
</para><para>
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.
</para><para>
Extended Sequence Number support may be indicated with the
<literal>esn</literal> and <literal>noesn</literal> values, both may be
included to indicate support for both modes. If omitted,
<literal>noesn</literal> is assumed.
</para><para>
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 kind is allowed per proposal, more algorithms get
implicitly stripped. Use multiple proposals to offer different algorithms
combinations in IKEv1.
</para><para>
Algorithm keywords get separated using dashes. Multiple proposals may be
specified as a list. The special value <literal>default</literal> 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 ESP, the default set of algorithms for ESP is
included.
'';
sha256_96 = mkYesNoParam no ''
HMAC-SHA-256 is used with 128-bit truncation with IPsec. For
compatibility with implementations that incorrectly use 96-bit truncation
this option may be enabled to configure the shorter truncation length in
the kernel. This is not negotiated, so this only works with peers that
use the incorrect truncation length (or have this option enabled).
'';
local_ts = mkCommaSepListParam ["dynamic"] ''
List of local traffic selectors to include in CHILD_SA. Each selector is
a CIDR subnet definition, followed by an optional proto/port
selector. The special value <literal>dynamic</literal> may be used
instead of a subnet definition, which gets replaced by the tunnel outer
address or the virtual IP, if negotiated. This is the default.
</para><para>
A protocol/port selector is surrounded by opening and closing square
brackets. Between these brackets, a numeric or getservent(3) protocol
name may be specified. After the optional protocol restriction, an
optional port restriction may be specified, separated by a slash. The
port restriction may be numeric, a getservent(3) service name, or the
special value <literal>opaque</literal> for RFC 4301 OPAQUE
selectors. Port ranges may be specified as well, none of the kernel
backends currently support port ranges, though.
</para><para>
When IKEv1 is used only the first selector is interpreted, except if the
Cisco Unity extension plugin is used. This is due to a limitation of the
IKEv1 protocol, which only allows a single pair of selectors per
CHILD_SA. So to tunnel traffic matched by several pairs of selectors when
using IKEv1 several children (CHILD_SAs) have to be defined that cover
the selectors. The IKE daemon uses traffic selector narrowing for IKEv1,
the same way it is standardized and implemented for IKEv2. However, this
may lead to problems with other implementations. To avoid that, configure
identical selectors in such scenarios.
'';
remote_ts = mkCommaSepListParam ["dynamic"] ''
List of remote selectors to include in CHILD_SA. See
<option>local_ts</option> for a description of the selector syntax.
'';
rekey_time = mkDurationParam "1h" ''
Time to schedule CHILD_SA rekeying. CHILD_SA rekeying refreshes key
material, optionally using a Diffie-Hellman exchange if a group is
specified in the proposal. To avoid rekey collisions initiated by both
ends simultaneously, a value in the range of <option>rand_time</option>
gets subtracted to form the effective soft lifetime.
</para><para>
By default CHILD_SA rekeying is scheduled every hour, minus
<option>rand_time</option>.
'';
life_time = mkOptionalDurationParam ''
Maximum lifetime before CHILD_SA gets closed. Usually this hard lifetime
is never reached, because the CHILD_SA gets rekeyed before. If that fails
for whatever reason, this limit closes the CHILD_SA. The default is 10%
more than the <option>rekey_time</option>.
'';
rand_time = mkOptionalDurationParam ''
Time range from which to choose a random value to subtract from
<option>rekey_time</option>. The default is the difference between
<option>life_time</option> and <option>rekey_time</option>.
'';
rekey_bytes = mkIntParam 0 ''
Number of bytes processed before initiating CHILD_SA rekeying. CHILD_SA
rekeying refreshes key material, optionally using a Diffie-Hellman
exchange if a group is specified in the proposal.
</para><para>
To avoid rekey collisions initiated by both ends simultaneously, a value
in the range of <option>rand_bytes</option> gets subtracted to form the
effective soft volume limit.
</para><para>
Volume based CHILD_SA rekeying is disabled by default.
'';
life_bytes = mkOptionalIntParam ''
Maximum bytes processed before CHILD_SA gets closed. Usually this hard
volume limit is never reached, because the CHILD_SA gets rekeyed
before. If that fails for whatever reason, this limit closes the
CHILD_SA. The default is 10% more than <option>rekey_bytes</option>.
'';
rand_bytes = mkOptionalIntParam ''
Byte range from which to choose a random value to subtract from
<option>rekey_bytes</option>. The default is the difference between
<option>life_bytes</option> and <option>rekey_bytes</option>.
'';
rekey_packets = mkIntParam 0 ''
Number of packets processed before initiating CHILD_SA rekeying. CHILD_SA
rekeying refreshes key material, optionally using a Diffie-Hellman
exchange if a group is specified in the proposal.
</para><para>
To avoid rekey collisions initiated by both ends simultaneously, a value
in the range of <option>rand_packets</option> gets subtracted to form
the effective soft packet count limit.
</para><para>
Packet count based CHILD_SA rekeying is disabled by default.
'';
life_packets = mkOptionalIntParam ''
Maximum number of packets processed before CHILD_SA gets closed. Usually
this hard packets limit is never reached, because the CHILD_SA gets
rekeyed before. If that fails for whatever reason, this limit closes the
CHILD_SA.
</para><para>
The default is 10% more than <option>rekey_bytes</option>.
'';
rand_packets = mkOptionalIntParam ''
Packet range from which to choose a random value to subtract from
<option>rekey_packets</option>. The default is the difference between
<option>life_packets</option> and <option>rekey_packets</option>.
'';
updown = mkOptionalStrParam ''
Updown script to invoke on CHILD_SA up and down events.
'';
hostaccess = mkYesNoParam no ''
Hostaccess variable to pass to <literal>updown</literal> script.
'';
mode = mkEnumParam [ "tunnel"
"transport"
"transport_proxy"
"beet"
"pass"
"drop"
] "tunnel" ''
IPsec Mode to establish CHILD_SA with.
<itemizedlist>
<listitem><para>
<literal>tunnel</literal> negotiates the CHILD_SA in IPsec Tunnel Mode,
</para></listitem>
<listitem><para>
whereas <literal>transport</literal> uses IPsec Transport Mode.
</para></listitem>
<listitem><para>
<literal>transport_proxy</literal> signifying the special Mobile IPv6
Transport Proxy Mode.
</para></listitem>
<listitem><para>
<literal>beet</literal> is the Bound End to End Tunnel mixture mode,
working with fixed inner addresses without the need to include them in
each packet.
</para></listitem>
<listitem><para>
Both <literal>transport</literal> and <literal>beet</literal> modes are
subject to mode negotiation; <literal>tunnel</literal> mode is
negotiated if the preferred mode is not available.
</para></listitem>
<listitem><para>
<literal>pass</literal> and <literal>drop</literal> are used to install
shunt policies which explicitly bypass the defined traffic from IPsec
processing or drop it, respectively.
</para></listitem>
</itemizedlist>
'';
policies = mkYesNoParam yes ''
Whether to install IPsec policies or not. Disabling this can be useful in
some scenarios e.g. MIPv6, where policies are not managed by the IKE
daemon. Since 5.3.3.
'';
policies_fwd_out = mkYesNoParam no ''
Whether to install outbound FWD IPsec policies or not. Enabling this is
required in case there is a drop policy that would match and block
forwarded traffic for this CHILD_SA. Since 5.5.1.
'';
dpd_action = mkEnumParam ["clear" "trap" "restart"] "clear" ''
Action to perform for this CHILD_SA on DPD timeout. The default clear
closes the CHILD_SA and does not take further action. trap installs a
trap policy, which will catch matching traffic and tries to re-negotiate
the tunnel on-demand. restart immediately tries to re-negotiate the
CHILD_SA under a fresh IKE_SA.
'';
ipcomp = mkYesNoParam no ''
Enable IPComp compression before encryption. If enabled, IKE tries to
negotiate IPComp compression to compress ESP payload data prior to
encryption.
'';
inactivity = mkDurationParam "0s" ''
Timeout before closing CHILD_SA after inactivity. If no traffic has been
processed in either direction for the configured timeout, the CHILD_SA
gets closed due to inactivity. The default value of 0 disables inactivity
checks.
'';
reqid = mkIntParam 0 ''
Fixed reqid to use for this CHILD_SA. This might be helpful in some
scenarios, but works only if each CHILD_SA configuration is instantiated
not more than once. The default of 0 uses dynamic reqids, allocated
incrementally.
'';
priority = mkIntParam 0 ''
Optional fixed priority for IPsec policies. This could be useful to
install high-priority drop policies. The default of 0 uses dynamically
calculated priorities based on the size of the traffic selectors.
'';
interface = mkOptionalStrParam ''
Optional interface name to restrict outbound IPsec policies.
'';
mark_in = mkStrParam "0/0x00000000" ''
Netfilter mark and mask for input traffic. On Linux, Netfilter may
require marks on each packet to match an SA/policy having that option
set. This allows installing duplicate policies and enables Netfilter
rules to select specific SAs/policies for incoming traffic. Note that
inbound marks are only set on policies, by default, unless
<option>mark_in_sa</option> is enabled. The special value
<literal>%unique</literal> sets a unique mark on each CHILD_SA instance,
beyond that the value <literal>%unique-dir</literal> assigns a different
unique mark for each
</para><para>
An additional mask may be appended to the mark, separated by
<literal>/</literal>. The default mask if omitted is
<literal>0xffffffff</literal>.
'';
mark_in_sa = mkYesNoParam no ''
Whether to set <option>mark_in</option> on the inbound SA. By default,
the inbound mark is only set on the inbound policy. The tuple destination
address, protocol and SPI is unique and the mark is not required to find
the correct SA, allowing to mark traffic after decryption instead (where
more specific selectors may be used) to match different policies. Marking
packets before decryption is still possible, even if no mark is set on
the SA.
'';
mark_out = mkStrParam "0/0x00000000" ''
Netfilter mark and mask for output traffic. On Linux, Netfilter may
require marks on each packet to match a policy/SA having that option
set. This allows installing duplicate policies and enables Netfilter
rules to select specific policies/SAs for outgoing traffic. The special
value <literal>%unique</literal> sets a unique mark on each CHILD_SA
instance, beyond that the value <literal>%unique-dir</literal> assigns a
different unique mark for each CHILD_SA direction (in/out).
</para><para>
An additional mask may be appended to the mark, separated by
<literal>/</literal>. The default mask if omitted is
<literal>0xffffffff</literal>.
'';
set_mark_in = mkStrParam "0/0x00000000" ''
Netfilter mark applied to packets after the inbound IPsec SA processed
them. This way it's not necessary to mark packets via Netfilter before
decryption or right afterwards to match policies or process them
differently (e.g. via policy routing).
An additional mask may be appended to the mark, separated by
<literal>/</literal>. The default mask if omitted is 0xffffffff. The
special value <literal>%same</literal> uses the value (but not the mask)
from <option>mark_in</option> as mark value, which can be fixed,
<literal>%unique</literal> or <literal>%unique-dir</literal>.
Setting marks in XFRM input requires Linux 4.19 or higher.
'';
set_mark_out = mkStrParam "0/0x00000000" ''
Netfilter mark applied to packets after the outbound IPsec SA processed
them. This allows processing ESP packets differently than the original
traffic (e.g. via policy routing).
An additional mask may be appended to the mark, separated by
<literal>/</literal>. The default mask if omitted is 0xffffffff. The
special value <literal>%same</literal> uses the value (but not the mask)
from <option>mark_out</option> as mark value, which can be fixed,
<literal>%unique_</literal> or <literal>%unique-dir</literal>.
Setting marks in XFRM output is supported since Linux 4.14. Setting a
mask requires at least Linux 4.19.
'';
if_id_in = mkStrParam "0" ''
XFRM interface ID set on inbound policies/SA. This allows installing
duplicate policies/SAs and associates them with an interface with the
same ID. The special value <literal>%unique</literal> sets a unique
interface ID on each CHILD_SA instance, beyond that the value
<literal>%unique-dir</literal> assigns a different unique interface ID
for each CHILD_SA direction (in/out).
'';
if_id_out = mkStrParam "0" ''
XFRM interface ID set on outbound policies/SA. This allows installing
duplicate policies/SAs and associates them with an interface with the
same ID. The special value <literal>%unique</literal> sets a unique
interface ID on each CHILD_SA instance, beyond that the value
<literal>%unique-dir</literal> assigns a different unique interface ID
for each CHILD_SA direction (in/out).
The daemon will not install routes for CHILD_SAs that have this option set.
'';
tfc_padding = mkParamOfType (with lib.types; either int (enum ["mtu"])) 0 ''
Pads ESP packets with additional data to have a consistent ESP packet
size for improved Traffic Flow Confidentiality. The padding defines the
minimum size of all ESP packets sent. The default value of
<literal>0</literal> disables TFC padding, the special value
<literal>mtu</literal> adds TFC padding to create a packet size equal to
the Path Maximum Transfer Unit.
'';
replay_window = mkIntParam 32 ''
IPsec replay window to configure for this CHILD_SA. Larger values than
the default of <literal>32</literal> are supported using the Netlink
backend only, a value of <literal>0</literal> disables IPsec replay
protection.
'';
hw_offload = mkEnumParam ["yes" "no" "auto"] "no" ''
Enable hardware offload for this CHILD_SA, if supported by the IPsec
implementation. The value <literal>yes</literal> enforces offloading
and the installation will fail if it's not supported by either kernel or
device. The value <literal>auto</literal> enables offloading, if it's
supported, but the installation does not fail otherwise.
'';
copy_df = mkYesNoParam yes ''
Whether to copy the DF bit to the outer IPv4 header in tunnel mode. This
effectively disables Path MTU discovery (PMTUD). Controlling this
behavior is not supported by all kernel interfaces.
'';
copy_ecn = mkYesNoParam yes ''
Whether to copy the ECN (Explicit Congestion Notification) header field
to/from the outer IP header in tunnel mode. Controlling this behavior is
not supported by all kernel interfaces.
'';
copy_dscp = mkEnumParam [ "out" "in" "yes" "no" ] "out" ''
Whether to copy the DSCP (Differentiated Services Field Codepoint)
header field to/from the outer IP header in tunnel mode. The value
<literal>out</literal> only copies the field from the inner to the outer
header, the value <literal>in</literal> does the opposite and only
copies the field from the outer to the inner header when decapsulating,
the value <literal>yes</literal> copies the field in both directions,
and the value <literal>no</literal> disables copying the field
altogether. Setting this to <literal>yes</literal> or
<literal>in</literal> could allow an attacker to adversely affect other
traffic at the receiver, which is why the default is
<literal>out</literal>. Controlling this behavior is not supported by
all kernel interfaces.
'';
start_action = mkEnumParam ["none" "trap" "start"] "none" ''
Action to perform after loading the configuration.
<itemizedlist>
<listitem><para>
The default of <literal>none</literal> loads the connection only, which
then can be manually initiated or used as a responder configuration.
</para></listitem>
<listitem><para>
The value <literal>trap</literal> installs a trap policy, which triggers
the tunnel as soon as matching traffic has been detected.
</para></listitem>
<listitem><para>
The value <literal>start</literal> initiates the connection actively.
</para></listitem>
</itemizedlist>
When unloading or replacing a CHILD_SA configuration having a
<option>start_action</option> different from <literal>none</literal>,
the inverse action is performed. Configurations with
<literal>start</literal> get closed, while such with
<literal>trap</literal> get uninstalled.
'';
close_action = mkEnumParam ["none" "trap" "start"] "none" ''
Action to perform after a CHILD_SA gets closed by the peer.
<itemizedlist>
<listitem><para>
The default of <literal>none</literal> does not take any action,
</para></listitem>
<listitem><para>
<literal>trap</literal> installs a trap policy for the CHILD_SA.
</para></listitem>
<listitem><para>
<literal>start</literal> tries to re-create the CHILD_SA.
</para></listitem>
</itemizedlist>
</para><para>
<option>close_action</option> does not provide any guarantee that the
CHILD_SA is kept alive. It acts on explicit close messages only, but not
on negotiation failures. Use trap policies to reliably re-create failed
CHILD_SAs.
'';
} ''
CHILD_SA configuration sub-section. Each connection definition may have
one or more sections in its <option>children</option> subsection. The
section name defines the name of the CHILD_SA configuration, which must be
unique within the connection (denoted <child> below).
'';
} ''
Section defining IKE connection configurations, each in its own subsection
with an arbitrary yet unique name
'';
secrets = let
mkEapXauthParams = mkPrefixedAttrsOfParams {
secret = mkOptionalStrParam ''
Value of the EAP/XAuth secret. It may either be an ASCII string, a hex
encoded string if it has a 0x prefix or a Base64 encoded string if it
has a 0s prefix in its value.
'';
id = mkPrefixedAttrsOfParam (mkOptionalStrParam "") ''
Identity the EAP/XAuth secret belongs to. Multiple unique identities may
be specified, each having an <literal>id</literal> prefix, if a secret
is shared between multiple users.
'';
} ''
EAP secret section for a specific secret. Each EAP secret is defined in a
unique section having the <literal>eap</literal> prefix. EAP secrets are
used for XAuth authentication as well.
'';
in {
eap = mkEapXauthParams;
xauth = mkEapXauthParams;
ntlm = mkPrefixedAttrsOfParams {
secret = mkOptionalStrParam ''
Value of the NTLM secret, which is the NT Hash of the actual secret,
that is, MD4(UTF-16LE(secret)). The resulting 16-byte value may either
be given as a hex encoded string with a 0x prefix or as a Base64 encoded
string with a 0s prefix.
'';
id = mkPrefixedAttrsOfParam (mkOptionalStrParam "") ''
Identity the NTLM secret belongs to. Multiple unique identities may be
specified, each having an id prefix, if a secret is shared between
multiple users.
'';
} ''
NTLM secret section for a specific secret. Each NTLM secret is defined in
a unique section having the <literal>ntlm</literal> prefix. NTLM secrets
may only be used for EAP-MSCHAPv2 authentication.
'';
ike = mkPrefixedAttrsOfParams {
secret = mkOptionalStrParam ''
Value of the IKE preshared secret. It may either be an ASCII string, a
hex encoded string if it has a 0x prefix or a Base64 encoded string if
it has a 0s prefix in its value.
'';
id = mkPrefixedAttrsOfParam (mkOptionalStrParam "") ''
IKE identity the IKE preshared secret belongs to. Multiple unique
identities may be specified, each having an <literal>id</literal>
prefix, if a secret is shared between multiple peers.
'';
} ''
IKE preshared secret section for a specific secret. Each IKE PSK is
defined in a unique section having the <literal>ike</literal> prefix.
'';
ppk = mkPrefixedAttrsOfParams {
secret = mkOptionalStrParam ''
Value of the PPK. It may either be an ASCII string, a hex encoded string
if it has a <literal>0x</literal> prefix or a Base64 encoded string if
it has a <literal>0s</literal> prefix in its value. Should have at least
256 bits of entropy for 128-bit security.
'';
id = mkPrefixedAttrsOfParam (mkOptionalStrParam "") ''
PPK identity the PPK belongs to. Multiple unique identities may be
specified, each having an <literal>id</literal> prefix, if a secret is
shared between multiple peers.
'';
} ''
Postquantum Preshared Key (PPK) section for a specific secret. Each PPK is
defined in a unique section having the <literal>ppk</literal> prefix.
'';
private = mkPrefixedAttrsOfParams {
file = mkOptionalStrParam ''
File name in the private folder for which this passphrase should be used.
'';
secret = mkOptionalStrParam ''
Value of decryption passphrase for private key.
'';
} ''
Private key decryption passphrase for a key in the
<literal>private</literal> folder.
'';
rsa = mkPrefixedAttrsOfParams {
file = mkOptionalStrParam ''
File name in the <literal>rsa</literal> folder for which this passphrase
should be used.
'';
secret = mkOptionalStrParam ''
Value of decryption passphrase for RSA key.
'';
} ''
Private key decryption passphrase for a key in the <literal>rsa</literal>
folder.
'';
ecdsa = mkPrefixedAttrsOfParams {
file = mkOptionalStrParam ''
File name in the <literal>ecdsa</literal> folder for which this
passphrase should be used.
'';
secret = mkOptionalStrParam ''
Value of decryption passphrase for ECDSA key.
'';
} ''
Private key decryption passphrase for a key in the
<literal>ecdsa</literal> folder.
'';
pkcs8 = mkPrefixedAttrsOfParams {
file = mkOptionalStrParam ''
File name in the <literal>pkcs8</literal> folder for which this
passphrase should be used.
'';
secret = mkOptionalStrParam ''
Value of decryption passphrase for PKCS#8 key.
'';
} ''
Private key decryption passphrase for a key in the
<literal>pkcs8</literal> folder.
'';
pkcs12 = mkPrefixedAttrsOfParams {
file = mkOptionalStrParam ''
File name in the <literal>pkcs12</literal> folder for which this
passphrase should be used.
'';
secret = mkOptionalStrParam ''
Value of decryption passphrase for PKCS#12 container.
'';
} ''
PKCS#12 decryption passphrase for a container in the
<literal>pkcs12</literal> folder.
'';
token = mkPrefixedAttrsOfParams {
handle = mkOptionalHexParam ''
Hex-encoded CKA_ID or handle of the private key on the token or TPM,
respectively.
'';
slot = mkOptionalIntParam ''
Optional slot number to access the token.
'';
module = mkOptionalStrParam ''
Optional PKCS#11 module name to access the token.
'';
pin = mkOptionalStrParam ''
Optional PIN required to access the key on the token. If none is
provided the user is prompted during an interactive
<literal>--load-creds</literal> call.
'';
} ''Definition for a private key that's stored on a token/smartcard/TPM.'';
};
pools = mkAttrsOfParams {
addrs = mkOptionalStrParam ''
Subnet or range defining addresses allocated in pool. Accepts a single
CIDR subnet defining the pool to allocate addresses from or an address
range (<from>-<to>). Pools must be unique and non-overlapping.
'';
dns = mkCommaSepListParam [] "Address or CIDR subnets";
nbns = mkCommaSepListParam [] "Address or CIDR subnets";
dhcp = mkCommaSepListParam [] "Address or CIDR subnets";
netmask = mkCommaSepListParam [] "Address or CIDR subnets";
server = mkCommaSepListParam [] "Address or CIDR subnets";
subnet = mkCommaSepListParam [] "Address or CIDR subnets";
split_include = mkCommaSepListParam [] "Address or CIDR subnets";
split_exclude = mkCommaSepListParam [] "Address or CIDR subnets";
} ''
Section defining named pools. Named pools may be referenced by connections
with the pools option to assign virtual IPs and other configuration
attributes. Each pool must have a unique name (denoted <name> below).
'';
}
