3 conftest - an IKEv2 conformance testing framework
4 =================================================
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.
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.
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.
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.
34 3. Configuration syntax
35 -----------------------
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.
41 The syntax is as follows:
43 settings := (section|keyvalue)*
44 section := name { settings }
45 keyvalue := key = value\n
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
52 The test specific configuration is merged to the suite configuration, resulting
53 in a unified configuration. Sections are merged, keys in the test configuration
54 overwrite existing identical keys in the suite configuration.
59 Logging verbosity can be controlled in the log section of a suite/test
60 configuration. The stdout subsection takes logging facility/verbosity key
61 value pairs, the different facility types are defined in debug_lower_names at
62 src/libstrongswan/debug.c.
63 Any other sub-section in the log section is considered as a file name to log
64 to. Each section takes the same facility/verbosity keys as the special stdout
70 Both the suite and test configuration may contain connection definitions under
71 the configs section. Each IKE_SA configuration has a sub-section. Each IKE_SA
72 sub-section contains one or more CHILD_SA configuration sub-sections:
86 Configuration names can be chosen arbitrary, but should be unique within the
89 The IKE_SA configuration uses the following options (as key/value pairs):
91 lhost: Address (IP or Hostname) of this host
92 rhost: Address (IP or Hostname) of tested host
93 lid: IKEv2 identifier of this host
94 rid: IKEv2 identifier of tested host
95 proposal: IKE_SA proposal list, comma separated, e.g.:
96 aes128-sha1-modp2048,3des-md5-sha1-modp1024-modp1536
97 Supported algorithm names are defined under
98 src/libstrongswan/crypt/proposal/proposal_keywords.txt
99 fake_nat: Fake the NAT_DETECTION_*_IP payloads to simulate a NAT
101 rsa_strength: Connection requires a trustchain with RSA keys of given bits
102 ecdsa_strength: Connection requires a trustchain with ECDSA keys of given bits
103 cert_policy: Connection requires a certificate with the given OID policy
104 named_pool: Name of an IP pool defined e.g. in a database backend
106 The following CHILD_SA specific configuration options are supported:
108 lts: Local side traffic selectors, comma separated CIDR subnets
109 rts: Remote side traffic selectors, comma separated CIDR subnets
110 transport: Propose IPsec transport mode instead of tunnel mode
111 tfc_padding: Inject Traffic Flow Confidentiality bytes to align packets to the
113 proposal: CHILD_SA proposal list, same syntax as IKE_SA proposal list
118 Credentials may be defined globally in the suite or locally in the test specific
119 configuration file. Certificates files are defined in the certs section, either
120 in the trusted or in the untrusted section. Trusted certificates are trust
121 anchors, usually root CA certificates. Untrusted certificates do not build a
122 trust anchor and usually contain intermediate or end entity certificates.
124 Certificates files are loaded relative to the configuration file path and may
125 be encoded either in plain ASN.1 DER or in PEM format. The prefix of the
126 key/value pair is used to specify the type of the certificate, usually x509 or
129 Private keys can be defined in the suite or test config file under the keys
130 section. The prefix of the key/value pair must be either rsa or ecdsa, the
131 specified file may be encoded in ASN.1 DER or unencrypted PEM.
138 x509-me = /path/to/cert.pem
139 crl-from-ca = /path/to/crl.pem
143 ecdsa-me = /path/to/key.pem
149 The actions section in the test specific configuration file defines
150 the IKEv2 protocol actions to trigger. Currently, the following actions
151 are supported and take these arguments (as key/value pairs):
153 initiate: Initiate an IKE- and CHILD_SA
154 config: name of the CHILD_SA configuration to initiate
155 delay: Delay to trigger action after startup
156 rekey_ike: Rekey an IKE_SA
157 config: name of originating IKE_SA configuration
158 delay: Delay to trigger action after startup
159 rekey_child: Rekey an CHILD_SA
160 config: name of originating CHILD_SA configuration
161 delay: Delay to trigger action after startup
162 liveness: Do a liveness check (DPD) on the IKE_SA
163 config: name of originating IKE_SA configuration
164 delay: Delay to trigger action after startup
165 close_ike: Close an IKE_SA
166 config: name of originating IKE_SA configuration
167 delay: Delay to trigger action after startup
168 close_child: Close a CHILD_SA
169 config: name of originating IKE_SA configuration
170 delay: Delay to trigger action after startup
172 To trigger the same action multiple times, the action sections must be named
173 uniquely. Append an arbitrary string to the action name. The following example
174 initiates a connection and rekeys it twice:
193 The hooks section section in the test configuration defines different hooks
194 to use to mangle packets or trigger other protocol modifications. These
195 hook functions are implemented in the hooks folder of conftest.
197 Currently, the following hooks are defined with the following options:
199 add_notify: Add a notify to a message
200 request: yes to include in request, no in response
201 id: IKEv2 message identifier of message to add notify
202 type: notify type to add, names defined in notify_type_names
203 under src/libcharon/encoding/payloads/notify_payload.c
204 data: notification data to add, prepend 0x to interpret the
206 spi: SPI to use in notify
207 esp: yes to send an ESP protocol notify, no for IKE
208 add_payload: Add an arbitrary payload to a message
209 request: yes to include in request, no in response
210 id: IKEv2 message identifier of message to add payload
211 type: type of the payload to add, names defined in
212 payload_type_short_names in payload.c
213 data: data to append after generic payload header, use 0x
214 prefix for hex encoded data
215 critical: yes to set payload critical bit
216 replace: yes to replace an existing payload of the same type
217 custom_proposal: set a custom proposal value in the SA payload
218 request: yes to include in request, no in response
219 id: IKEv2 message identifier of message to add notify
220 The hook takes subsections with numerical names, each
221 defining a proposal substructure. The substructure
222 takes key/value pairs, where key defines the type, value
223 the specific algorithm.
224 force_cookie: Reject IKE_SA_INIT requests with a COOKIE
225 ignore_message: Ignore a specific message, simulating packet loss
226 inbound: yes to ignore incoming, no for outgoing messages
227 request: yes to ignore requests, no for responses
228 id: IKEv2 message identifier of message to ignore
229 ike_auth_fill: Fill up IKE_AUTH message to a given size using a CERT
231 request: yes to fill requests messages, no for responses
232 id: IKEv2 message identifier of message to fill up
233 bytes: number of bytes the final IKE_AUTH message should have
234 log_id: Comfortably log received ID payload contents
235 log_ke: Comfortably log received KE payload DH groups
236 log_proposal: Comfortably log all proposals received in SA payloads
237 log_ts: Comfortably log all received TS payloads
238 pretend_auth: magically reconstruct IKE_AUTH response even if
239 AUTHENTICATION_FAILED received
240 rebuild_auth: rebuild AUTH payload, i.e. if ID payload changed
241 reset_seq: Reset sequence numbers of an ESP SA
242 delay: Seconds to delay reset after SA established
243 oseq: Sequence number to set, default is 0
244 set_critical: Set critical bit on existing payloads:
245 request: yes to set in request, no in response
246 id: IKEv2 message identifier of message to mangle payloads
247 payloads: space separated payload list to set critical bit on
248 set_ike_initiator: toggle IKE initiator flag in IKE header
249 request: yes to set in request, no in response
250 id: IKEv2 message identifier of message to mangle
251 set_ike_request: toggle IKE request flag in IKE header
252 request: yes to set in request, no in response
253 id: IKEv2 message identifier of message to mangle
254 set_ike_spi: set the IKE SPIs in IKE header
255 request: yes to set in request, no in response
256 id: IKEv2 message identifier of message to mangle
257 spii: initiator SPI to set (as decimal integer)
258 spir: responder SPI to set
259 set_ike_version: set version fields in IKE header
260 request: yes to set in request, no in response
261 id: IKEv2 message identifier of message to mangle
262 major: major version to set
263 minor: minor version to set
264 higher: yes to set Higher Version Supported flag
265 set_length: set the length in a payload header
266 request: yes to set in request, no in response
267 id: IKEv2 message identifier of message to mangle
268 type: payload type to mangle
269 diff: difference to add/remove from real length (+1,-3 etc.)
270 set_proposal_number:Change the number of a proposal in a SA payload
271 request: yes to set in request, no in response
272 id: IKEv2 message identifier of message to mangle
273 from: proposal number to mangle
274 to: new proposal number to set instead of from
275 set_reserved: set arbitrary reserved bits/bytes in payloads
276 request: yes to set in request, no in response
277 id: IKEv2 message identifier of message to mangle
278 The hook takes a list of subsection, each named as payload
279 type. Each section takes a bits and a bytes key, the
280 value is a comma separated list of decimal numbers of
281 bits/bytes to mangle (1 is the first reserved bit/byte
282 in the payload). The byteval key defines to which value
283 set mangled bytes in the byte list.
284 unencrypted_notify: Send an unencrypted message with a notify after
285 establishing an IKE_SA
286 id: IKEv2 message identifier of message to send
287 type: notify type to add, names defined in notify_type_names
288 under src/libcharon/encoding/payloads/notify_payload.c
289 data: notification data to add, prepend 0x to interpret the
291 spi: SPI to use in notify
292 esp: yes to send an ESP protocol notify, no for IKE
293 unsort_message: reorder the payloads in a message
294 request: yes to reorder requests messages, no for responses
295 id: IKEv2 message identifier of message to reorder
296 order: payload order, space separated payload names as defined
297 in payload_type_short_names under
298 src/libcharon/encoding/payloads/payload.c
303 Compile time options required depend on the test suite. A minimalistic
304 strongSwan build with the OpenSSL crypto backend can be configured with:
306 ./configure --sysconfdir=/etc --disable-pluto --disable-scripts \
307 --disable-scepclient --disable-aes --disable-des --disable-md5 \
308 --disable-sha1 --disable-sha2 --disable-fips-prf --disable-gmp \
309 --disable-pubkey --disable-pgp --disable-dnskey --disable-updown \
310 --disable-attr --disable-resolve --enable-openssl --enable-conftest \
311 --enable-gcm --enable-ccm --enable-ctr
313 The conftest utility is installed by default under /usr/local/libexec/ipsec/,
314 but can be invoked with the ipsec helper script. It takes a suite specific
315 configuration file after the --suite option and a test specific file with
318 ipsec conftest --suite suite.conf --test 1.1.1/test.conf