319 lines
14 KiB
Plaintext
319 lines
14 KiB
Plaintext
|
|
|
|
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
|