HOWTO: openswan to libreswan migration

Libreswan was forked from openswan 2.6.38 in 2012]. It has many features that are unavailable in openswan, but libreswan supports all openswan features with the exception of the broken openswan loopback= support. For a complete list of changes since openswan-2.6.38, see the CHANGES file or checkout the libreswan.git repository.

libreswan tries to be as backwards compatible as possible with openswan. Obsoleted or renamed configuration options will still work using the old openswan name, and a warning will be logged. Therefor, most migrations can be safely performed using the Linux distribution vendor update. If you roll your own packages or distribution, take note of the incompatibilities listed below.

Some Linux distributions will automatically upgrade openswan to libreswan when a system update is issued. Libreswan is currently available in Fedora, RHEL7/CentOS7, RHEL6.7 Extra's Channel, EPEL6, Arch Linux, uclibc/buildroot and others. Work is being done to add libreswan to Debian and Ubuntu.

Upgrading from RHEL6 to RHEL7 will cause an automatic upgrade from openswan to libreswan. RHEL-6.8 will move libreswan from Extra's to Core, and will then also cause an automatic update from openswan to libreswan between RHEL-6.7 to RHEL-6.8.

The packaging of libreswan on those Linux distributions handle some of the update requirements. There are a few incompatibilities that might require manual intervention. These are listed on this page. If you encounter anything not listed here, please contact us on the libreswan development list or on the #libreswan irc channel on Libera.Chat network.

Configuration changes between libreswan and openswan

Where possible, libreswan recognises old keyword and syntax from openswan. There are a few exceptions where behaviour changed. See the libreswan documentation for the many new features that have been added since forked from openswan.

The key size of the AES_GCM and AES_CCM algorithms no longer include salt/ICV values

With libreswan it is no longer requires (or allowed!) to specify the salt or ICV bytes for phase2 (using esp= or phase2alg=). The AES_GCM and AES_CCM algorithms come in different truncation flavours denoted with "_a", "_b" or "_c", for example "aes_gcm_c". While libreswan still supports this syntax, the non-flavoured version without underscore always refers to the strongest (_c) versions, and use of the other versions is discouraged and should only be done if required for interoperability with a remote peer. Note that similar rules apply to using AES_GCM or AES_CCM with IKE (using ike=) which openswan does not support at all. One difference is that the second component, which is always null for ESP, refers to the PRF function in IKE. Specifying null as PRF is invalid. SHA2 is often used in this combination (eg ike=aes_gcm-sha2). See the ipsec.conf man page for more details.

The following example list the libreswan specification versus the old openswan specification for ESP using AES_GCM with 16 byte ICV and 8 byte salt:

    # Libreswan AES_GCM
    esp=aes_gcm256-null
    # Old openswan notiation: esp=aes_gcm_c-280-null

Libreswan added support for AES_GCM in IKEv2, which is specified as ike=aes_gcm256-sha2 (where sha2 refers to the prf, not the integ/auth algorithm). Openswan does not support AES_GCM in IKE.

The use of the strict flag ("!") is no longer allowed

The old freeswan X.509 patch required the strict flag ("!") to make the ike= or esp= list exclusive. This behaviour was changed in openswan many years ago to default to strict mode. The strict flag was ignored. Libreswan no longer allows specifying the strict flag. Simple remove the "!" character from the connection definition.

Obsoleted /etc/ipsec.d/cacerts and /etc/ipsec.d/crls

Libreswan requires the use of NSS for storing cryptographic material such as private keys, certificates and CA certificates. Openswan could be optionally compiled with HAVE_NSS which enabled this feature as well. The Linux distributions of RHEL, Fedora and CentOS enabled NSS while Debian and Ubuntu did not. For details on how to migrate from non-NSS openswan to NSS libreswan see Using_NSS_with_libreswan.

Even when NSS was used, openswan would still read CA certificates from /etc/ipsec.d/cacerts/ and CRLs from /etc/ipsec.d/crls. Libreswan no longer uses these directories. Use certutil to import the CAcerts from /etc/ipsec.d/cacerts/ into the NSS database. Use crlutil to import CRL pem files into the NSS database. Both operations can be done at runtime and do not require a restart. Note that pluto supports fetching the CRLs from the DistributionPoints specified in the certificate and will use that per default. This URL can be overridden in the configuration. See the manual page for ipsec.conf for more details.

When libreswan detects an old dbm based NSS database that was created by openswan or libreswan < 3.15, it will upgrade the NSS database to the sql format. It will also then import the CA certificates and CRLs from the old directories if these contain any files. This will only happen once. If the cacerts or crl directory is updated by an external program or administrator, these new files will be ignored.

protostack=auto is obsoleted

Libreswan will interpret protostack=auto to be protostack=netkey. Most distributions already specified protostack=netkey.

Changed defaults for crypto algorithms

The default cryptographic proposal set when using IKEv2 (ikev2=yes|insist) has been updated - The new default proposal set added SHA2 and AES_GCM and removed MD5 and MODP1024. You might need to update your connections if a remote endpoint insists on using MD5 or MODP1024 with IKEv2. This is unlikely to be the case as most implementations will also allow at least SHA1 and MODP1536. Note that the default proposal set for IKE and ESP attempt to follow the latest recommendations - currently specified in RFC-8247 and RFC-8221.

Blowish algorithm support has been removed

Blowfish support was removed from ESP (irrespective whether the kernel supports it). Use twofish instead. When using twofish (or serpent) to a strongswan endpoint, enable fake-strongswan=yes (added to libreswan in version 3.16)

Changes to config setup options

A lot of new features have been added to libreswan since it forked from openswan. A few openswan keywords have been obsoleted or rename. When using these old options, libreswan will log a warning that your obsoleted option is ignored. If the option was renamed it will still activate the option but log a warning. For example, all options that used an underscore ("_") have been renamed to use a dash ("-") instead.

Options removed because the functionality was no longer needed: prepluto=', postpluto=, plutoopts=, plutofork=, plutowait=, nocrsend= and oe=

NAT Traversal is always enabled because it is a core part of IKEv2 and the nat_traversal= option is ignored even when set to "no". The disable_port_floating= option is also obsoleted and ignored.

Some renamed options: plutostderrlog= and plutostderrlogtime= have been renamed to logfile= and logtime=.

The option plutorestartoncrash= is only used when using the older sysvinit initsystem - other init systems handle restarting a service natively (eg systemd, upstart).

The option force_keepalive= has been obsoleted for the slightly different nat-keepalive= option. See also the per-connection keep-alive= option.

Changes to connection parameter options

A lot of new functionality has been added to libreswan. Please see the man page for ipsec.conf for more details. This section only lists the obsoleted or renamed per-connection options. Using the old names still works and a warning is logged.

The modecfgwin1=, modecfgwins2= and loopback= options are obsoleted and ignored.

The dpdaction restart and restart_by_peer was folded into one option called restart that behaves like the old restart_by_peer.

The NAT-T keepalive packet sending behaviour was changed. See the ipsec.conf man page for both the global nat-keepalive= and the per-connection keep-alive= options. See also nat-ikev1-method=.

Some X.509 options were renamed: strictcrlpolicy= to crl-strict=, ocsp_trust_name= to ocsp-trustname=

IPsec loopback support removed

The IPsec support on loopback using loopback= for use with Labeled IPsec has been completely removed. The functionality was broken and can be implemented using other kernel subsystems when needed.

IKE behaviour changes

Apart from new features, some existing behaviour changed that might affect interoperability with third party devices or certain specific configurations

init system support

The sysv init system did not have native support for restarting daemons after a crash, so the sysvinit init scripts use a wrapper called _plutorun. For newer init systems, this wrapper is not used in favour of the native support. For example, for systemd the restart options are defined in the ipsec.service unit file. This also obsoletes the plutorestartoncrash= option.

For those upgrading from sysvinit to a new init system like systemd, the config files in /etc/sysconfig/ipsec, /etc/sysconfig/pluto or /etc/defaults/pluto are no longer used.

X.509 validation with NSS

All the old X.509 code was replaced with calls to the NSS library. NSS handles certain X.509 certificates differently than the old code did. As such, it might happen that certain X.509 certificates with missing or bogus Extended Key Usage (EKU) attributes no longer validate because NSS rejected the certificate. Note that libreswan only imports files from /etc/ipsec.d/cacerts and /etc/ipsec.d/crls once during an upgrade. If an external program updates these directories, it will need to be updated to import new CAcerts and CRLs into the NSS database directly. See HOWTO: Using NSS with libreswan for the exact usage of the certutil and crlutil commands.

CRLs are no longer allowed to be signed using MD5.

NSS does not allow a CA to sign multiple certificates with the same serial number. If NSS encounters the second certificate with the same serial number that has already been seen for another certificate, it will REJECT the certificate. This can lead to strange intermittent errors depending on which certificate connected first.

IKE padding behaviour

The IKE padding behaviour was updated in libreswan. This could (rarely) cause interoperability issues with other vendors. If you suspect such a problem after migration, try specifying ikepad=no.

Obsoleted environment variables

The pluto IKE daemon and some of the ipsec commands supported some environment variables to tweak their behaviour. These were mostly used for automatic testing. These environment variables have been obsoleted by config setup or per-connection options (and for testing, migrated to whack --impair-* options). For example, PLUTO_EVENT_RETRANSMIT_DELAY= and PLUTO_MAXIMUM_RETRANSMISSIONS= have been obsoleted for the options retransmit-interval= and retransmit-timeout=.

Updated commands

The ipsec command has been extended

The ipsec command has gained some functionality. These changed are important because they are used in the init systems. For example ipsec checknss and ipsec nflog are used (via the init system invocations) to update the NSS database format or enable NFLOG iptables rules. If you are using a custom initscript it is recommended to look at the libreswan versions (either the sysvinit script or the systemd ipserv.service unit file)

ipsec status command changed output

The ipsec status command lists a lot of internal data of the pluto IKE daemon. Since so many options have changed, the output of this command is also vastly different from the openswan version. Custom scripts that rely on the output of openswan's ipsec status command will need to be updated for the libreswan version of the command. Better alternatives for these use cases might be to use some of the newer libreswan commands such as "ipsec whack --trafficstatus", "ipsec whack --globalstatus" or "ipsec whack --shuntstatus".

Specfiying the NSS database in custom scripts

As of libreswan-3.15, the NSS database is in the newer SQL format, performing any commands using certutil or pk12util or crlutil requires the use of an updated -d option: -d sql:/etc/ipsec.d

ipsec newhostkey creates bigger RSA keys

The ipsec newhostkey command which invokes the ipsec rsasigkey command now generates bigger keys - a minimum of 3072 bits. These commands used to allow specifying the random device to use, although this was ignored when compiled with NSS when it would use the NSS library to obtain strong random. Therefor the --random option has been removed in libreswan. Note a new --seeddev= option has been added that allows specifying the seed device used to initialise the NSS internal state.

Miscellaneous issues

leftover scripts

Note that libreswan prefers systemd and upstrart over sysvinit. If you have a custom sysvinit script installed that is not part of a package, and you upgrade it to libreswan, some old openswan scripts might still try to start openswan - specifically keep an eye out for an obsoletes leftover /etc/init.d/ipsec

Changes in building libreswan versus openswan

Some build options have changed. The following list will explain the changes you need to know to update your custom compile environment, such as your Makefile.inc or Makefile.inc.local file, or via specified environment variables in the pacakge build.

NSS mandatory, USE_LIBNSS removed

Libreswan has removed all old crypto code. It uses the NSS library for all userland cryptographic operations. This was optional with openswan using the USE_LIBNSS compile time option. This option was already set for all RHEL and Fedora builds. The build option USE_LIBNSS has been removed. See Migration_NSS on how to migrate a non-nss openswan system to libreswan.

USE_LWRES removed, USE_DNSSEC added

Support for the bind9 lwres DNS interface has been removed. The old ADNS interface is only used for (obsoleted) IKEv1 opportunstic encryption DNS lookups and will also be removed in the near future when replaced with an libevent based async DNS query mechanism based on getdns or libunbound.

USE_DYNAMICDNS always enabled, option removed

When connections rekey, dynamic dns support performs a fresh dns lookup to support IPsec gateways on dynamic IP using DNS names, such as dyndns.org. Libreswan always performs these DNS lookups, so this option was removed.

USE_IPSECPOLICY obsoleted and removed

The policy socket was an method for non-root users to query the pluto daemon for information. This support has been removed. Similar features will be re-implemented using a dbus API.

USE_TAPROOM obsoleted and removed

The taproom code allowed custom mangling of data for fuzzing and regression testing. It was left unused and no longer worked. It was removed. Fuzzing is now done via IKE fuzzer

USE_IKEPING always built, option removed

The 'ipsec ikeping' command is now always built and installed.

SEND_VENDORID changed to runtime option

Instead of using a global compile time option, libreswan allows one to set sending the vendor id payload on a per connection basis using the new 'send_vendorid=yes' option. The libreswan vendorid changed to 'OEN-<version>' but can be manually set using the global myvendorid= option.

HAVE_STATSD changed to runtime option

The HAVE_STATSD option is now a runtime option statsbin= which can be set in the 'config setup' section of ipsec.conf. Its value should point to a valid executable filename. When the option is not specified, no statsd calls are done.

USE_AGGRESSIVE, USE_XAUTH, USE_NAT_TRAVERSAL, USE_NAT_TRAVERSAL_TRANSPORT_MODE

IKEv1 extensions that were integrated into the IKEv2 specification are always built in libreswan. That means these options have been removed and cannot be disabled at compile time. USE_XAUTHPAM is enabled for all platforms that support pam.

HAVE_THREADS always built, option removed

Thread support is always enabled, as even uclibc has support for it. However, the use of threads has been strongly reduced. Only some of the X509 CRL code and the XAUTH pam code use threads.

FIPSPRODUCTCHECK

FIPS mode detection has been updated to be compliant to new FIPS requirements. The FIPSPRODUCTCHECK= option points to a file that when present, it means that libreswan is running on a "FIPS Product". This is separate from the check if the kernel was booted in FIPS mode.

USE_MODP_RFC5114 always built, option removed

Support for these DiffieHellman groups is always built.

USE_NOCRYPTO

This option was removed put will be re-introduced because sadly people still need it.

USE_EXTRACRYPTO changed

The SHA2 algorithm has moved into the core list of algorithms that are always enabled and the USE_EXTRACRYPTO option now only refers to serpent and twofish. Blowfish support has been removed.

OSTYPE and OSMEDIA

These options are used with the Testing_Harness to specify the OS type (fedora or ubuntu) and the OS network install media. See the kvmsetup.sh file in the main libreswan directory.