Updated conftest README
authorMartin Willi <martin@revosec.ch>
Wed, 22 Dec 2010 17:00:11 +0000 (18:00 +0100)
committerMartin Willi <martin@revosec.ch>
Wed, 5 Jan 2011 15:46:06 +0000 (16:46 +0100)
src/conftest/README

index 582c633..e215692 100644 (file)
@@ -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.
 
 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
 --------------
 
 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):
 
 
 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:
 
 
 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
 --------------
 
 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
 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
 
 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 {
 specified file may be encoded in ASN.1 DER or unencrypted PEM.
 
 certs {
     trusted {
-        x509 = ca.pem
+        x509-a-ca = ca.pem
     }
     untrusted {
     }
     untrusted {
-        x509 = /path/to/cert.pem
+        x509-me = /path/to/cert.pem
+        crl-from-ca = /path/to/crl.pem
     }
 }
 keys {
     }
 }
 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
 ----------
 
 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
 --------
 
 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:
 
 
 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
   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
                       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
   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
     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 \
 -----------
 
 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 \
   --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 \