WeOS
5.29.0

# IPsec with Certificates

## About

This is a configuration example of an IPsec tunnel that uses X.509 certificates for authentication instead of pre-shared keys. In this setup, two devices are securely connected over the Internet using an IPsec tunnel. Each device is provisioned with its own end-entity certificate signed by a trusted CA certificate. The configuration demonstrates how to establish a reliable and encrypted communication channel using certificate-based authentication.

## Introduction

In this example, the devices use IKEv2 with certificate-based authentication. Each peer presents its own certificate and validates the peer certificate using a trusted CA certificate. Identities configured on the tunnel are matched against the subject (or subjectAltName) of the presented certificates.

The topology is the same as in the PSK-based example:

                                .--.-.
                               ( (    )__
                              (_,  \ ) ,_)  Internet/Public Network
                                '-'--`--'
                                 |    |
              .------------------'    '--------------------.
              |                                            |
              |Public IP:                                  |Public IP:
              |192.168.0.1                                 |192.168.0.2
          .---+----.                                   .---+----.
          |  Alice |           IPsec Tunnel            |  Bob   |
          |        |===================================|        |
          |        |Responder                 Initiator|        |
          '--------'                                   '--------'

Figure 1: IPsec tunnel using certificate-based authentication.

           Alice PKI                                  Bob PKI
        +----------------------+               +----------------------+
        | Root CA (root-a.pem) |               | Root CA (root-b.pem) |
        +------+---------------+               +------------+---------+
               |                                            |
               v                                            v
        +-------------------------+          +-------------------------+
        | Issuing CA (int-a.pem)  |          | Issuing CA (int-b.pem)  |
        +------+------------------+          +--------------+----------+
               |                                            |
               v                                            v
        +--------------------+                   +--------------------+
        | alice-cert.pem (EE)|                   | bob-cert.pem (EE)  |
        | CN=alice           |                   | CN=bob             |
        +--------------------+                   +--------------------+

Figure 2: Alice and Bob are using two separate PKI hierarchies. They need to import the root CA certificate of their respective peer before establishing connection.

In Figure 1, Alice is the responder and Bob is the initiator. They both configured their identities to allow for IKE authentication. Instead of a shared secret, each peer is configured with a local certificate and a trusted CA certificate used to validate peer’s certificate.

Before configuring the tunnels, make sure that:

- Each peer has a local certificate (with private key) installed (imported or enrolled) in the device certificate store.
- Both peers trust the CA that issued the peer certificates; the CA certificate is installed in the Local CA Store.

In our example, Alice must have at least the following certificates installed. The “A-chain” (root-a, int-a, alice) will be sent to Bob. Root of “B-chain” will validate Bob’s chain.

    alice:/pki/#> show cert full

    Certificates
    TYPE     HASH     EXPIRES     NAME                 DIST LABEL
    CA-local 9db57dbe Sep 21 2035 Root-A CA                 root-a
    CA-local 8a09dd4b Sep 21 2028 Issuing-A CA              int-a
    CA-local 36a0943a Sep 22 2035 Root-B CA                 root-b
    Pub      db1c90fc Dec 10 2026 alice                     alice
    Key      N/A      N/A         alice                N/A  alice

## Responder Setup (Alice)

In this example, Alice is configured as the responder. She uses a certificate with label `alice-cert` signed by a issuing CA, `issuing-a` signed by a Root-CA certificate with label `root-a`. We assume that all certificates from Alice’s PKI chain and Bob’s Root-CA `root-b`, have already been imported or enrolled to the system.

    alice:/#> config
    alice:/config/#> tunnel
    alice:/config/tunnel/#> ipsec 1
    alice:/config/tunnel/ipsec-1/#> description "Site-to-site"

    alice:/config/tunnel/ipsec-1/#> local-address 192.168.0.1
    alice:/config/tunnel/ipsec-1/#> peer 192.168.0.2
    alice:/config/tunnel/ipsec-1/#> local-id CN=alice
    alice:/config/tunnel/ipsec-1/#> remote-id CN=bob

    alice:/config/tunnel/ipsec-1/#> method cert
    alice:/config/tunnel/ipsec-1/#> certificate alice-cert
    alice:/config/tunnel/ipsec-1/#> ca root-b

    alice:/config/tunnel/ipsec-1/#> leave

The `method cert` command selects certificate-based authentication. The `certificate` command selects which local certificate (and private key) to use for this tunnel. The `ca` command selects the CA certificate that is used to validate the certificate chain presented by the peer. NOTE: the CA certificate must be a standalone file (not a bundle). The `local-id` and `remote-id` values configured on the tunnel must match exactly the identities in the certificates (for example, the certificate subject).

In this example, the revocation policy is kept default, `relaxed`, meaning that the tunnel will not be established if Bob’s certificate is explicitly revoked in a CRL. In other cases, like CRLDP not available the revocation checking will not be

## Initiator Setup (Bob)

Bob is configured as the initiator. He uses a certificate with label `bob-cert` signed `issuer-b` signed by `root-b`. Again, all certificates must be present in the system.

    bob:/#> config
    bob:/config/#> tunnel
    bob:/config/tunnel/#> ipsec 1
    bob:/config/tunnel/ipsec-1/#> description "Site-to-site (cert)"
    bob:/config/tunnel/ipsec-1/#> initiator

    bob:/config/tunnel/ipsec-1/#> local-address 192.168.0.2
    bob:/config/tunnel/ipsec-1/#> peer 192.168.0.1
    bob:/config/tunnel/ipsec-1/#> local-id CN=bob
    bob:/config/tunnel/ipsec-1/#> remote-id CN=alice

    bob:/config/tunnel/ipsec-1/#> method cert
    bob:/config/tunnel/ipsec-1/#> certificate bob-cert
    bob:/config/tunnel/ipsec-1/#> ca root-a

    bob:/config/tunnel/ipsec-1/#> leave

Again, `method cert` enables certificate-based authentication on the tunnel, `certificate` selects the local certificate to present to the peer, and `ca` selects the CA certificate used to validate the remote certificate. The revocation policy is `relaxed`.

## Revocation

In context of IPsec the CRL revocation checking is always enabled and does not require any additional configuration. It relies on CRL Distribution Points defined in the incoming certificate chain. Revocation cannot be disabled instead one of the two policies can be selected: strict ro relaxed (default).

Revocation status checking is done during initial authentication phase and at every next re-authentication attempt. The `reauth-time` parameter controls how often the IKE_SA is re-authenticated and the peer certificate and revocation status are revalidated. Please align re-authentication time to CRL refresh time. An example alignment is `0.5 x (CRL-refresh-time)`.

Given that CRL updates every week, the following example shows how to configure IKE re-authentication to 3 days on Alice. Bob should use compatible values.

    alice:/config/tunnel/ipsec-1/#> reauth-time 3d

### Strict Revocation

If you need a stricter, security-first policy, enable `revocation strict` on both peers. With strict mode:

- Authentication fails if a current CRL cannot be fetched, its signature is invalid, or the CRL is expired.
- The tunnel will not be established without valid, up-to-date revocation data.

Before enabling strict mode, ensure:

- Reliable network access to CRL distribution points.
- Accurate system time via NTP.
- Appropriate CRL cache lifetimes aligned with the CRL refresh schedule.
- Regular re-authentication (reauth-time) set to a value compatible with CRL updates.

## Verification

After applying the configuration, Alice can check if Bob succeeded with connection:

    alice:/#> show tunnel ipsec
    ID  DESCRIPTION      STATUS               TIME (since last rekey)
    1   ipsec1           Up(Installed)        0 Days 1 Hours 8 Mins 39 Secs

    alice:/#> show tunnel ipsec 1
    Current state for tunnel ipsec1 is UP(Installed).

    Security-Association(SA) details:
    ipsec1: #6, ESTABLISHED, IKEv2, 20759114c78bf131_i* 4fb9e973f3067b48_r
      local  'alice' @ 192.168.0.1[500]
      remote 'bob' @ 192.168.0.2[500]
      AES_CBC-128/HMAC_SHA2_256_128/PRF_HMAC_SHA2_256/ECP_256
      established 5s ago, rekeying in 14304s
      tunnel1: #5, reqid 1, INSTALLED, TUNNEL, ESP:AES_CBC-128/HMAC_SHA2_256_128
        installed 5s ago, rekeying in 3267s, expires in 3955s
        in  c2032981,      0 bytes,     0 packets
        out cc173955,      0 bytes,     0 packets
        local  192.168.0.1/32
        remote 192.168.0.2/32

    Loaded configuration for the connection:
    ipsec1: IKEv2, reauthentication every 14400s, rekeying every 14400s, dpd delay 30s
      local:  192.168.0.1
      remote: 192.168.0.2
      local certificate authentication:
        id: alice, certificate: alice-cert, ca: ipsec-ca
      remote certificate authentication:
        id: bob, ca: ipsec-ca
      tunnel1: TUNNEL, rekeying every 3600s, dpd action is start
        local:  dynamic
        remote: dynamic

If the tunnel does not come up, check the following:

- The local and remote subnets match between the peers.
- The `local-id` and `remote-id` values correspond to the identities in the certificates.
- The correct local certificate and CA certificate labels are configured.
- The revocation policy is suitable for your environment and valid revocation information is available when using `revocation strict`.
- Check that when using a multi-tier certificate hierarchy all certificates from the chain, including intermediates are present in the system.

« Previous Next »