Annotation of embedaddon/strongswan/src/conftest/README, revision 1.1.1.1
1.1 misho 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 requires a certificate with the given OID policy
104: named_pool: Name of an IP pool defined e.g. in a database backend
105:
106: The following CHILD_SA specific configuration options are supported:
107:
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
112: given length
113: proposal: CHILD_SA proposal list, same syntax as IKE_SA proposal list
114:
115: 6. Credentials
116: --------------
117:
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.
123:
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
127: crl.
128:
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.
132:
133: certs {
134: trusted {
135: x509-a-ca = ca.pem
136: }
137: untrusted {
138: x509-me = /path/to/cert.pem
139: crl-from-ca = /path/to/crl.pem
140: }
141: }
142: keys {
143: ecdsa-me = /path/to/key.pem
144: }
145:
146: 7. Actions
147: ----------
148:
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):
152:
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
171:
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:
175:
176: actions {
177: initiate {
178: config = child-a1
179: }
180: rekey_ike-1 {
181: config = ike-a
182: delay = 3
183: }
184: rekey_ike-2 {
185: config = ike-a
186: delay = 6
187: }
188: }
189:
190: 8. Hooks
191: --------
192:
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.
196:
197: Currently, the following hooks are defined with the following options:
198:
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
205: string as hex string
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
230: payload.
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
290: string as hex string
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
299:
300: 9. Invoking
301: -----------
302:
303: Compile time options required depend on the test suite. A minimalistic
304: strongSwan build with the OpenSSL crypto backend can be configured with:
305:
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
312:
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
316: the --test option:
317:
318: ipsec conftest --suite suite.conf --test 1.1.1/test.conf
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to README CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / strongswan / src / conftest