Creating physical TCP servers

If you want to use TCP transports to facilitate communication between clients and servers, you must create physical TCP servers.

Before you begin

To configure a TCP transport to use ISO 8583 to packetize data streams, import an ISO 8583 schema into your project.
To configure SSL for a TCP transport, create an identity store in your project to store certificates.

Procedure

Open the Physical View of the Architecture School perspective.
On the toolbar of the Physical View, click General > TCP Server.
The TCP Server window is displayed.
Alternatively, open the Logical View, right-click a TCP connection, and click Set Binding in > Environment name > Create new TCP Server in the menu.
Optional: In the Name field, enter a name for the transport.
Tip: Assigning a name helps to identify the transport if there is more than one TCP transport in your project.

Click Settings, if necessary, to configure the basic settings of the transport. These settings are used to create the rule that defines which TCP traffic to record.

The basic settings are described in the following table:

Table 1. TCP Server window: Config tab, Settings tab
Hostname	The hostname or IP address of the computer that hosts the TCP server to which to connect.
Port	The port number to which to connect.

Optional: Click Client to configure proxy, socket, and Kerberos settings of the transport.

The Port Forwarding Proxy settings help you to specify a proxy through which HCL OneTest™ API will connect to the computer that hosts the TCP server. If no proxy is specified, the host name and port number that is specified on the Settings tab is used to connect to the computer that hosts the TCP server.

The Port Forwarding Proxy settings are described in the following table:

Table 2. TCP Server window: Config tab, Client tab, Port Forwarding Proxy settings
Hostname	The hostname or IP address of the proxy through which to connect to the computer that hosts the TCP server.
Port	The port number of the proxy through which to connect to the computer that hosts the TCP server.

The Socket Options settings helps you to specify socket settings for the transport.

The Socket Options settings are described in the following table:

Table 3. TCP Server window: Config tab, Client tab, Socket Options settings
Send 'keep alive' packets	Select this check box to enable the use of keep alive packets, which are used to maintain the stream connection where possible.
Enable Nagle's algorithm	Select this check box to reduce the number of packets that are sent by combining small messages.
Receive buffer size	The send and receive buffer sizes define the receive window. This window is the amount of receive data (in bytes) that can be buffered at one time on a TCP/IP socket connection. The optimal buffer size depends on network environment factors, such as acknowledgment timing, error rates, network topology, memory size, and data transfer size. HCL OneTest™ API uses a default receive buffer size. To specify a different receive buffer size, enter the value in the field provided. Tip: Any value that you enter is treated only as a hint to the socket and might be ignored.
Send buffer size	HCL OneTest™ API uses a default send buffer size. To specify a different send buffer size, enter the value in the field provided. Tip: Any value that you enter is treated only as a hint to the socket and it might be ignored.

The Kerberos settings helps you to configure Kerberos authentication for the transport.

The Kerberos settings are described in the following table:

Table 4. TCP Server window: Config tab, Client tab, Kerberos settings
Use Kerberos	Select this check box to enable Kerberos authentication for the transport. Selecting the check box makes available the other controls under Kerberos.
Principal	A Kerberos principal represents a unique identity in a Kerberos system to which Kerberos can assign tickets to access Kerberos-aware services. Enter the alias of the principal that to use for authentication.
Credential Type	Using the list that is provided, specify whether the identity of the principal will be provided in the form of a user name and password or in an external file. Tip: Clicking Username / Password makes the Username and Password fields available, and clicking External Config makes the Config Location field available.
Username	If you clicked Username / Password in the Credential Type list, enter the user name of the principal to use for authentication.
Password	If you clicked Username / Password in the Credential Type list, enter the password of the principal to use for authentication.
Config Location	If you clicked External Config in the Credential Type list, enter the path and file name of the file that contains identity details about the principal to use for authentication.
Anonymity	Kerberos provides a mechanism for principals to authenticate to a remote service without disclosing their identities. By default, this check box is selected. Clear this check box to disclose the principal's identity when data is sent and received.
Confidentiality	Kerberos optionally provides confidentiality for data that is sent between the client and server. By default, this check box is selected. Clear this check box if you do not want to use encryption when data is sent and received.
Integrity	Kerberos optionally provides integrity for data that is sent between the client and server. By default, this check box is selected. Clear this check box if you do not want to use checksum when data is sent and received.
Mutual Authentication	Kerberos optionally supports mutual authentication, which enables a client to validate the identity of a server. By default, this check box is selected. Clear this check box if you do not want to use mutual authentication when data is sent and received.
Replay Detection	Kerberos optionally supports replay attack detection. This facility prevents an eavesdropper from recording the messages that are sent by the client, establishing a new connection, and resending or replaying the same messages. By default, this check box is selected. Clear this check box to not use replay detection when data is sent and received.
Sequence Checking	Kerberos optionally supports sequence checking, which involves the use of sequence numbers to counter-replay attacks. By default, this check box is selected. Clear this check box to not use sequence numbers when data is sent and received.

Optional: Click Server to configure socket overrides and socket options. These settings configure the behavior of the transport when it is used in a stub.

The Socket Overrides settings help you to specify socket override settings for the port on the TCP server to which to connect.

The Socket Overrides settings are described in the following table:

Table 5. TCP Server window: Config tab, Server tab, Socket Overrides settings
Bind Address	You can enter a bind address. Important: If you do not enter a value in this field, the address that is specified in the HTTP Bind Address field in the Application page of Library Manager is used. If no address is specified in the HTTP Bind Address field in Library Manager, the transport binds to all local addresses on the computer that hosts the TCP server.
Port	You can enter a port number to override the port number that is specified in the Settings tab. Important: You might have to enter a port number in this field if the port number specified in the Port field in the Settings tab is being used by a different program or process on the physical TCP server. For more information, see Virtualizing TCP.

The Socket Options settings help you to specify options that will be set on an accepted socket.

For information about the Socket Options settings, refer to Table 3.

Select the Generate message on connection check box to generate a message with an empty body and a messageType of 100 in the header when a connection is accepted.

Select the Don't close connection when client closes its output stream (support half-closure) check box when you have a stub that expects to receive a single message on a connection and you want the client output stream to close to indicate that the complete message was sent. In this case, the transport must be configured with the All Available Bytes packetizer selected, the support half-closure option selected, and the Disconnect after send option selected (when editing the message Reply Header) to close the stub after sending a response.

When you select the support half-closure option:

A stub does not stop if the client closes its output stream; instead the stub is presented with any data that the packetizer did not forward and sends the data to the client. The stub closes its connection after it sends its final response.
If the All Available Bytes packetizer is in use, data is not presented as it is received but rather when the client closes its output stream.

Click Packetizer to configure the application layer settings of the transport.

In the Type list, click an option.

The Type list options are described in the following table:

Option Description

All Available Bytes

This option is the default, but use it only for initial investigation when the format of the data is unknown.

Important: The role of a packetizer for inbound data is to split the stream into meaningful messages. This packetizer treats all of the data available in a single read as the "meaningful message" to pass on. A single read can contain multiple messages or a partial message, which is why this packetizer is not suitable for regular use. For example, a message that contains 1124 bytes might be received as a packet of 1024 bytes followed by a packet of 100 bytes, and this packet might also contain the start of the next message.

Split

Click this option to use the packetizer settings to split the data stream into packets by using a delimiter that is configured by you.

Clicking this option displays the following controls on the Packetizer tab:

Select the Update outbound message with packet details below check box for the packetizer to add the selected delimiter to the end of any outbound messages.
Click Comma, Tab, Space, Semi-colon, or Other to select a delimiter type. If you click Other, you must enter the delimiter characters in the field provided.
Select the Process last empty packet check box if the data that is being read ends with your chosen delimiter and you must process one more packets as an empty string (""). Clear the Process last empty packet check box if the delimiter indicates that there are no more packets.
Select the Write token with last packet check box for the packetizer to write out the delimiter as the last character, thus ensuring that each record ends with a delimiter; for example, |Field_Value|. Clear the Write token with last packet check box if you do not want the delimiter as the last character; for example, |Field_Value.

Length

Click this option for the packetizer settings to be used to split length-based data according to a fixed length or a dynamic length that is encoded in the packet. For dynamic lengths, the position can be specified in relation to a known identifier or as a fixed offset from the start of the message.

Important: If you set a length of 0, the packetizer passes all data from a single read, which might not be a complete message. This behavior is the same as if you use All Available Bytes.

Clicking this option displays the following controls in the Packetizer tab:

Select the Update outbound message with packet details below check box for the packetizer to update the significant part of outbound messages based on the selected delimiter type.

Click Fixed Length, Token, Offset, or Prefix to select a delimiter type. The following table describes these options:

Table 7. Length delimiter types
Length delimiter type	Description
Fixed Length	Each packet is the same designated size. When the specified number of bytes is received from the socket, the bytes are passed to the subscriber. To test an input stream, set a fixed length of `0` to indicate that data is packetized in line with the physical packet size that is received from the underlying network.
Token	Indicates that the string of entered characters immediately precedes the length.
Offset	Length information is located immediately after the entered number of bytes.
Prefix	A number of bytes or characters at the start of the packet that denote the length of the packet.

Clicking Token, Offset, or Prefix makes available controls that help you to control how the actual packet length is read from the stream of information. The following table describes these controls:

Table 8. Packet controls
Control	Description
Size	The number of bytes that contain the length information.
Format	This list determines how values are treated. The options are as follows: Bytes: Values are treated as raw values. ASCII: Values are translated to their ASCII equivalent.
Swap Bytes	Select this check box for the packetizer to swap the order of the bytes before it treats the data as the length of the packet. Tip: Clicking ASCII in the Format list makes this check unavailable.
Length includes prefix	Select this check box if the length information includes the length of the length data.
Propagate prefix	The meaning of the option depends on whether the packetizer is decoding an incoming stream or updating an outgoing stream. For an incoming stream: When the option is selected, the prefix (length information and preceding bytes) from the incoming stream is propagated by the packetizer. When the option is cleared, only the bytes following the prefix are propagated. For outgoing data: When the option is selected, the packetizer assumes that data received before writing to the stream contains the prefix bytes. Tt updates the bytes representing the length according to the Length Includes Prefix setting. When the option is cleared, the packetizer generates a prefix according to the settings and updates the bytes representing the length. For a comparison of how the length delimiter type, Length includes prefix option, and Propagate prefix option interact, see Example.

Delimited

Click this option for the packetizer settings to be used to extract data that is designated by a start token and an end token.

Clicking this option displays the following controls in the Packetizer tab:

Select the Update outbound message with packet details below check box for the packetizer to update outbound messages with the relevant packet information.
In the Start Token field, enter a series of characters that denotes the start of a record.
In the End Token field, enter a series of characters that denotes the end of a record.

Start and end tokens can accept representations of certain non-printable characters. The following table lists these characters:

Table 9. Non-printable characters that can be entered in Start Token and End Token fields
Esc character	Definition	Unicode character
\b	Backspace character	\u008
\t	Tab character	\u009
\n	Newline character	\u00A
\f	Form feed	\u00C
\r	Carriage return	\u00D
\0	Null	\u000
\xHH	Two-character Hex value; for example, \x02 (STX)	\u002

ISO 8583

Click this option for the packetizer to break up the data stream into an ISO 8583 message based on the ISO 8583 schema that is selected by you.

Clicking this option displays the following controls in the Packetizer tab:

Select the Update outbound message with packet details below check box if you for the packetizer to update outbound messages with the relevant packet information.
In the Select the ISO 8583 Schema list, click an ISO 8583 schema in your project.
Restriction: Versions of HCL OneTest™ API earlier than 8.5.1.1 do not support ISO 8583.

SWIFT

Click this option for the packetizer settings to be used to break up the data stream into a SWIFT message that is based on simple SWIFT rules.

Clicking this option displays only the Update outbound message with packet details below check box on the Packetizer tab.

Select the Update outbound message with packet details below check box for the packetizer to update outbound messages with the relevant packet information.

Token

Click this option to use the packetizer settings to extract data that is designated by a start token and an end token and to extract more bytes of data after the end token.

Clicking this option displays the following controls on the Packetizer tab:

Select the Update outbound message with packet details below check box for the packetizer to update outbound messages with the relevant packet information.
In the Start Token field, enter a series of characters that denotes the start of a record.
In the End Token field, enter a series of characters that denotes the end of a record.
Optional: In the End Token Data Length field, enter the number of bytes that is present immediately following the end token; for example, these bytes might contain a checksum.

Tip: Start and end tokens can accept representations of certain non-printable characters. For information about the use of non-printable characters, refer to Table 9.

Click SSL to configure the SSL settings of the transport.

Click SSL to configure the secure socket layer (SSL) settings for the transport. The SSL settings are described in the following table:

Field

Description

Use SSL

Select this check box to enable security for the transport.

Selecting the check box makes the other controls on the SSL tab available. You can enable security for Testing (Client) or Virtualization (Server) or both.

Server certificates to trust

All available identity stores are displayed in the drop-down list. Select one of the following menu items:


Field	Description
Trust All	To accept any certificate presented by the server, regardless of its validity. This option is the default and assumes you are focused on testing an application rather than the security of the server.
New	To define a new identity store.
`Identity store`	To specify an identity store, that contains certificates that the client is to trust.

Client identities to give to the server

All available identity stores are displayed in the drop-down list. If you use mutual authentication, a suitable identity is selected from the chosen identity store. Select one of the following menu items:


Field	Description
None	If the server does not request an identity.
New	To define a new identity store.
`Identity store`	To use an existing identity store. Specify an alias in the Identity field.

Certificate source

All available identity stores are displayed in the drop-down list. You can select one of the following menu items:


Field	Description
Generated	To use a certificate that HCL OneTest™ API generates for you. The source for that certificate is displayed in the Signed by field.
New	To define a new identity store.
`Identity store`	To use a certificate from an identity store.

Signed by

If you chose Generated in the Certificate source field, this field holds the location of a certificate within the HCL OneTest™ API installation directory that is used to generate the new certificate. This is a read-only field.

Identity

If you specified an identity store in the Certificate source field, use this field to specify the alias of a key in that identity store.

Certificate Authorities a stub will trust

All available identity stores are displayed in the drop-down list. You can select one of the following menu items:


Field	Description
Trust All	To accept any certificate presented by the client.
New	To define a new identity store.
`Identity store`	To specify an identity store that contains certificates that the stub is to trust.

Override default protocols

If you are required to use a specific version of the secure sockets protocol, such as SSLv2 or TLSv1.2, enter that algorithm name here.

Optional: Click Recording to configure the recording settings of the transport.

Table 10. Fields for the Recording page
Field	Description
Recording mode	The following options are available: Packet Capture Requires packet capture software. On Windows™ systems, Network Packet Capture is included in the installation program of HCL OneTest™ API. On non-Windows™ systems, libpcap is typically installed by default. If necessary, you can download the latest package from http://www.tcpdump.org/. For more information about packet capture, refer to Limitations of packet capture in Related reference. External Proxy Server The proxies in HCL® Quality Server are used by HCL OneTest™ API and HCL OneTest™ Virtualization to record all HTTP(S) traffic that is routed through the proxy. For more information, refer to HTTP/TCP proxy setup in Related concepts. Envoy Proxy (Experimental) The proxies in HCL® Quality Server are used by HCL OneTest™ API and HCL OneTest™ Virtualization to record all HTTP(S) traffic that is routed through the Envoy Proxy (Experimental). You must provide the config id that you configured in the admin_config of the Envoy Proxy. Istio Select this option if you are recording the HTTP(S) traffic that is routed through the Istio services port in any Kubernetes cluster.

Tip: You can configure the default option that is displayed in the Recording Mode list in the Recording tab. To change the default option that is displayed, complete the following tasks:

Open the Preferences window by clicking Project > Preferences in the menu bar. Alternatively, click Window > Preferences in the menu bar.
Click Recording.
Under Transport Specific Recording, click an option in the Default Method for IP based list.
Click Apply.
Click OK.

Click Test Transport to verify that the connection works.
Click OK.

Results

The new physical TCP server resource is added to your project.

Example

The following tables show the interaction of the length delimiter type, Length includes prefix option, and Propagate prefix option. For Fixed Length delimiter type, the packetizer makes no changes in the data from the stream.

Example 1:

Incoming stream
Offset delimiter type
Offset=4
Size=2

Table 11. Length packetizer example 1
Length includes prefix	Propagate prefix	Incoming stream	Data received
false	false	abcd05Hello	Hello
false	true	abcd05Hello	abcd05Hello
true	false	abcd11Hello	Hello
true	true	abcd11Hello	abcd11Hello

Example 2:

Incoming stream
Token delimiter type
Token=len
Size=2

Table 12. Length packetizer example 2
Length includes prefix	Propagate prefix	Incoming stream	Data received
false	false	len=05Hello	Hello
false	true	token1=`xxx`len=05Hello	token1=`xxx`len=05Hello
true	false	len=11Hello	Hello
true	true	token1=`xxx`len=21Hello	token1=`xxx`len=21Hello

Example 3:

Incoming stream
Prefix delimiter type
Size=2

Table 13. Length packetizer example 3
Length includes prefix	Propagate prefix	Incoming stream	Data received
false	false	05Hello	Hello
false	true	05Hello	05Hello
true	false	11Hello	Hello
true	true	11Hello	11Hello

Example 4:

Outgoing data
Offset delimiter type
Offset=4
Size=2

Table 14. Length packetizer example 4
Length includes prefix	Propagate prefix	Data in stream	Outbound message
false	false	Hello	\0\0\0\005Hello
false	true	abcd00Hello	abcd05Hello
true	false	Hello	\0\0\0\005Hello
true	true	abcd00Hello	abcd11Hello

Example 5:

Outgoing data
Token delimiter type
Token=len
Size=2

Table 15. Length packetizer example 5
Length includes prefix	Propagate prefix	Data in stream	Outbound message
false	false	Hello	len=05Hello
false	true	token1=`xxx`len=00Hello	token1=`xxx`len=05Hello
true	false	Hello	len=11Hello
true	true	token1=`xxx`len=00Hello	token1=`xxx`len=21Hello

Example 6:

Outgoing data
Prefix delimiter type
Size=2

Table 16. Length packetizer example 6
Length includes prefix	Propagate prefix	Data in stream	Outbound message
false	false	Hello	05Hello
false	true	00Hello	05Hello
true	false	Hello	11Hello
true	true	00Hello	11Hello