Add missing CHILD_SA specific proposal keyword in conftest README
[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 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.
55
56 4. Logging
57 ----------
58
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
65 section.
66
67 5. Connections
68 --------------
69
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:
73
74 configs {
75     ike-a {
76         # ... ike options
77         child-a1 {
78             # ... child options
79         }
80         child-a2 {
81             # ...
82         }
83     }
84 }
85
86 Configuration names can be chosen arbitrary, but should be unique within the
87 same file.
88
89 The IKE_SA configuration uses the following options (as key/value pairs):
90
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
100                   scenario
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 requries a certificate with the given OID policy
104
105 The following CHILD_SA specific configuration options are supported:
106
107   lts:         Local side traffic selectors, comma separated CIDR subnets
108   rts:         Remote side traffic selectors, comma separated CIDR subnets
109   transport:   Propose IPsec transport mode instead of tunnel mode
110   tfc_padding: Inject Traffic Flow Confidentialty bytes to align packets to the
111                given length
112   proposal:    CHILD_SA proposal list, same syntax as IKE_SA proposal list
113
114 6. Credentials
115 --------------
116
117 Credentials may be defined globally in the suite or locally in the test specific
118 configuration file. Certificates files are defined in the certs section, either
119 in the trusted or in the untrusted section. Trusted certificates are trust
120 anchors, usually root CA certificates. Untrusted certificates do not build a
121 trust anchor and usually contain intermediate or end entity certificates.
122
123 Certificates files are loaded relative to the configuration file path and may
124 be encoded either in plain ASN.1 DER or in PEM format. The prefix of the
125 key/value pair is used to specify the type of the certificate, usually x509 or
126 crl.
127
128 Private keys can be defined in the suite or test config file under the keys
129 section. The prefix of the key/value pair must be either rsa or ecdsa, the
130 specified file may be encoded in ASN.1 DER or unencrypted PEM.
131
132 certs {
133     trusted {
134         x509-a-ca = ca.pem
135     }
136     untrusted {
137         x509-me = /path/to/cert.pem
138         crl-from-ca = /path/to/crl.pem
139     }
140 }
141 keys {
142     ecdsa-me = /path/to/key.pem
143 }
144
145 7. Actions
146 ----------
147
148 The actions section in the test specific configuration file defines
149 the IKEv2 protocol actions to trigger. Currently, the following actions
150 are supported and take these arguments (as key/value pairs):
151
152   initiate:    Initiate an IKE- and CHILD_SA
153                config: name of the CHILD_SA configuration to initiate
154                delay: Delay to trigger action after startup
155   rekey_ike:   Rekey an IKE_SA
156                config: name of originating IKE_SA configuration
157                delay: Delay to trigger action after startup
158   rekey_child: Rekey an CHILD_SA
159                config: name of originating CHILD_SA configuration
160                delay: Delay to trigger action after startup
161   liveness:    Do a liveness check (DPD) on the IKE_SA
162                config: name of originating IKE_SA configuration
163                delay: Delay to trigger action after startup
164   close_ike:   Close an IKE_SA
165                config: name of originating IKE_SA configuration
166                delay: Delay to trigger action after startup
167   close_child: Close a CHILD_SA
168                config: name of originating IKE_SA configuration
169                delay: Delay to trigger action after startup
170
171 To trigger the same action multiple times, the action sections must be named
172 uniquely. Append an arbitrary string to the action name. The following example
173 initiates a connection and rekeys it twice:
174
175 actions {
176     initiate {
177         config = child-a1
178     }
179     rekey_ike-1 {
180         config = ike-a
181         delay = 3
182     }
183     rekey_ike-2 {
184         config = ike-a
185         delay = 6
186     }
187 }
188
189 8. Hooks
190 --------
191
192 The hooks section section in the test configuration defines different hooks
193 to use to mangle packets or trigger other protocol modifications. These
194 hook functions are implemented in the hooks folder of conftest.
195
196 Currently, the following hooks are defined with the following options:
197
198   add_notify:         Add a notify to a message
199     request:          yes to include in request, no in response
200     id:               IKEv2 message identifier of message to add notify
201     type:             notify type to add, names defined in notify_type_names
202                       under src/libcharon/encoding/payloads/notify_payload.c
203     data:             notification data to add, prepend 0x to interpret the
204                       string as hex string
205     spi:              SPI to use in notify
206     esp:              yes to send an ESP protocol notify, no for IKE
207   add_payload:        Add an arbitrary payload to a message
208     request:          yes to include in request, no in response
209     id:               IKEv2 message identifier of message to add payload
210     type:             type of the payload to add, names defined in
211                       payload_type_short_names in payload.c
212     data:             data to append after generic payload header, use 0x
213                       prefix for hex encoded data
214     critical:         yes to set payload critical bit
215     replace:          yes to replace an existing payload of the same type
216   custom_proposal:    set a custom proposal value in the SA payload
217     request:          yes to include in request, no in response
218     id:               IKEv2 message identifier of message to add notify
219                       The hook takes subsections with numerical names, each
220                       defining a proposal substructure. The substructure
221                       takes key/value pairs, where key defines the type, value
222                       the specific algorithm.
223   force_cookie:       Reject IKE_SA_INIT requests with a COOKIE
224   ignore_message:     Ignore a specific message, simulating packet loss
225     inbound:          yes to ignore incoming, no for outgoing messages
226     request:          yes to ignore requests, no for responses
227     id:               IKEv2 message identifier of message to ignore
228   ike_auth_fill:      Fill up IKE_AUTH message to a given size using a CERT
229                       payload.
230     request:          yes to fill requests messages, no for responses
231     id:               IKEv2 message identifier of message to fill up
232     bytes:            number of bytes the final IKE_AUTH message should have
233   log_id:             Comfortably log received ID payload contents
234   log_ke:             Comfortably log received KE payload DH groups
235   log_proposal:       Comfortably log all proposals received in SA payloads
236   log_ts:             Comfortably log all received TS payloads
237   pretend_auth:       magically reconstruct IKE_AUTH response even if
238                       AUTHENTICATION_FAILED received
239   rebuild_auth:       rebuild AUTH payload, i.e. if ID payload changed
240   reset_seq:          Reset sequence numbers of an ESP SA
241     delay:            Seconds to delay reset after SA established
242   set_critical:       Set critical bit on existing payloads:
243     request:          yes to set in request, no in response
244     id:               IKEv2 message identifier of message to mangle payloads
245     payloads:         space separated payload list to set critical bit on
246   set_ike_initiator:  toggle IKE initiator flag in IKE header
247     request:          yes to set in request, no in response
248     id:               IKEv2 message identifier of message to mangle
249   set_ike_request:    toggle IKE request flag in IKE header
250     request:          yes to set in request, no in response
251     id:               IKEv2 message identifier of message to mangle
252   set_ike_spi:        set the IKE SPIs in IKE header
253     request:          yes to set in request, no in response
254     id:               IKEv2 message identifier of message to mangle
255     spii:             initiator SPI to set (as decimal integer)
256     spir:             responder SPI to set
257   set_ike_version:    set version fields in IKE header
258     request:          yes to set in request, no in response
259     id:               IKEv2 message identifier of message to mangle
260     major:            major version to set
261     minor:            minor version to set
262     higher:           yes to set Higher Version Supported flag
263   set_length:         set the length in a payload header
264     request:          yes to set in request, no in response
265     id:               IKEv2 message identifier of message to mangle
266     type:             payload type to mangle
267     diff:             difference to add/remove from real length (+1,-3 etc.)
268   set_proposal_number:Change the number of a proposal in a SA payload
269     request:          yes to set in request, no in response
270     id:               IKEv2 message identifier of message to mangle
271     from:             proposal number to mangle
272     to:               new porposal number to set instead of from
273   set_reserved:       set arbitrary reserved bits/bytes in payloads
274     request:          yes to set in request, no in response
275     id:               IKEv2 message identifier of message to mangle
276                       The hook takes a list of subsection, each named as payload
277                       type. Each section takes a bits and a bytes key, the
278                       value is a comma separated list of decimal numbers of
279                       bits/bytes to mangle (1 is the first reserved bit/byte
280                       in the payload). The byteval key defines to which value
281                       set mangled bytes in the byte list.
282   unencrypted_notify: Send an unencrypted message with a notify after
283                       establishing an IKE_SA
284     id:               IKEv2 message identifier of message to send
285     type:             notify type to add, names defined in notify_type_names
286                       under src/libcharon/encoding/payloads/notify_payload.c
287     data:             notification data to add, prepend 0x to interpret the
288                       string as hex string
289     spi:              SPI to use in notify
290     esp:              yes to send an ESP protocol notify, no for IKE
291   unsort_message:     reorder the payloads in a message
292     request:          yes to reorder requests messages, no for responses
293     id:               IKEv2 message identifier of message to reorder
294     order:            payload order, space separated payload names as defined
295                       in payload_type_short_names under
296                       src/libcharon/encoding/payloads/payload.c
297
298 9. Invoking
299 -----------
300
301 Compile time options required depend on the test suite. A minimalistic
302 strongSwan build with the OpenSSL crypto backend can be configured with:
303
304 ./configure --sysconfdir=/etc --disable-pluto --disable-scripts \
305   --disable-tools --disable-aes --disable-des --disable-md5 \
306   --disable-sha1 --disable-sha2 --disable-fips-prf --disable-gmp \
307   --disable-pubkey --disable-pgp --disable-dnskey --disable-updown \
308   --disable-attr --disable-resolve --enable-openssl --enable-conftest \
309   --enable-gcm --enable-ccm --enable-ctr
310
311 The conftest utility is installed by default under /usr/local/libexec/ipsec/,
312 but can be invoked with the ipsec helper script. It takes a suite specific
313 configuration file after the --suite option and a test specific file with
314 the --test option:
315
316   ipsec conftest --suite suite.conf --test 1.1.1/test.conf