Internet Draft                                            Paul Hoffman
draft-hoffman-ipsec-testing-01.txt                      VPN Consortium
September 9, 2000                                   Michael Richardson
Expires in six months                         Sandelman Software Works

               Steps for IPsec Interoperability Testing

Status of this memo

This document is an Internet-Draft and is in full conformance with all
provisions of Section 10 of RFC2026.

Internet-Drafts are working documents of the Internet Engineering Task
Force (IETF), its areas, and its working groups. Note that other
groups may also distribute working documents as Internet-Drafts.

Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference material
or to cite them other than as "work in progress."

The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt

The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.

Abstract

Bringing up IPsec gateways, clients and end systems is a hard task.
There are the numerous configurations issues that occur when doing this.
Techniques for diagnosing regular nodes may not yeild understandable results
when one or both nodes have network security features.

There is a further difficulty presented by the number of configuration
options presented by a typical IPsec gateway implementation, and the lack of
consistent diagnostics from gateways. The network administrator, field
engineers and product support staff are faced with multiple indistinguishable
failure modes: is the client unable to connect because of a network outage,
or because the two products have never actually tested in that scenario? Or
is the naive user unaware that they are behind a network address translator?

Interoperability testing between systems from different vendors is
often a difficult process. In the case of IPsec implementations,
interoperability testing is made more difficult by the fact that there
are two protocols, IKE and IPsec, that both must work together.

This document defines an ordered set of steps for testing two
systems efficiently. It attempts to isolate network faults from IKE faults,
and IKE faults from IPsec faults.

1. Introduction

Over many years of bakeoffs, IPsec vendors have found many problems
when testing interoperability between devices. Some of these problems
prevent the testing from even beginning, and in such cases the two
parties usually spend a lot of time trying to figure out why nothing is
happening. That time could be better spent debugging the errant system.

To help make the testing and diagnostic process work better, this document
describes the steps that a pair of testers should go through as they test
IPsec implementations. Following these steps together can help pinpoint where
problems occur.

Users in the VPN market expect IPsec implementations to interoperate
instantly and often expect that they will be able to connect two
systems easily. Technical support staff can attest to the fact that
these are very wrong assumptions, and it can take many hours for remote
technical support staff to debug simple problems.

To help save time for both customers and support staff, vendors should
consider implementing debugging user interfaces that follow the steps in this
document. Even if a special mode is not provided, vendors should consider
whether they provide enough diagnostic tools to the end user such that they
would be able to follow a version of this proceedure that could be documented
in their user's manuals.

There are three implementation appendices provided in this document. They
provide details for performing these steps with the FreeS/WAN IPsec
implementation for Linux, for the KAME implementation for *BSD systems, and
for the OpenBSD IPsec implementation. These are three widely available
implementations for which source code is available.

1.1 Terminology

This document is geared towards gateway-to-gateway testing; client-to-
gateway testing is covered towards the end of the document.

IPsec gateways have two interfaces: one to the "inside net", which is
the protected network, and one to the "outside net", which is often the
Internet.

A gateway-to-gateway test environment looks like this:

     oooo     +----+     oooooooooo     +----+     oooo
H1--( N1 )--I1| G1 |O1--( Internet )--O2| G2 |I2--( N2 )--H2
     oooo     +----+     oooooooooo     +----+     oooo

H1 = A host on Network 1
N1 = Network 1
I1 = The inside interface on G1
G1 = Gateway 1
O1 = The outside interface on G1
O2 = The outside interface on G2
G2 = Gateway 2
I2 = The inside interface on G2
N2 = Network 2
H2 = A host on Network 2

The key words "MUST", "SHALL", "REQUIRED", "SHOULD", "RECOMMENDED", and
"MAY" in this document are to be interpreted as described in RFC 2119
[RFC2119].


2. Gateway-to-gateway Testing

The following are the steps used to test gateway-to-gateway IPsec. The
steps follow a logical progression from easiest to hardest so that
problems can be found quickly.

Tests for IPsec clients are a bit simpler than for gateways because the
client has fewer possible settings, and the client is always the
initiator.

In some of the following steps, there is a "ping set". This is a set of
ICMP with six ordered sizes: 64 octets, 256 octets, 512 octets, 1480
octets, 1480 octets with DF, 2048 octets, and 64 octets again. This tests
both unfragmented and fragmented ICMP.

For steps 1 through 9, I1 and I2 should be restricted. That is, they
should be configured but made inactive, if possible. (e.g. the cables should
be disconnected if appropriate)

This is to protect any hosts on the protected networks (N1 and N2) in case
the testing has unexpected results, and to protect the testing from systems
on the protected networks from sending messages to the gateways that might
confuse the testing (such as BGP messages and so on). In client-to-gateway
testing, there is no I1.

Please the section on Security Considerations for further discussion of
testing with live systems.

2.1 Step one: Prepare systems for testing

The two people testing should agree which system is G1 and which is G2.

A simple-minded way of doing this is to say that the system whose IP
address is lower is G1. For automated use, this is a reasonable choice for
pass one, and invert the choice for pass two.

G1 is the initiator. The person testing G1 tells the person testing G2 the IP
address of H1 and O1; the person testing G2 tells the person testing G1 the
IP address of O2 and H2.

2.2 Step two: ICMP Ping test

Send a stream of ICMP pings to G2. Send a ping set.

G2 checks to see if pings got through. A failure to receive the pings
indicates a network or wiring problem.

G1 checks to see that the pings are returned. A failure to return the pings
indicates a network or wiring problem on the reverse path, and may indicate
asymmetric routing is occuring.

A failure of certain sizes to be transmitted may indicate presence of
other tunnels, firewalls, NAT devices, or other IPsec devices.

2.3 Step three: Manual-key testing

Set up SPD entries for manual keying between G1 and G2 as hosts.

Use AH, as it can be most easily examined by dignoses tools.

G1's SPI is 0x00001111; G2's SPI is 0x00002222.

G1's key is 0x0000ffff0000ffff.
G2's key is 0x1111ffff1111ffff.

Use TripleDES for the encryption algorithm, SHA1 for the hash algorithm.

Use tunnel mode.

Use I1 as the originating address and I2 as the terminating address for
the ping set.

Set as few other options as possible. G2 checks to see if pings got through
and that they are encrypted. G1 checks to see that the pings are returned and
that they are not encrypted.

After running this step, remove the manual key entries on G1 and on G2.

[[[Should this be a SPI< 256, assigned by the IANA? ]]]

2.4 Step four: Pre-IKE notify

Use the administrative interface on G1 to send an ISAKMP Notify payload
to G2 without IKE. This makes sure that port 500 UDP can actually
travel between the two gateways.

The transmitter should send three packets of this type, spaced out by
a second or so.

This message has an Exchange type of 5, a Notify Message Type of TEST-
NOTIFY1 (defined in Appendix A of this document).

G2 checks to see that the payload got through, that it had the right message
type, that it actually arrived from UDP port 500, and that the short text
string was readable.

Should the payload not get through, the there is something blocking port 500
in the path.

Should the payload get through, but not be seen to arrive on port 500, then
there is a network address/port translator (NAPT) [see RFC2663], and
communication may not be possible.

Gateway implementations may want to perform this test in general, and log
information to help diagnose this occurance.

[[[They could also return a Notify message to tell the client what is up...]]]

2.5 Step five: Preshared Secret Phase 1

Set up IKE for preshared keys between G1 and G2.

Set options:

[[[ should we mandate use of Main Mode? I1 and I2 are known. ]]]

- Use TripleDES for the encryption algorithm.
- Use SHA1 for the hash algorithm.
- Use Diffie-Hellman Group 2.
- The preshared secret is "mekmitasdigoat".

Negotiate Phase 1, and then send an informational exchange containing
an ISAKMP message protected by Phase 1.

This message has an Exchange type of 5, a Notify Message Type of TEST-NOTIFY2
(defined in Appendix A of this document).

G2 checks to see that the payload got through, that it was encrypted,
that it had the right message type, and that the short text string was
readable.

2.6 Step 6: Preshared Secret Phase 2

Using the same setup as for the previous step, get all the through
Phase 2.

Use tunnel mode.

Set up the SA for the C class address space that includes I1 and H1,
and for the remote address space that includes I2 and H2.

[[[I1 and H1 may not be on the same class C network. Since we never use
      data  from H1/H2, should we use the /24 network that includes
      I1 and the /24 that includes I2??? ]]]

Using I1 as the originating address and I2 as the terminating address,
send a ping set protected by the Phase 2 to G2.

G2 checks to see if pings got through after successful decryption.

G2 should look for pings to arrive that are not encrypted. Typically, this
will be seen as ICMPs from I1 to G2, or as ICMPs from I1 to I2.

G1 checks to see that the pings are returned after successful decryption.

After running this step, remove these preshared secret key entries on
G1 and on G2.

2.7 Step 7: Public key authentication

[[[ this step is very worthwhile, but involves exchanging data. ]]]

Load the self-signed certificate from G2 into G1's trusted store, and the
self-signed certificate from G1 into G2's trusted store.

Set up IKE for signature authentication between G1 and G2.
 - Use TripleDES for the encryption algorithm.
 - Use SHA1 for the hash algorithm.
 - Use tunnel mode.
[[[ ditto question about Main Mode ]]]

Set up the SA for the C class address space that includes I1 and H1.

[[[ ditto question about /24 networks ]]]

Set up the identification based on the IP addresses of O1 and O2.
Send a ping set protected by the Phase 2 to G2.

G2 checks to see if pings got through after successful decryption.

G2 should look for pings to arrive that are not encrypted. Typically, this
will be seen as ICMPs from I1 to G2, or as ICMPs from I1 to I2.

G1 checks to see that the pings are returned after successful decryption.

After this step, reset the trusted store of G1 and G2, removing the
certificates that were inserted.

2.8 Step 8: Well known public certificates

Load the well known public keys provides in appendix B into the trusted
store of G1 and G2.
Using the published private key provided in appendix C, generate approprixate
certificates. A proceedure for doing this is provided in appendix B.

Perform the same exchange as for step 7.

After this step, reset the trusted store of G1 and G2, removing the
certificates that were inserted.

2.9 Step 9: Certificates

Verbally determine that at least one trusted root is shared by G1 and G2.

Compare the fingerprint of the trusted root's certificate to be
sure that both certificates are in fact the same.

Perform the same exchange as for step 7.

After this step, reset the trusted store of G1 and G2, removing the
certificates that were inserted.

Step 10: Host to Host

This step should only be done in controlled environments, such as in
bakeoffs, or in lab settings.

Set up IKE to cause all traffic between H1 and H2 to be protected by
IPsec.
 - Use TripleDES for the encryption algorithm.
 - Use SHA1 for the hash algorithm.

Turn on I1 and I2. Send a stream of ICMP pings from H1 to H2. H1 and H2
check to see if pings got through. If possible, G1 should check at O1
for encrypted traffic to H1, and G2 should check at O2 for encrypted
traffic to H2.

(Note that client-to-gateway tests can skip this step and the following
one as well.)

Step 11: Change Roles

Long experience with interoperability testing of IPsec has found that,
in some cases, a pair of systems that works just fine when one is the
initiator doesn't work at all when the other is the initiator. Thus, G1
and G2 should change roles here and go through the steps again.

[[[ do we need a step 12 to have a 12-step program ]]]

3. User Debug Mode

Automated versions of the steps in this document can be included in
shipping products. Doing so would allow users who are having a problem
hooking two IPsec systems together to more quickly determine where the
problem lies. Having the steps built into one of the two systems would
still help facilitate testing as long as the person running the other
system knew of the steps.

An automated debug program might start with a way of giving the
relevant IP addresses and a way of specifying whether the system was G1
or G2. From that point, there might be eleven buttons that say "do step
1", "do step 2" and so on. Of course, such a system should give copious
debugging output as well as a simplified pass or fail indication.

[[[ PAUL: Should suggested values be included in this document? It would be
nice if technical support could ask customers to put the gateway into
"RFCXXXX test mode" and send the output to tech support.
MCR: says yes. We can specify I1/I2 and a root CA ]]]

4. Security Considerations

Testing security systems inherently means reducing the security of the
systems during the tests. It is extremely important that the testers
reset any changes they made during the tests. Specifically, testers
should remove any manual keys and preshared secrets as indicated in the
steps described.

This testing system is invasive: the configurations of both G1 and G2 is
affected, and neither gateway will be able to process traffic for another
other connections.

To permit other traffic to flow during this testing proceedure would require
that the gateways remain connected to their respective internal networks.

As noted, step 10 should not be performed except in very controlled
environments.

5. References

[RFC2119] Scott Bradner, "Key words for use in RFCs to Indicate
          Requirement Levels", March 1997, RFC 2119.

[RFC2407] Derrell Piper, "The Internet IP Security Domain of
          Interpretation for ISAKMP", RFC 2407.

[RFC2663]  P. Srisuresh, M. Holdrege, "IP Network Address Translator (NAT)
       Terminology and Considerations", RFC 2663


Appendix A. IANA Considerations

A.1 Registration for new ISAKMP Notify Message Type: TEST-NOTIFY1

This is the registration for a new ISAKMP Notify Message Type called
TEST-NOTIFY1. This registration extends the registrations given in
[RFC2407], section 4.6.3.

TEST-NOTIFY1 is a status-type message. Its value is 24579.

The TEST-NOTIFY1 status message MAY be used in debugging situations to
verify that port 500 UDP packets can travel between two IPsec systems.
It MUST only be used for this purpose; it MUST NOT appear in any other
context.

Note that [RFC2407] specifies "Notification Status Messages MUST be
sent under the protection of an ISAKMP SA". In the context of this
document, TEST-NOTIFY1 is sent before any protection is negotiated.
This relaxing of the requirement in [RFC2407] applies only to the TEST-
NOTIFY1 message, not to any other message defined in [RFC2407].

When present, the Notification Payload MUST have the following format:

o  Payload Length - set to length of payload + size of data (var)
o  DOI - set to IPSEC DOI (1)
o  Protocol ID - set to 1 (ISAKMP)
o  SPI Size - set to 4 (one IPSEC SPI)
o  Notify Message Type - set to TEST-NOTIFY1 (24579)
o  SPI - set to a 4-octet value that is ignored
o  Free text - Text in from the US-ASCII charset

A.2 Registration for new ISAKMP Notify Message Type: TEST-NOTIFY2

This is the registration for a new ISAKMP Notify Message Type called
TEST-NOTIFY2. This registration extends the registrations given in
[RFC2407], section 4.6.3.

TEST-NOTIFY2 is a status-type message. Its value is 24580.

The TEST-NOTIFY2 status message MAY be used in debugging situations to
verify that a phase 1 SA can be fully set up between two IPsec systems.
It MUST only be used for this purpose; it MUST NOT appear in any other
context.

When present, the Notification Payload MUST have the following format:

o  Payload Length - set to length of payload + size of data (var)
o  DOI - set to IPSEC DOI (1)
o  Protocol ID - set to 1 (ISAKMP)
o  SPI Size - set to 4 (one IPSEC SPI)
o  Notify Message Type - set to TEST-NOTIFY2 (24580)
o  SPI - set to a 4-octet value that is ignored
o  Free text - Text in from the US-ASCII charset

B. Well known public keys

[[[ generate a set of keys with OpenSSL's CA tools, publish here ]]]

C. Implementation of testing proceedure for FreeSWAN

[[[ Hugh? ]]]

D. Implementation of testing proceedure for KAME

[[[ Itojun? ]]]

E. Implementation of testing proceedure for OpenBSD

[[[ Angelos? ]]]

Author Contact Information

Paul Hoffman, Director
VPN Consortium
127 Segre Place
Santa Cruz, CA  95060
paul.hoffman@vpnc.org

Michael Richardson
Sandelman Software Works
152 Rochester Street
Ottawa, ON
K1R 7M4
Canada
mcr@sandelman.ottawa.on.ca