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