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

  1. Open the Physical View of the Architecture School perspective.
  2. 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.

  3. 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.
  4. 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.

  5. 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.

  6. 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.
  7. 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.
  8. 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.
  9. 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:
    1. Open the Preferences window by clicking Project > Preferences in the menu bar. Alternatively, click Window > Preferences in the menu bar.
    2. Click Recording.
    3. Under Transport Specific Recording, click an option in the Default Method for IP based list.
    4. Click Apply.
    5. Click OK.
  10. Click Test Transport to verify that the connection works.
  11. 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=xxxlen=05Hello token1=xxxlen=05Hello
true false len=11Hello Hello
true true token1=xxxlen=21Hello token1=xxxlen=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=xxxlen=00Hello token1=xxxlen=05Hello
true false Hello len=11Hello
true true token1=xxxlen=00Hello token1=xxxlen=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