path: root/src/conftest/README

             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 requries 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