Added a short README about the conftest utility
[strongswan.git] / src / conftest / README
1
2
3              conftest - an IKEv2 conformance testing framework
4              =================================================
5
6
7 1. Introduction
8 ---------------
9
10 conftest is a conformance testing framework for IKEv2 and related protocols,
11 based on the strongSwan IKEv2 daemon charon. It uses a specialized configuration
12 and control front-end, but links against the mainstream strongSwan IKEv2 stack.
13
14 The conftest framework can test other implementations of IKEv2 and related
15 standards. It can inject or mangle packets to test the behavior of other
16 implementations under certain conditions.
17
18 2. Test suites
19 --------------
20
21 The framework can use different sets of conformance tests, called test suites.
22 Each test suite contains a global suite configuration file, usually named
23 suite.conf. It contains the global settings for all tests in this suite, mostly
24 credentials and connection definitions.
25
26 A test suite consists of several test cases. Each test has its own configuration
27 file, often called test.conf. The test configuration file may contain test
28 specific credentials and connection definitions, but primarily defines actions
29 and hooks. Actions trigger certain protocol specific operations, such as
30 initiating or terminating a tunnel. Hooks are used to change the behavior of
31 the IKE stack, most likely to stress some factors of the IKE protocol and
32 provoke unintended behavior in the tested platform.
33
34 3. Configuration syntax
35 -----------------------
36
37 Both the suite and the test specific configuration file use the same syntax.
38 It is the same as used by the strongswan.conf file used to configure the
39 strongSwan software suite.
40
41 The syntax is as follows:
42
43  settings := (section|keyvalue)*
44  section  := name { settings }
45  keyvalue := key = value\n
46
47 Settings contain zero or more sub-sections or key/value pairs. A section
48 consists of a name, followed by curly open and close brackets. The value in the
49 key/value pair starts after the equal sign and is terminated by the end of the
50 line.
51
52 4. Connections
53 --------------
54
55 Both the suite and test configuration may contain connection definitions under
56 the configs section. Each IKE_SA configuration has a sub-section. Each IKE_SA
57 sub-section contains one or more CHILD_SA configuration sub-sections:
58
59 configs {
60     ike-a {
61         # ... ike options
62         child-a1 {
63             # ... child options
64         }
65         child-a2 {
66             # ...
67         }
68     }
69 }
70
71 Configuration names can be chosen arbitrary, but should be unique within the
72 same file.
73
74 The IKE_SA configuration uses the following options (as key/value pairs):
75
76   lhost:    Address (IP or Hostname) of this host
77   rhost:    Address (IP or Hostname) of tested host
78   lid:      IKEv2 identifier of this host
79   rid:      IKEv2 identifier of tested host
80   proposal: IKE_SA proposal list, comma separated, e.g.:
81             aes128-sha1-modp2048,3des-md5-sha1-modp1024-modp1536
82             Supported algorithm names are defined under
83             src/libstrongswan/crypt/proposal/proposal_keywords.txt
84
85 The following CHILD_SA specific configuration options are supported:
86
87   lts:      Local side traffic selectors, comma separated CIDR subnets
88   rts:      Remote side traffic selectors, comma separated CIDR subnets
89
90 5. Credentials
91 --------------
92
93 Credentials may be defined globally in the suite or locally in the test specific
94 configuration file. Certificates files are defined in the certs section, either
95 in the trusted or in the untrusted section. Trusted certificates are trust
96 anchors, usually root CA certificates. Untrusted certificates do not build a
97 trust anchor and usually contain intermediate or end entity certificates.
98
99 Certificates files are loaded relative to the configuration file path and may
100 be encoded either in plain ASN.1 DER or in PEM format. The name of the key/value
101 pair is used to specify the type of the certificate, usually x509.
102
103 Private keys can be defined in the suite or test config file under the keys
104 section. The name of the key/value pair must be either rsa or ecdsa, the
105 specified file may be encoded in ASN.1 DER or unencrypted PEM.
106
107 certs {
108     trusted {
109         x509 = ca.pem
110     }
111     untrusted {
112         x509 = /path/to/cert.pem
113     }
114 }
115 keys {
116     ecdsa = /path/to/key.pem
117 }
118
119 6. Actions
120 ----------
121
122 The actions section in the test specific configuration file defines
123 the IKEv2 protocol actions to trigger. Currently, the following actions
124 are supported and take these arguments (as key/value pairs):
125
126   initiate:    Initiate an IKE- and CHILD_SA
127                config: name of the CHILD_SA configuration to initiate
128                delay: Delay to trigger action after startup
129   rekey_ike:   Rekey an IKE_SA
130                config: name of originating IKE_SA configuration
131                delay: Delay to trigger action after startup
132   rekey_child: Rekey an CHILD_SA
133                config: name of originating CHILD_SA configuration
134                delay: Delay to trigger action after startup
135   liveness:    Do a liveness check (DPD) on the IKE_SA
136                config: name of originating IKE_SA configuration
137                delay: Delay to trigger action after startup
138   close_ike:   Close an IKE_SA
139                config: name of originating IKE_SA configuration
140                delay: Delay to trigger action after startup
141   close_child: Close a CHILD_SA
142                config: name of originating IKE_SA configuration
143                delay: Delay to trigger action after startup
144
145 To trigger the same action multiple times, the action sections must be named
146 uniquely. Append an arbitrary string to the action name. The following example
147 initiates a connection and rekeys it twice:
148
149 actions {
150     initiate {
151         config = child-a1
152     }
153     rekey_ike-1 {
154         config = ike-a
155         delay = 3
156     }
157     rekey_ike-2 {
158         config = ike-a
159         delay = 6
160     }
161 }
162
163 7. Hooks
164 --------
165
166 The hooks section section in the test configuration defines different hooks
167 to use to mangle packets or trigger other protocol modifications. These
168 hook functions are implemented in the hooks folder of conftest.
169
170 Currently, the following hooks are defined with the following options:
171
172   ignore_message:     Ignore a specific message, simulating packet loss
173     inbound:          yes to ignore incoming, no for outgoing messages
174     request:          yes to ignore requests, no for responses
175     id:               IKEv2 message identifier of message to ignore
176   add_notify:         Add a notify to a message
177     request:          yes to include in request, no in response
178     id:               IKEv2 message identifier of message to add notify
179     type:             notify type to add, names defined in notify_type_names
180                       under src/libcharon/encoding/payloads/notify_payload.c
181     data:             notification data to add, prepend 0x to interpret the
182                       string as hex string
183     spi:              SPI to use in notify
184     esp:              yes to send an ESP protocol notify, no for IKE
185   unencrypted_notify: Send an unencrypted message with a notify after
186                       establishing an IKE_SA
187     id:               IKEv2 message identifier of message to send
188     type:             notify type to add, names defined in notify_type_names
189                       under src/libcharon/encoding/payloads/notify_payload.c
190     data:             notification data to add, prepend 0x to interpret the
191                       string as hex string
192     spi:              SPI to use in notify
193     esp:              yes to send an ESP protocol notify, no for IKE
194   unsort_message:     reorder the payloads in a message
195     request:          yes to reorder requests messages, no for responses
196     id:               IKEv2 message identifier of message to reorder
197     order:            payload order, space separated payload names as defined
198                       in payload_type_short_names under
199                       src/libcharon/encoding/payloads/payload.c
200   ike_auth_fill:      Fill up IKE_AUTH message to a given size using CERT
201                       a payload.
202     request:          yes to fill requests messages, no for responses
203     id:               IKEv2 message identifier of message to fill up
204     bytes:            number of bytes the final IKE_AUTH message should have
205
206 8. Invoking
207 -----------
208
209 Compile time options required depend on the test suite. A minimalistic
210 strongSwan build with the OpenSSL crypto backend can be configured with:
211
212 ./configure --sysconfdir=/etc --disable-pluto --disable-scripts \
213   --disable-tools --disable-stroke --disable-aes --disable-des --disable-md5 \
214   --disable-sha1 --disable-sha2 --disable-fips-prf --disable-gmp \
215   --disable-pubkey --disable-pgp --disable-dnskey --disable-updown \
216   --disable-attr --disable-resolve --enable-openssl --enable-conftest \
217   --enable-gcm --enable-ccm --enable-ctr
218
219 The conftest utility is installed by default under /usr/local/libexec/ipsec/,
220 but can be invoked with the ipsec helper script. It takes a suite specific
221 configuration file after the --suite option and a test specific file with
222 the --test option:
223
224   ipsec conftest --suite suite.conf --test 1.1.1/test.conf