HOWTO: openswan to libreswan migration

Migration from openswan to libreswan

libreswan is a fork of openswan 2.6.38. It has features that are unavailable with openswan, but libreswan itself supports all openswan features.

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_ccm_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.

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-4307. This document is being updated by https://datatracker.ietf.org/doc/draft-ietf-ipsecme-rfc4307bis/ draft-ietf-ipsecme-rfc4307bis]

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. When using these obsoleted options, libreswan will log a warning that your obsoleted option is ignored. Examples include plutoopts=, plutofork=, nat_traversal= and oe=.

Options that used an underscore ("_") have been renamed to use a dash ("-") and a warning is logged as well. Note that the NAT Traversal is always enabled because it is a core part of IKEv2 and the nat_traversal= option is ignored)

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.