1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
|
conftest - an IKEv2 conformance testing framework
=================================================
1. Introduction
---------------
conftest is a conformance testing framework for IKEv2 and related protocols,
based on the strongSwan IKEv2 daemon charon. It uses a specialized configuration
and control front-end, but links against the mainstream strongSwan IKEv2 stack.
The conftest framework can test other implementations of IKEv2 and related
standards. It can inject or mangle packets to test the behavior of other
implementations under certain conditions.
2. Test suites
--------------
The framework can use different sets of conformance tests, called test suites.
Each test suite contains a global suite configuration file, usually named
suite.conf. It contains the global settings for all tests in this suite, mostly
credentials and connection definitions.
A test suite consists of several test cases. Each test has its own configuration
file, often called test.conf. The test configuration file may contain test
specific credentials and connection definitions, but primarily defines actions
and hooks. Actions trigger certain protocol specific operations, such as
initiating or terminating a tunnel. Hooks are used to change the behavior of
the IKE stack, most likely to stress some factors of the IKE protocol and
provoke unintended behavior in the tested platform.
3. Configuration syntax
-----------------------
Both the suite and the test specific configuration file use the same syntax.
It is the same as used by the strongswan.conf file used to configure the
strongSwan software suite.
The syntax is as follows:
settings := (section|keyvalue)*
section := name { settings }
keyvalue := key = value\n
Settings contain zero or more sub-sections or key/value pairs. A section
consists of a name, followed by curly open and close brackets. The value in the
key/value pair starts after the equal sign and is terminated by the end of the
line.
The test specific configuration is merged to the suite configuration, resulting
in a unified configuration. Sections are merged, keys in the test configuration
overwrite existing identical keys in the suite configuration.
4. Logging
----------
Logging verbosity can be controlled in the log section of a suite/test
configuration. The stdout subsection takes logging facility/verbosity key
value pairs, the different facility types are defined in debug_lower_names at
src/libstrongswan/debug.c.
Any other sub-section in the log section is considered as a file name to log
to. Each section takes the same facility/verbosity keys as the special stdout
section.
5. Connections
--------------
Both the suite and test configuration may contain connection definitions under
the configs section. Each IKE_SA configuration has a sub-section. Each IKE_SA
sub-section contains one or more CHILD_SA configuration sub-sections:
configs {
ike-a {
# ... ike options
child-a1 {
# ... child options
}
child-a2 {
# ...
}
}
}
Configuration names can be chosen arbitrary, but should be unique within the
same file.
The IKE_SA configuration uses the following options (as key/value pairs):
lhost: Address (IP or Hostname) of this host
rhost: Address (IP or Hostname) of tested host
lid: IKEv2 identifier of this host
rid: IKEv2 identifier of tested host
proposal: IKE_SA proposal list, comma separated, e.g.:
aes128-sha1-modp2048,3des-md5-sha1-modp1024-modp1536
Supported algorithm names are defined under
src/libstrongswan/crypt/proposal/proposal_keywords.txt
fake_nat: Fake the NAT_DETECTION_*_IP payloads to simulate a NAT
scenario
rsa_strength: Connection requires a trustchain with RSA keys of given bits
ecdsa_strength: Connection requires a trustchain with ECDSA keys of given bits
cert_policy: Connection requires a certificate with the given OID policy
named_pool: Name of an IP pool defined e.g. in a database backend
The following CHILD_SA specific configuration options are supported:
lts: Local side traffic selectors, comma separated CIDR subnets
rts: Remote side traffic selectors, comma separated CIDR subnets
transport: Propose IPsec transport mode instead of tunnel mode
tfc_padding: Inject Traffic Flow Confidentialty bytes to align packets to the
given length
proposal: CHILD_SA proposal list, same syntax as IKE_SA proposal list
6. Credentials
--------------
Credentials may be defined globally in the suite or locally in the test specific
configuration file. Certificates files are defined in the certs section, either
in the trusted or in the untrusted section. Trusted certificates are trust
anchors, usually root CA certificates. Untrusted certificates do not build a
trust anchor and usually contain intermediate or end entity certificates.
Certificates files are loaded relative to the configuration file path and may
be encoded either in plain ASN.1 DER or in PEM format. The prefix of the
key/value pair is used to specify the type of the certificate, usually x509 or
crl.
Private keys can be defined in the suite or test config file under the keys
section. The prefix of the key/value pair must be either rsa or ecdsa, the
specified file may be encoded in ASN.1 DER or unencrypted PEM.
certs {
trusted {
x509-a-ca = ca.pem
}
untrusted {
x509-me = /path/to/cert.pem
crl-from-ca = /path/to/crl.pem
}
}
keys {
ecdsa-me = /path/to/key.pem
}
7. Actions
----------
The actions section in the test specific configuration file defines
the IKEv2 protocol actions to trigger. Currently, the following actions
are supported and take these arguments (as key/value pairs):
initiate: Initiate an IKE- and CHILD_SA
config: name of the CHILD_SA configuration to initiate
delay: Delay to trigger action after startup
rekey_ike: Rekey an IKE_SA
config: name of originating IKE_SA configuration
delay: Delay to trigger action after startup
rekey_child: Rekey an CHILD_SA
config: name of originating CHILD_SA configuration
delay: Delay to trigger action after startup
liveness: Do a liveness check (DPD) on the IKE_SA
config: name of originating IKE_SA configuration
delay: Delay to trigger action after startup
close_ike: Close an IKE_SA
config: name of originating IKE_SA configuration
delay: Delay to trigger action after startup
close_child: Close a CHILD_SA
config: name of originating IKE_SA configuration
delay: Delay to trigger action after startup
To trigger the same action multiple times, the action sections must be named
uniquely. Append an arbitrary string to the action name. The following example
initiates a connection and rekeys it twice:
actions {
initiate {
config = child-a1
}
rekey_ike-1 {
config = ike-a
delay = 3
}
rekey_ike-2 {
config = ike-a
delay = 6
}
}
8. Hooks
--------
The hooks section section in the test configuration defines different hooks
to use to mangle packets or trigger other protocol modifications. These
hook functions are implemented in the hooks folder of conftest.
Currently, the following hooks are defined with the following options:
add_notify: Add a notify to a message
request: yes to include in request, no in response
id: IKEv2 message identifier of message to add notify
type: notify type to add, names defined in notify_type_names
under src/libcharon/encoding/payloads/notify_payload.c
data: notification data to add, prepend 0x to interpret the
string as hex string
spi: SPI to use in notify
esp: yes to send an ESP protocol notify, no for IKE
add_payload: Add an arbitrary payload to a message
request: yes to include in request, no in response
id: IKEv2 message identifier of message to add payload
type: type of the payload to add, names defined in
payload_type_short_names in payload.c
data: data to append after generic payload header, use 0x
prefix for hex encoded data
critical: yes to set payload critical bit
replace: yes to replace an existing payload of the same type
custom_proposal: set a custom proposal value in the SA payload
request: yes to include in request, no in response
id: IKEv2 message identifier of message to add notify
The hook takes subsections with numerical names, each
defining a proposal substructure. The substructure
takes key/value pairs, where key defines the type, value
the specific algorithm.
force_cookie: Reject IKE_SA_INIT requests with a COOKIE
ignore_message: Ignore a specific message, simulating packet loss
inbound: yes to ignore incoming, no for outgoing messages
request: yes to ignore requests, no for responses
id: IKEv2 message identifier of message to ignore
ike_auth_fill: Fill up IKE_AUTH message to a given size using a CERT
payload.
request: yes to fill requests messages, no for responses
id: IKEv2 message identifier of message to fill up
bytes: number of bytes the final IKE_AUTH message should have
log_id: Comfortably log received ID payload contents
log_ke: Comfortably log received KE payload DH groups
log_proposal: Comfortably log all proposals received in SA payloads
log_ts: Comfortably log all received TS payloads
pretend_auth: magically reconstruct IKE_AUTH response even if
AUTHENTICATION_FAILED received
rebuild_auth: rebuild AUTH payload, i.e. if ID payload changed
reset_seq: Reset sequence numbers of an ESP SA
delay: Seconds to delay reset after SA established
oseq: Sequence number to set, default is 0
set_critical: Set critical bit on existing payloads:
request: yes to set in request, no in response
id: IKEv2 message identifier of message to mangle payloads
payloads: space separated payload list to set critical bit on
set_ike_initiator: toggle IKE initiator flag in IKE header
request: yes to set in request, no in response
id: IKEv2 message identifier of message to mangle
set_ike_request: toggle IKE request flag in IKE header
request: yes to set in request, no in response
id: IKEv2 message identifier of message to mangle
set_ike_spi: set the IKE SPIs in IKE header
request: yes to set in request, no in response
id: IKEv2 message identifier of message to mangle
spii: initiator SPI to set (as decimal integer)
spir: responder SPI to set
set_ike_version: set version fields in IKE header
request: yes to set in request, no in response
id: IKEv2 message identifier of message to mangle
major: major version to set
minor: minor version to set
higher: yes to set Higher Version Supported flag
set_length: set the length in a payload header
request: yes to set in request, no in response
id: IKEv2 message identifier of message to mangle
type: payload type to mangle
diff: difference to add/remove from real length (+1,-3 etc.)
set_proposal_number:Change the number of a proposal in a SA payload
request: yes to set in request, no in response
id: IKEv2 message identifier of message to mangle
from: proposal number to mangle
to: new porposal number to set instead of from
set_reserved: set arbitrary reserved bits/bytes in payloads
request: yes to set in request, no in response
id: IKEv2 message identifier of message to mangle
The hook takes a list of subsection, each named as payload
type. Each section takes a bits and a bytes key, the
value is a comma separated list of decimal numbers of
bits/bytes to mangle (1 is the first reserved bit/byte
in the payload). The byteval key defines to which value
set mangled bytes in the byte list.
unencrypted_notify: Send an unencrypted message with a notify after
establishing an IKE_SA
id: IKEv2 message identifier of message to send
type: notify type to add, names defined in notify_type_names
under src/libcharon/encoding/payloads/notify_payload.c
data: notification data to add, prepend 0x to interpret the
string as hex string
spi: SPI to use in notify
esp: yes to send an ESP protocol notify, no for IKE
unsort_message: reorder the payloads in a message
request: yes to reorder requests messages, no for responses
id: IKEv2 message identifier of message to reorder
order: payload order, space separated payload names as defined
in payload_type_short_names under
src/libcharon/encoding/payloads/payload.c
9. Invoking
-----------
Compile time options required depend on the test suite. A minimalistic
strongSwan build with the OpenSSL crypto backend can be configured with:
./configure --sysconfdir=/etc --disable-pluto --disable-scripts \
--disable-scepclient --disable-aes --disable-des --disable-md5 \
--disable-sha1 --disable-sha2 --disable-fips-prf --disable-gmp \
--disable-pubkey --disable-pgp --disable-dnskey --disable-updown \
--disable-attr --disable-resolve --enable-openssl --enable-conftest \
--enable-gcm --enable-ccm --enable-ctr
The conftest utility is installed by default under /usr/local/libexec/ipsec/,
but can be invoked with the ipsec helper script. It takes a suite specific
configuration file after the --suite option and a test specific file with
the --test option:
ipsec conftest --suite suite.conf --test 1.1.1/test.conf
|