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 .
The TCP Server window is displayed.
Alternatively, open the Logical View, right-click a TCP connection, and click
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 host name 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 host name 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
of100
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:Table 6. TCP Server window: Config tab, Packetizer tab, Type list options 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.
- Istio via HCL OneTest™ Server
- Select this option if you are recording the HTTP(S) traffic that is routed through the Istio services port in the Kubernetes cluster that hosts HCL OneTest™ Server.
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 in the menu bar. Alternatively, click 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.
- Incoming stream
- Offset delimiter type
- Offset=4
- Size=2
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 |
- Incoming stream
- Token delimiter type
- Token=len
- Size=2
Length includes prefix | Propagate prefix | Incoming stream | Data received |
---|---|---|---|
false | false | len=05Hello | Hello |
false | true | token1=xxxlen=05Hello | token1=xxxlen=05Hello |
true | false | len=11Hello | Hello |
true | true | token1=xxxlen=21Hello | token1=xxxlen=21Hello |
- Incoming stream
- Prefix delimiter type
- Size=2
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 |
- Outgoing data
- Offset delimiter type
- Offset=4
- Size=2
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 |
- Outgoing data
- Token delimiter type
- Token=len
- Size=2
Length includes prefix | Propagate prefix | Data in stream | Outbound message |
---|---|---|---|
false | false | Hello | len=05Hello |
false | true | token1=xxxlen=00Hello | token1=xxxlen=05Hello |
true | false | Hello | len=11Hello |
true | true | token1=xxxlen=00Hello | token1=xxxlen=21Hello |
- Outgoing data
- Prefix delimiter type
- Size=2
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 |