| 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 Confidentiality 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 proposal 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 |