# OVN IPsec Tutorial

This document provides a step-by-step guide for encrypting tunnel traffic with IPsec in Open Virtual Network (OVN). OVN tunnel traffic is transported by physical routers and switches. These physical devices could be untrusted (devices in public network) or might be compromised. Enabling IPsec encryption for the tunnel traffic can prevent the traffic data from being monitored and manipulated. More details about the OVN IPsec design can be found in `ovn-architecture`(7) manpage.

This document assumes OVN is installed in your system and runs normally. Also, you need to install OVS IPsec packages in each chassis (refer to Open vSwitch documentation on ipsec).

## Generating Certificates and Keys

OVN chassis uses CA-signed certificate to authenticate peer chassis for building IPsec tunnel. If you have enabled Role-Based Access Control (RBAC) in OVN, you can use the RBAC SSL/TLS certificates and keys to set up OVN IPsec. Or you can generate separate certificates and keys with `ovs-pki` (refer to Generating Certificates and Keys).

Note

OVN IPsec requires x.509 version 3 certificate with the subjectAltName DNS field setting the same string as the common name (CN) field. CN should be set as the chassis name. `ovs-pki` in Open vSwitch 2.10.90 and later generates such certificates. Please generate compatible certificates if you use another PKI tool, or an older version of `ovs-pki`, to manage certificates.

## Configuring OVN IPsec

You need to install the CA certificate, chassis certificate and private key in each chassis. Use the following command:

    $ ovs-vsctl set Open_vSwitch . \
            other_config:certificate=/path/to/chassis-cert.pem \
            other_config:private_key=/path/to/chassis-privkey.pem \
            other_config:ca_cert=/path/to/cacert.pem

## Enabling OVN IPsec

To enable OVN IPsec, set `ipsec` column in `NB_Global` table of the northbound database to true:

    $ ovn-nbctl set nb_global . ipsec=true

With OVN IPsec enabled, all tunnel traffic in OVN will be encrypted with IPsec. To disable it, set `ipsec` column in `NB_Global` table of the northbound database to false:

    $ ovn-nbctl set nb_global . ipsec=false

Note

On Fedora, RHEL and CentOS, you may need to install firewall rules to allow ESP and IKE traffic:

    # systemctl start firewalld
    # firewall-cmd --add-service ipsec

Or to make permanent:

    # systemctl enable firewalld
    # firewall-cmd --permanent --add-service ipsec

## Enforcing IPsec NAT-T UDP encapsulation

In specific situations, it may be required to enforce NAT-T (RFC3948) UDP encapsulation unconditionally and to bypass the normal NAT detection mechanism. For example, this may be required in environments where firewalls drop ESP traffic, but where NAT-T detection (RFC3947) fails because packets otherwise are not subject to NAT. In such scenarios, UDP encapsulation can be enforced with the following.

For libreswan backends:

    $ ovn-nbctl set nb_global . options:ipsec_encapsulation=true

For strongswan backends:

    $ ovn-nbctl set nb_global . options:ipsec_forceencaps=true

Note

Support for this feature is only availably when OVN is used together with OVS releases that accept IPsec custom tunnel options.

## Troubleshooting

The `ovs-monitor-ipsec` daemon in each chassis manages and monitors the IPsec tunnel state. Use the following `ovs-appctl` command to view `ovs-monitor-ipsec` internal representation of tunnel configuration:

    $ ovs-appctl -t ovs-monitor-ipsec tunnels/show

If there is a misconfiguration, then `ovs-appctl` should indicate why. For example:

    Interface name: ovn-host_2-0 v1 (CONFIGURED) <--- Should be set
                                              to CONFIGURED. Otherwise,
                                              error message will be
                                              provided
    Tunnel Type:    geneve
    Remote IP:      2.2.2.2
    SKB mark:       None
    Local cert:     /path/to/chassis-cert.pem
    Local name:     host_1
    Local key:      /path/to/chassis-privkey.pem
    Remote cert:    None
    Remote name:    host_2
    CA cert:        /path/to/cacert.pem
    PSK:            None
    Custom Options: {'encapsulation': 'yes'} <---- Whether NAT-T is enforced
    Ofport:         2          <--- Whether ovs-vswitchd has assigned Ofport
                                    number to this Tunnel Port
    CFM state:      Disabled     <--- Whether CFM declared this tunnel healthy
    Kernel policies installed:
    ...                          <--- IPsec policies for this OVS tunnel in
                                      Linux Kernel installed by strongSwan
    Kernel security associations installed:
    ...                          <--- IPsec security associations for this OVS
                                      tunnel in Linux Kernel installed by
                                      strongswan
    IPsec connections that are active:
    ...                          <--- IPsec "connections" for this OVS
                                      tunnel

If you don’t see any active connections, try to run the following command to refresh the `ovs-monitor-ipsec` daemon:

    $ ovs-appctl -t ovs-monitor-ipsec refresh

You can also check the logs of the `ovs-monitor-ipsec` daemon and the IKE daemon to locate issues. `ovs-monitor-ipsec` outputs log messages to `/var/log/openvswitch/ovs-monitor-ipsec.log`.

The ipsec_encapsulation and ipsec_forceencaps options are boolean and only accept true or yes. Additional “ipsec_*” options such as the one below can be set to pass configuration directly to the underlying IPsec backend.

> $ ovn-nbctl set nb_global . options:ipsec_replay-window=128

## Bug Reporting

If you think you may have found a bug with security implications, like

1. IPsec protected tunnel accepted packets that came unencrypted; OR

2. IPsec protected tunnel allowed packets to leave unencrypted;

Then report such bugs according to OVN’s Security Process.

If bug does not have security implications, then report it according to instructions in Reporting Bugs in OVN.

If you have suggestions to improve this tutorial, please send a email to ovs-discuss@openvswitch.org.