Annotation of embedaddon/strongswan/src/conftest/README, revision 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