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