Updated conftest README

1 files changed, 122 insertions, 31 deletions

diff --git a/src/conftest/README b/src/conftest/README
index 582c63355..e2156921f 100644
--- a/src/conftest/README
+++ b/src/conftest/README
@@ -49,7 +49,22 @@ 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.
 
-4. Connections
+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
@@ -73,21 +88,29 @@ 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
+  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
 
 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
+  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
 
-5. Credentials
+6. Credentials
 --------------
 
 Credentials may be defined globally in the suite or locally in the test specific
@@ -97,26 +120,28 @@ 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 name of the key/value
-pair is used to specify the type of the certificate, usually x509.
+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 name of the key/value pair must be either rsa or ecdsa, the
+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 = ca.pem
+        x509-a-ca = ca.pem
     }
     untrusted {
-        x509 = /path/to/cert.pem
+        x509-me = /path/to/cert.pem
+        crl-from-ca = /path/to/crl.pem
     }
 }
 keys {
-    ecdsa = /path/to/key.pem
+    ecdsa-me = /path/to/key.pem
 }
 
-6. Actions
+7. Actions
 ----------
 
 The actions section in the test specific configuration file defines
@@ -160,7 +185,7 @@ actions {
     }
 }
 
-7. Hooks
+8. Hooks
 --------
 
 The hooks section section in the test configuration defines different hooks
@@ -169,10 +194,6 @@ hook functions are implemented in the hooks folder of conftest.
 
 Currently, the following hooks are defined with the following options:
 
-  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
   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
@@ -182,6 +203,81 @@ Currently, the following hooks are defined with the following options:
                       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
+  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
@@ -197,20 +293,15 @@ Currently, the following hooks are defined with the following options:
     order:            payload order, space separated payload names as defined
                       in payload_type_short_names under
                       src/libcharon/encoding/payloads/payload.c
-  ike_auth_fill:      Fill up IKE_AUTH message to a given size using CERT
-                      a 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
 
-8. Invoking
+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-tools --disable-stroke --disable-aes --disable-des --disable-md5 \
+  --disable-tools --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 \