CDRouter IKE User Guide
Introduction and Terminology
CDRouter IKE is an add-on module for CDRouter and CDRouter Multiport that adds IKEv1 IPsec based VPN testing support to CDRouter. CDRouter IKE is used to test CPE routers that contain VPN security gateway functionality based on IKE.
When CDRouter IKE is enabled, CDRouter is able to establish IKE based VPN connections with the router under test by emulating IPsec gateways and clients. Several automated functional test cases verify the behavior of IKE and verify that VPN connections are secure and robust. The CDRouter IKE functionality can also be combined with CDRouter’s existing application tests to allow application traffic to run over VPN connections.
CDRouter IKE offers a blend of testing styles including conformance, functional, and negative. Many of the test cases focus on the underlying problems encountered during interoperability testing.
Since CDRouter IKE is highly configurable, the number of VPN configurations that can be tested is unlimited. Test Engineers are encouraged to run their devices through as many different configurations as possible.
Before testing an IKE based gateway using CDRouter IKE, it is helpful to review some terminology specific to IKE and VPNs. A good understanding of this terminology will assist the tester in reading log messages and diagnosing testing issues involving IKE. It is assumed the tester has some basic knowledge of IKE and VPN technologies.
The CDRouter IKE test suite targets the testing of the IKE protocol (RFC 2409 Internet Key Exchange) and also the ESP protocol (RFC 2406 IP Encapsulating Security Payload). IKE is the keying protocol used to establish dynamic keys for IPsec connections. The keys produced by IKE are used to encrypt and authenticate data traffic sent using ESP packets.
IKE is based on a general key management protocol called ISAKMP (RFC 2408). Some of the terminology used to test IKE comes from ISAKMP and some of the terminology comes from IKE. For simplicity, the test documentation generally refers to the protocol as IKE.
Key Exchange Modes
Phase 1 – When two IKE peers first attempt to communicate with each other, they must establish an IKE SA (Security Association). IKE supports two types of Phase 1 modes – “Main Mode” and “Aggressive Mode”. In test cases where the type of Phase 1 mode does not matter, the test case will refer to the general term “Phase 1”. A successful Phase 1 exchange will produce an IKE SA that is used to encrypt and authenticate all IKE traffic associated with a specific IKE SA.
Phase 2 – The actual IPsec SAs (Security Associations) for ESP traffic are negotiated during the Phase 2 exchange. IKE only supports one type of Phase 2 exchange called “Quick Mode”. Test cases may refer to either Phase 2 or “Quick Mode”. A successful Phase 2 exchange will produce an IPsec SA that is used to encrypt and authenticate all data traffic.
A VPN Tunnel is the high level configuration provided by the user that describes the local and remote traffic that will be carried by IPsec ESP packets. It also describes the type of encryption, authentication, and Diffie-Hellman modes for the Phase 1 and Phase 2 exchanges needed to produce the IKE SAs and IPsec SAs.
CDRouter IKE attempts to bring up any site-to-site tunnels defined in the CDRouter configuration file during the initial start-up phase. CDRouter IKE first sends traffic on the LAN side that matches the tunnel. If the traffic matching the tunnel does not cause the tunnel to be established, CDRouter IKE will initiate the Phase 1 exchange from the WAN.
For site-to-site tunnel testing, each test case assumes that one valid Phase 1 and Phase 2 SA exists before the test case starts. For some test cases, CDRouter will attempt to delete all existing Phase 1 and/or Phase 2 SAs. CDRouter does this by sending an Informational message with the DELETE payload.
CDRouter IKE can test tunnels with various lifetime values for Phase 1 and Phase 2. However, in some situations, small tunnel lifetimes are recommended. There are a small number of test cases that will wait for Phase 1 and Phase 2 SAs initiated by the gateway to timeout. It may not always be practical to run these tests with the default SA lifetime.
Under normal operation, you should configure CDRouter with same Phase 1 and Phase 2 lifetimes as the gateway under test. In most situations the Phase 2 SA lifetime is usually shorter than the Phase 1 SA lifetime.
Not all IKE gateways support the configuration of short lifetimes. QA Cafe has found that the following sample values work well when running all the test cases in the ike.tcl module:
- IKE SA Lifetime (Phase 1): 300 seconds
- IPsec SA Lifetime (Phase 2): 120 seconds
Longer lifetime values can still be used. However, the tester must be prepared to wait if the gateway initiated deletion test cases are included in the test run.
During some test cases, CDRouter IKE will attempt to initiate IKE and IPsec SAs with a very short lifetime. Some routers will not allow this and will actually set the lifetimes based on their configured values. The short lifetime values used by CDRouter can be configured using the testvars ikeMinimumLifetime and ipsecMinimumLifetime. If the router does not support lifetimes shorter than its own configuration, these values should be set to the same values as the tunnel configuration.
Recovering IKE Tunnels
If a tunnel appears to be down, CDRouter will attempt to bring the tunnel back up using the following approach:
Send traffic on the LAN with a destination address that matches the tunnel
If the tunnel is still down, attempt to initiate a new Phase 1 and Phase 2 exchange
Include the INITIAL-CONTACT Notify Payload in the Phase 1 or Phase 2 exchange to encourage gateway to delete any existing Phase 1 and Phase 2 SAs
Switching IPsec SAs
During several of the test cases, the IPsec SA that is used for tunnel traffic will change. This may happen for several reasons:
The IPsec SA expires and the gateway under test initiates a new IPsec SA
CDRouter IKE sends a DELETE payload for the IPsec SA
The INITIAL-CONTACT status message is sent to restart
After a Quick Mode exchange is completed, CDRouter IKE can be configured to wait a specific amount of time before checking that a new IPsec SA is being used. The testvar ikeNewQuickModeDelay should be configured with the amount of time to wait after a new Quick Mode exchange. The default value is 1000 milliseconds.
CDRouter IKE supports NAT-Traversal (NAT-T) based on RFC 3947 or NAT-T draft versions 00, 02, and 03. When NAT-T is enabled, CDRouter will report NAT Detection payloads that will not match either side of the IKE connection in order to force NAT-T to detect NAT and use UDP encapsulations. All of the existing test cases in the ike.tcl module maybe run when NAT-T is enabled. There is also an additional ike-natt.tcl module that contains specific tests for NAT-T. These test cases may or may not force NAT to be detected. NAT-T may be enabled by selecting the NAT-T version that CDRouter IKE will use.
testvar ikeNatTraversal draft-00
Valid values for ikeNatTraversal are draft-00, draft-02, draft-03, rfc-3947, and no.
You may test that your router interoperates with different versions of NAT-T by changing the version CDRouter IKE will use. Some vendors support multiple versions at the same time in order to work with multiple products. CDRouter IKE only recognizes one version of NAT-T at a time.
Requirements and License
An update is required to your license file in order to enable the CDRouter IKE functionality. Please follow the instructions from email@example.com on how to install an updated license file that enables CDRouter IKE.
CDRouter will report the status of IKE during its normal startup. If CDRouter IKE is enabled, the line “IKE is enabled” will be displayed during the initial start up text.
Note that the CDRouter IPv6 add-on is also required to test IPv6 VPN tunnels.
Starting cdrouter-cli Thu Mar 24 13:27:55 EDT 2016 Copyright (c) 2001-2016 by QA Cafe Version 10.0 build 1 (21394 trunk), built 2016-03-23 17:36:08 by firstname.lastname@example.org (x86_64) Loaded OS distro \S Kernel \r on an \m Loaded OS version Linux-3.10.0-327.10.1.el7.x86_64 x86_64 Loaded Tcl version 8.6.4 Loaded buddy version 10.0.1 (email@example.com) (gcc version 4.8.3 20140911 (Red Hat 4.8.3-9) (GCC) ) Trying to load modules from '.' Trying to load modules from '/usr/cdrouter/tests' Start command: /usr/cdrouter/bin/cdrouter-cli -info Test Suite cdrouter 10.0.1 The system ID is 2df9e2a1f8c359183cf0191a20f2cc5a Using license installed at: /etc/cdrouter.lic Registered to: qacafe Maintenance, Support and Upgrades until: 2016-05-11 Licensed to run: cdrouter Multiport is enabled IPv6 is enabled Storage is enabled IKE is enabled TR69 is enabled TR69-EDM is enabled Nmap is enabled BBF.069 is enabled SNMP is enabled Performance is disabled CPU is Intel(R) Core(TM) i5-4308U CPU @ 2.80GHz, bogomips 5599.98 Loaded TclXML version 3.1 (libxml2), TclDOM 3.0, xmldefs 3.1 Trying to load modules from '/usr/cdrouter/vendor/IOL/BBF.069/Tests' BBF.069 version 1.2.075-11 (19093)
The status of the IKE add-on can also be displayed using the
$ cdrouter-cli –info
The configuration of IKE based tunnels is similar to the existing CDRouter configuration for manual keyed IPsec tunnels. Up to 4096 unique site-to-site IKE tunnels may be configured. Each testvar entry for a tunnel should end with the tunnel number. For example, ipsecTunnelEndPoint1, ipsecTunnelEndPoint2, ipsecTunnelEndPoint3, etc.
You can quickly comment out a tunnel in the CDRouter configuration file by commenting out the testvar ipsecTunnelEndpoint for the tunnel. Not all of the other tunnel testvars need to be commented out to disable the tunnel.
IPsec tunnels can be defined for IPv4 or IPv6.
Global IKE Options
The following testvars are global options that apply to all configured tunnels:
IPsec Tunnel Configuration
The following testvars are used to define a single tunnel. Up to 4096 individual tunnels can be configured. A mix of IPv4 and IPv6 tunnels can be defined.
Example Configuration: IPv4 IKE based tunnel
Here’s a simple example configuration for an IPv4 IKE based tunnel.
testvar ipsecTunnelKeyType1 ike testvar ipsecTunnelEndpoint1 22.214.171.124 testvar ipsecTunnelRemoteNetwork1 126.96.36.199 testvar ipsecTunnelRemoteMask1 255.255.255.0 testvar ipsecTunnelHost1 188.8.131.52 testvar ipsecTunnelIkeEncrypt1 des testvar ipsecTunnelIkeAuth1 sha1-hmac testvar ipsecTunnelIkeGroup1 1 testvar ipsecTunnelIkeLifetime1 150 testvar ipsecTunnelEncrypt1 des testvar ipsecTunnelAuth1 sha1-hmac testvar ipsecTunnelPfsGroup1 1 testvar ipsecTunnelLifetime1 120 testvar ipsecTunnelPsk1 qacafe123 testvar ipsecTunnelIkeMode1 main testvar ipsecTunnelUsesNat1 yes
Example Configuration: IPv6 IKE based tunnel
Here’s a simple example configuration for an IPv6 IKE based tunnel.
testvar ipsecTunnelKeyType1 ike testvar ipsecTunnelEndpoint1 5::1 testvar ipsecTunnelRemoteNetwork1 5:: testvar ipsecTunnelRemoteMask1 ffff:: testvar ipsecTunnelHost1 5::2 testvar ipsecTunnelIkeEncrypt1 des testvar ipsecTunnelIkeAuth1 sha1-hmac testvar ipsecTunnelIkeGroup1 1 testvar ipsecTunnelIkeLifetime1 150 testvar ipsecTunnelEncrypt1 des testvar ipsecTunnelAuth1 sha1-hmac testvar ipsecTunnelPfsGroup1 1 testvar ipsecTunnelLifetime1 120 testvar ipsecTunnelPsk1 qacafe123 testvar ipsecTunnelIkeMode1 main testvar ipsecTunnelUsesNat1 yes
Configuration of local subnet for site-to-site tunnels
When configuring site-to-site tunnels on the gateway under test, the local protected subnet should be the same as the local LAN network on the gateway under test. CDRouter IKE will automatically create a security profile from the remote network to the local subnet on the LAN.
If NAT is also applied to the IPsec tunnel, CDRouter will create a security protocol from the remote network to the assigned WAN IP address.
CDRouter IKE protocol messages can be filtered out using the
options from the command-line. The following protocols are specific to CDRouter
- IKE: All IKE protocol messages
- DH: All Diffie-Hellman relaxed messages.
- IPsec: IPsec messages and events
IKA SA status
By default, CDRouter IKE will show the status of all IKE and IPsec SAs for each
tunnel every 5 seconds when protocol tracing is enabled using the
command line option. This interval can be configured using the testvar ikeStatusInterval
Setting the ikeStatusInterval
0 will completely disable the IKE status reports.
INFO(vpnServer): 18:11:53| ---------- IKE status ----------- INFO(vpnServer): 18:11:53| IKE SA: 1: 9b0338d0ea406c33:cf5194d871a42523 (R) INFO(vpnServer): 18:11:53| tun_0: 60cdebb9 -> aa49ed3c:1150ca45 (R) INFO(vpnServer): 18:11:53| ---------------------------------
The IKE status report shows all Phase 1 SAs (IKE SA) and all the Phase 2 SAs associated with it. If CDRouter IKE initiated the SA the status is shown as (I). If the gateway under test initiated the SA the status is shown as (R).
The CDRouter IKE test suite can be run through several different configurations. The following test scenarios are recommended.
Main Mode and Aggressive Mode
If the gateway under test supports both Main Mode and Aggressive Mode, we recommend running the test suite with a configuration for Main Mode and a configuration for Aggressive Mode. When running in Aggressive Mode, test cases that do not apply will be skipped. You may also consider running a configuration with multiple tunnels that includes both main mode and aggressive mode.
Wireless and Wired Interfaces
Both wired and wireless LAN interfaces should be used when running CDRouter IKE. QA Cafe has seen issues where some routers send wireless traffic in the clear when IKE site-to-site tunnels are down.
Multiple tunnels can be configured on the gateway under test. When multiple tunnels exist, CDRouter IKE will cycle through each tunnel when running each test case. For example, if 2 tunnels are defined and the user executes tests ike_1, ike_2, and ike_4, the first test (ike_1) will run using tunnel 1. The second test (ike_2) will be run using tunnel 2. The last test (ike_4) will be run using tunnel 3.
This behavior can be disabled by configuring the testvar useSameIpsecTunnel to yes. When the testvar useSameIpsecTunnel is set to yes, all ike.tcl test cases will be run against the first tunnel in the configuration file. CDRouter will still respond to any IKE messages on the additional tunnels, but they will not be used for specific test cases.
If the gateway supports NAT over site-to-site tunnels, existing application tests may be run over the site-to-site tunnels by configuring the testvar remoteHostIp within the same range as the ipsecTunnelRemoteNetwork . The remoteHostIp must be different than the values specified by the ipsecTunnelEndpoint and ipsecTunnelHost testvars.
NOTE: When running any application modules over any IPsec tunnel, you should check that the testvars lanMtu and testvar mssClampingValue are set to the expected values. If the gateway supports fragmentation of IPsec packets, then the default value of lanMtu should be fine. IPsec fragmentation can be minimized by dropping the value of lanMtu .
By configuring multiple tunnels, multiple transforms can be run during a single test run. For example, tunnel 1 may be configured with AES-256+SHA1, tunnel 2 may be configured with 3DES+MD5, etc. CDRouter supports thousands of different tunnel configurations due to the number of encryption, authentication, and Diffie-Hellman groups that are supported.
Running the ESP Test Module (ipsec-esp.tcl)
The base version of CDRouter and CDRouter Multiport contain the ipsec- esp.tcl module which can also be run using IKE based tunnels. This test module includes tests specific to the ESP protocol. When IKE is enabled, some of the ipsec-esp.tcl test cases specific to Manual IPsec tunnels are skipped.
Long Duration Testing
Aside running through the ike.tcl module one time per test run, it is
recommended to set up long duration test runs of the ike.tcl module using
-repeat command line option or a CDRouter web package with repeat enabled.
Since many of the values used by IKE are random in nature, longer duration runs
will verify that the gateway continues to operate correctly over time.
Frequent IKE Re-Keying
Another recommended exercise is to stress the number of IKE re-key attempts on the router. This can be done by running test case ike_2 repeatedly. Another good candidate test case is ike_14.
Different NAT-T Versions
It is recommended to try all of the supported CDRouter IKE NAT-T versions even if the device under test only supports a specific version. The main ike.tcl module should still run successfully even when NAT-T is not recognized. Unfortunately, several versions of NAT-T exist in the field and many are not backwards compatible with the first draft version.
Certain IKE behavior issues can have a ripple effect on CDRouter IKE testing. Rather than restarting the VPN gateway before each test, CDRouter IKE brings the VPN gateway through a series of exercises. A failure in one of the test cases can lead to cascading failures. It can be difficult for CDRouter to recover if the active IKE and IPsec SAs get out of sync between CDRouter and the gateway under test. The following examples mention some of the possible problems and possible work-arounds.
IKE or IPsec SAs not deleted with DELETE message
If a gateway does not correctly handle deleting IKE and IPsec SAs using an Informational message, CDRouter IKE and the VPN gateway will not agree on the SAs that exists. Unfortunately, some gateways incorrectly process a DELETE message for IKE SAs and occasionally drop IKE messages. If these problems occur SAs may not get deleted. This problem is usually easy to detect since CDRouter IKE will delete all of its active IKE and IPsec SAs, but the gateway may still initiate a new Quick Mode thinking it has a valid IKE SA. CDRouter will log a message that the IKE SA does not exist.
To work around this type of problem, try running each test one at a time after
restarting the gateway. Another potential work around is to use a long delay in-
between each test to let all SAs expire before each test starts. This can be
done using the
-delay command line option or when building a CDRouter web test
If this problem is only experienced with a specific test case, it may be desirable to add a delay for a single test case. See this Knowledge Base article note for more information.
Gateway reports MALFORMED-PAYLOAD
Often a problem with the encryption keys can lead to a MALFORMED-PAYLOAD error. This may only occur occasionally and disappear in the next Phase 1 or Phase 2 exchange.
Verify that the router correctly handles Diffie-Hellman keys with leading zeros using test cases ike_365 and ike_366. This is a common cause of mismatched encryption keys.