IPv6 is supported with NETKEY and with KLIPS in all Libreswan versions

If using IP addresses in combination with NAT, always use the actual local machine´s (NATed) IP address, and if the remote (eg right=) is NATed as well, the remote´s public (not NATed) IP address. Note that this makes the configuration no longer symmetrical on both sides, so you cannot use an identical configuration file on both hosts.

It supports two magic shorthands vhost: and vnet:, which can list subnets in the same syntax as virtual-private. The value %priv expands to the networks specified in virtual-private. The value %no means no subnet. A common use for allowing roadwarriors to come in on public IPs or via accepted NATed networks from RFC1918 is to use leftsubnet=vhost:%no,%priv. The vnet: option can be used to allow RFC1918 subnets without hardcoding them. When using vnet the connection will instantiate, allowing for multiple tunnels with different subnets.

When leftaddresspool= is specified, the connection may not specify either leftsubnet= or leftsubnets=. Address pools are fully allocated when the connection is loaded, so the ranges should be sane. For example, specifying a range rightaddresspool=10.0.0.0-11.0.0.0 will lead to massive memory allocation. Address pools specifying the exact same range are shared between different connections. Different addresspools should not be defined to partially overlap.

To filter on specific icmp type and code, use the higher 8 bits for type and the lower 8 bits for port. For example, to allow icmp echo packets (type 8, code 0) the ´port´ would be 0x0800, or 2048 in decimal, so you configure leftprotoport=icmp/2048. Similarly, to allow ipv6-icmp Neighbour Discovery which has type 136 (0x88) and code 0(0x00) this becomes 0x8800 or in decimal 34816 resulting in leftprotoport=ipv6-icmp/34816 .

Some clients, notably older Windows XP and some Mac OSX clients, use a random high port as source port. In those cases rightprotoport=17/%any can be used to allow all UDP traffic on the connection. Note that this option is part of the proposal, so it cannot be arbitrarily left out if one end does not care about the traffic selection over this connection - both peers have to agree. The Port Selectors show up in the output of ipsec eroute and ipsec auto --status eg:"l2tp": 193.110.157.131[@aivd.libreswan.org]:7/1701...%any:17/1701 This option only filters outbound traffic. Inbound traffic selection must still be based on firewall rules activated by an updown script. The variables $PLUTO_MY_PROTOCOL, $PLUTO_PEER_PROTOCOL, $PLUTO_MY_PORT, and $PLUTO_PEER_PORT are available for use in updown scripts. Older workarounds for bugs involved a setting of 17/0 to denote any single UDP port (not UDP port 0). Some clients, most notably OSX, uses a random high port, instead of port 1701 for L2TP.

leftupdown="ipsec _updown --route yes"

See ipsec_pluto(8) for details. Relevant only locally, other end need not agree on it.

The option ondemand used to be called route

Digital signatures are superior in every way to shared secrets. Especially IKEv1 in Aggressive Mode is vulnerable to offline dictionary attacks and is performed routinely by at least the NSA on monitored internet traffic globally. The never option is only used for connections that do not actually start an IKE negotiation, such as type=passthrough connections. The auth method null is used for "anonymous opportunistic IPsec" and should not be used for regular pre-configured IPsec VPNs.

                cipher:                 3des or aes128 or aes256


                hash:                   sha1 or md5


                pfsgroup (DHgroup):     modp1024 or modp1536 or modp2048

Note that AES-GCM is an AEAD algorithm, meaning that it performs encryption+authentication in one step. This means that AES-GCM must not specify an authentication algorithm. However, it does require a PRF function, so the second argument to an AEAD algorithm denotes the PRF. So ike=aes_gcm-sha2 means propose AES_GCM with no authentication and using SHA2 as the prf. Note that for phase2alg, there is no prf, so AES-GCM is specified for ESP as phase2alg=aes_gcm-null. The AES-GCM and AES-CCM algorithms support 8,12 and 16 byte ICV´s. These can be specified using a postfix, for example aes_gcm_a (for 8), aes_gcm_b (for 12) and aes_gcm_c (for 16). The default (aes_gcm without postfix) refers to the 16 byte ICV version. It is strongly recommended to NOT use the 8 or 12 byte versions of GCM or CCM.

Weak algorithms are regularly removed from libreswan. Currently, 1DES and modp768 have been removed and modp1024 will be removed in the near future. Additionally, md5 and sha1 will be removed within the next few years. Null encryption is available, and should only be used for testing or benchmarking purposes. Please do not request for insecure algorithms to be re-added to libreswan.

Diffie-Hellman groups 22, 23 and 24 are also implemented as per RFC-5114. Instead of the modp key syntax, use the "dh" keyword, for example ike=3des-sha1;dh23

The modp syntax will be removed in favour of the dh syntax.

The very first IPsec designs called for use of AH plus ESP to offer authentication, integrity and confidentiality. That dual protocol use was a significant burden, so ESP was extended to offer all three services, and AH remained as an auth/integ. Only broken configurations (often used with racoon) require the strange double authentication using ah+esp. Additionally, AH does not play well with NATs, so it is strongly recommended to use ESP with the null cipher if you require unencrypted authenticated transport.

The default values are the same as for ike= Note also that not all ciphers available to the kernel (eg through CryptoAPI) are necessarily supported here.

The format for ESP is ENC-AUTH followed by an optional PFSgroup. For instance, "3des-md5" or "aes256-sha1;modp2048" or "aes-sha1,aes-md5".

For RFC-5114 DH groups, use the "dh" keyword, eg "aes256-sha1;dh23"

The format for AH is AUTH followed by an optional PFSgroup. For instance, "md5" or "sha1;modp1536".

AEAD algorithms such as AES-GCM and AES-CCM require null for the authentication algorithm, for example phase2alg=aes_ccm-null or phase2alg=aes_gcm-null. Note that the ike= syntax for aes_gcm does not specify a null authentication but specifies the prf instead. The supported key sizes are 128, 192 and 256, which are specified similarly to plain aes, i.e. phase2alg=aes_gcm256. A subscript of _c, _b or _a can be used to refer to the different ICV variants where a means 8 bytes, b means 12 bytes and c means 16 bytes. The default when not using a subscript is the 16 byte ICV, the recommended value by RFC-4106. Therefor phase2alg=aes_gcm256-null is equivalent to phase2alg=aes_gcm_c256-null. It is recommended to migrate to the _c versions (without specifying _c), as support for smaller ICV´s might be removed in the near future.

The supported algorithms depend on the libreswan version, OS and kernel stack used. Possible ciphers are aes, 3des, aes_ctr, aes_gcm, aes_ccm, camellia, serpent and twofish.

Note that openswan and versions of libreswan up to 3.6 require manually adding the salt size to the key size. Therefor, to configure an older version of openswan or libreswan, use: "phase2alg=aes_ccm_c-280-null" to interop with a new libreswan using "phase2alg=aes_ccm256". For CCM, the ´keysize´ needs to be increased by 24, resulted in valid keysizes of 152, 215 and 280. For GCM the ´keysize´ needs to be increased by 32, resulting valid ´keysizes´ of 160, 224 and 288.

This option enables using the draft 96 bits version to interop with those implementations. Currently the accepted values are no, (the default) signifying default RFC truncation of 128 bits, or yes, signifying the draft 96 bits truncation.

Another workaround is to switch from sha2_256 to sha2_128 or sha2_512.

This option allows fine tuning which of the NAT-T payloads to consider for sending and processing. Currently the accepted values are drafts, rfc or both (the default). To interoperate with known broken devices, use nat-ikev1-method=drafts.

IKEv1 fragmentation capabilities are negotiated via a well-known private vendor id. IKEv2 fragmentation support is implemented using RFC 7383. If pluto does not receive the fragmentation payload, no IKE fragments will be sent, regardless of the fragmentation= setting. When set to yes, IKE fragmentation will be attempted on the first re-transmit of an IKE packet of a size larger then 576 bytes for IPv4 and 1280 bytes for IPv6. If fragmentation is set to force, IKE fragmentation is used on initial transmits of such sized packets as well. When we have received IKE fragments for a connection, pluto behaves as if in force mode.

IKE padding is allowed in IKEv1 but it is known to cause interoperability issues. The ikepad= option can be used to disable IKEv1 padding. This is required for some devices (such as Checkpoint in Aggressive Mode) that reject padded IKEv1 packets. In IKEv2, no padding is allowed, and this option has no effect. If you find a device that seems to require IKE padding in IKEv2, please contact the libreswan developers. This option should almost never be enabled.

If the ikev2= setting is set to permit or propose, Libreswan will try and detect a "bid down" attack from IKEv2 to IKEv1. Since there is no standard for transmitting the IKEv2 capability with IKEv1, Libreswan uses a special Vendor ID "CAN-IKEv2". If a fall back from IKEv2 to IKEv1 was detected, and the IKEv1 negotiation contains Vendor ID "CAN-IKEv2", Libreswan will immediately attempt and IKEv2 rekey and refuse to use the IKEv1 connection. With an ikev2= setting of insist, no IKEv1 negotiation is allowed, and no bid down attack is possible.

There are security implications in allowing narrowing down the proposal. For one, what should be done with packets that we hoped to tunnel, but cannot. Should these be dropped or send in the clear? Second, this could cause thousands of narrowed down Child SAs to be created if the conn has a broad policy (eg 0/0 to 0/0). One possible good use case scenario is that a remote end (that you fully trust) allows you to define a 0/0 to them, while adjusting what traffic you route via them, and what traffic remains outside the tunnel. However, it is always preferred to setup the exact tunnel policy you want, as this will be much clearer to the user.

When using certificate based ID´s, one need to specify the full RDN, optionally using wildcard matching (eg CN=´*´). If the RDN contains a comma, this can be masked using a comma (eg OU=´Foo,, Bar and associates´)

      username:password:conname:ipaddress

For supported password hashing methods, see crypt(3). If pluto is running in FIPS mode, some hash methods, such as MD5, might not be available. Threads are used to launch an xauth authentication helper for file as well as PAM methods.

The alwaysok should only be used if the XAUTH user authentication is not really used, but is required for interoperability, as it defeats the whole point of XAUTH which is to rely on a secret only known by a human. See also pam-authorize=yes

When we are an XAUTH client, these options will be treated as defaults. If the remote XAUTH server did not pass us one of these options, the configured defaults are used to reconfigure the local DNS setup.

The split tunneling directive will be sent automatically if the xauth server side has configured a network other than 0.0.0.0/0

Vendor ID´s can be useful in tracking interoperability problems. However, specific vendor identification and software versions can be useful to an attacker when there are known vulnerabilities to a specific vendor/version.

The prefix OE stands for "Opportunistic Encryption". This prefix was historically used by The FreeS/WAN Project and The Openswan Project (openswan up to version 2.6.38) and in one Xeleranized openswan versions (2.6.39). Further Xeleranized openswan´s use the prefix OSW.

Note that connection instances created by the Opportunistic Encryption or PKIX (x.509) instantiation system are distinct internally. They will inherit this policy bit.

The default is no.

This feature is only available with kernel drivers that support SAs to overlapping conns. At present only the (klips) mast protocol stack supports this feature.

Automatically generated reqids use a range of 0-3 (eg 16380-16383 for the first reqid). These are used depending on the exact policy (AH, AH+ESP, IPCOMP, etc). Manually assigned reqids are all identical. Instantiations of connections (those using %any wildcards) will all use the same reqid.

For KLIPS, when using the MAST variant, a different mechanism called SAref is in use. See overlapip and sareftrack.

dpdaction=clear is really only useful on the server of a Road Warrior config.

The value restart_by_peer has been obsoleted and its functionality moved into the regular restart action.

Aggressive Mode is less secure, and more vulnerable to Denial Of Service attacks. It is also vulnerable to brute force attacks with software such as ikecrack. It should not be used, and it should especially not be used with XAUTH and group secrets (PSK). If the remote system administrator insists on staying irresponsible, enable this option.

Aggressive Mode is further limited to only proposals with one DH group as there is no room to negotiate the DH group. Therefor it is mandatory for Aggressive Mode connections that both ike= and phase2alg= options are specified with only one fully specified proposal using one DH group.

The KE payload is created in the first exchange packet when using aggressive mode. The KE payload depends on the DH group used. This is why there cannot be multiple DH groups in IKEv1 aggressive mode. In IKEv2, which uses a similar method to IKEv1 Aggressive Mode, there is an INVALID_KE response payload that can inform the initiator of the responder´s desired DH group and so an IKEv2 connection can actually recover from picking the wrong DH group by restarting its negotiation.

The keywords "keylife" and "lifetime" are obsoleted aliases for "salifetime." Change your configs to use "salifetime" instead.

As of libreswan 3.1, both ends must agree. In previous versions of libreswan, openswan and freeswan, compression was always accepted even if not configured. In light of the BEAST attacks on TLS, using compression and encryptions has come under more scrutiny, and it was decided that it should be possible for the local policy of an endpoint to disallow compression. A value of yes causes pluto to propose compression and reject proposals without it. A value of no prevents pluto from proposing compression; a proposal to compress will be rejected.

KLIPS and NETKEY use a priority system based on "most specific match first". It uses an internal algorithm to calculate these based on network prefix length, protocol and port selectors. A lower value means a higher priority.

Typical values are about the 2000 range. These can be seen on the NETKEY stack using ip xfrm policy when the connection is up. For "anonymous IPsec" or Opportunistic Encryption based connections, a much lower priority (65535) is used to ensure administrator configured IPsec always takes precedence over opportunistic IPsec.