TCP Probe¶

Send/receive TCP payloads.

Identification and Properties¶

Probe Type ID: tcp

Properties:

Name	Type	Default value	Description
`local_ip`	string	(empty - system assigned)	Local IP address to use when sending packets
`local_port`	integer	`0` (system assigned)	Local port to use when sending packets
`listening_ip`	string	`0.0.0.0`	Listening IP address, if listening mode is activated (see below)
`listening_port`	integer	`0`	Set it to a non-zero port to start listening on mapping
`size`	integer	`0`	Fixed-size packet strategy: if set to non-zero, only raises messages when `size` bytes have been received. All raised messages will hage this constant size.
`separator`	string	`None`	Separator-based packet strategy: if set to a character or a string, only raises messages when `separator` has been encountered; this separator is assumed to be a packet separator, and is not included in the raised message. May be useful for, for instance, x00-based packet protocols.
`enable_notifications`	boolean	`False`	If set, you may get connection/disconnection notification and connectionConfirm/Error notification messages
`default_sut_address`	string (ip:port)	`None`	If set, used as a default SUT address if none provided by the user
`default_decoder`	string	`None`	If set, must be a valid codec name (aliases are currently not supported). This codec is then used to decode all incoming packets, and only the probe only raises an incoming message when the codec successfully decoded something. This is particular convenient when used with an incremental codec (such as `'http.request'`) that will then be responsible for identifying the actual application PDU in the TCP stream.
`default_encoder`	string	`None`	If set, must be a valid codec name (aliases are currently not supported). This codec is then used to encode all outgoing packets, without a need to use it when sending the message through the port mapped to this probe.
`use_ssl`	boolean	`False`	If set, all outgoing and incoming traffic through is probe is transported over SSLv3. All TLS negotiations are performed by the probe. However, ...
`ssl_key`	string	`None`	The SSL key to use if `use_ssl` is set to `True`. Contains a private key associated to `ssl_certificate`, in base64 format. If not provided, a default sample private key is used.
`ssl_certificate`	string	`None`	The SSL certificate to use if `use_ssl` is set to `True`. Contains a certificate in PEM format that will be used when a certificate is needed by the probe connection(s). If not provided, a default one that matches the default private key, is used.
`connection_timeout`	float	`5.0`	The connection timeout, in s, when trying to connect to a remote party.
`auto_connect`	boolean	`True`	When sending a message, autoconnect to the provided address if there is no existing connections with this peer yet.
`ssl_require_client_cert_ca`	string	`None`	When `use_ssl` is set to `True` and the probe is used on server side (`listening_port` > 0), request the SSL client to provide a client-side certificate issued by one of the CA whose certificate is provided as base64 in this property. This enables to test mutual SSL authentication.
`auto_connect`	boolean	`True`	When sending a message, autoconnect to the provided address if there is no existing connections with this peer yet.

Overview¶

This is a general purpose probe to transport anything over TCP, with basic control on connections/disconnections (you can get optional incoming connection notifications or outgoing connection confirmations, or simply focus on payload exchanges), and a basic support for SSL (v3).

Such a probe may be used as a base to test any protocol transported over TCP.

Combined with the http.request and http.response codecs, this is enough to test anything based on HTTP/HTTPS. You may also use the diameter or sua codec, actually any codec that comes with an incremental decoding implementation. You just have to define such a codec as the default_decoder property (used to decode incoming stream) or the default_encoder property (used to encode outgoing messages).

ADPU Identification¶

The probe first waits for size bytes (if the size property is set) or (exclusively) for the separator character(s) (is the separator property is set). If none of those properties are set, the probe only considers what it read in the stream (which is system-dependent).

Then, the default decoder, if set, tries to decode this first raw segment. If it needs more input, it waits for the next raw segment. If multiple APDUs are detected, multiple incoming messages are raised. If undecodable data is detected, the raw segment is ignored.

If no decoder is set, the raw segment is raised as raw data.

Basic SSL Support¶

When the property use_ssl is set to True, the probe automatically performs SSL negotiations after a TCP connection (probe as a client) or when accepting a new incoming connection (as a server).

If enable_notifications is True, the connectionConfirm message will contain the server’s certificate in DER format. The connectionNotification message is planned to contain the client’s certificate as well, but it is currently not possible to force the (server side) probe to request it.

In addition, received certificates are not validated, and hostnames are not verified.

This probe offers very little control on these negotiations and is not meant to test SSL-level stuff (for instance, how a SUT implemented SSL itself). This support is provided as a convenience to interact with a SUT through higher-level protocols that have been ported over SSL (HTTP, SIP, ...).

When using this probe as a server in SSL mode, if you don’t provide the ssl_key and ssl_certificate parameters, a default pair is used. The default certificate is:

Availability¶

All platforms. However, SSL support depends on the Python SSL module, provided by default with Python 2.6 and later on Unix platforms.

Dependencies¶

None.

TTCN-3 Types Equivalence¶

The test system interface port bound to such a probe complies with the TransportProbePortType port type as specified below:

type union NotificationType
{
  record { octetstring certificate optional } connectionNotification, // new incoming connection established
  charstring disconnectionNotification, // contains a human readable reason to the disconnection
  record { octetstring certificate optional } connectionConfirm, // connection request OK
  charstring connectionError, // contains a human readable error after a connection request
}

type union RequestType
{
  any connectionRequest, // request a new tcp-connection
  any disconnectionRequest, // request a disconnection. Except a disconnectionNotification later
}

type TransportProbePortType
{
  in RequestType;
  out NotificationType;
  in, out octetstring;
  out any; // if the default_decoder is used, the raised structure is the decoder's output
  in any; // if the default_encoder is used
}