-

TLS_SOCKET

Note
For this function block, a new implementation is available which requires firmware version 2021.3 or newer. The new FB combines the handling of TCP and TLS communication. Furthermore, it supports that one TCP/TLS server can communicate with several clients. Refer to the topic "TLS_SOCKET_2" for details.

TypeFunction block
DescriptionThe function block opens and closes a TLS socket which is used for secure IP communication between a server and a client via Transport Layer Security (TLS).

The TLS socket is represented by the HANDLE output parameter. This handle has to be forwarded to the function blocks TLS_SEND and TLS_RECEIVE, which require the socket handle for the secure data exchange with a communication partner.

With a rising edge at the ACTIVATE input, the system starts to open a socket. Once the socket has been opened and the connection has been established successfully, the ACTIVE output is set to TRUE. Only while ACTIVE = TRUE, the socket handle provided at the HANDLE output can be used for subsequent calls of the TLS_SEND/TLS_RECEIVE function blocks.
A falling edge at ACTIVATE closes the socket. The connection is terminated in the form of a three-way handshake, i.e. three telegrams are exchanged between client and server. During the termination process a new rising edge results in a function block error.

The START_TLS input defines whether the TLS_SEND/TLS_RECEIVE function blocks send and receive data via a pure TCP connection or via a TLS connection. In the typical use case of the TLS_SOCKET FB, the START_TLS input is TRUE when the ACTIVATE input becomes TRUE. In rare situations as for SMTP, the START_TLS input gets a rising edge while ACTIVATE is TRUE. If START_TLS = FALSE once the connection is established, the TLS_SEND/TLS_RECEIVE function blocks use a TCP connection to send and receive data. The SEND_SECURE/RECEIVE_SECURE inputs of the function blocks must be consistent to the value of START_TLS. With a rising edge at START_TLS when the connection is established, the TLS protocol is initialized, i.e., the existing TCP connection is upgraded to a TLS connection. As long as START_TLS = TRUE, data are sent and received via a TLS-secured connection. For initialization of the TLS protocol, the data applied at the CONNECT_INFO input when activating the function block are used. The predefined structure at the CONNECT_INFO input holds, among others, the client and server certificates contained in the trust store and identity store of the devices used for authentication (see below for a description of the CONNECT_INFO values and how to manage and link the certificates in the web-based management (WBM) of the controller).

While ACTIVE = FALSE, calling the TLS_SEND/TLS_RECEIVE function blocks with the socket handle causes an error at the function blocks. The socket is kept open as long as the ACTIVATE input is TRUE. The BUSY output is set to TRUE while ACTIVATE is TRUE and the socket is still not open. If the ACTIVATE input switches to FALSE, the socket is closed and the ACTIVE output is set to FALSE (see also the notes below). If the connection is lost, the function block tries to re-establish the connection as long as ACTIVATE = TRUE.

The IS_SRV input defines whether the function block implements server or client functionality.

  • With IS_SRV = TRUE, the function block creates a listening (server) socket. The socket can be bound to the specified local Ethernet adapter (BIND_IP input) and the port (BIND_PORT input) and waits for incoming requests from remote clients. If necessary the accepted clients can be limited by specifying the DEST_IP/DEST_PORT inputs. With opened (server) socket, only 1:1 connections are possible, i.e., the listening socket can accept only one incoming TLS connection.
  • With IS_SRV = FALSE, a client socket is created. In case of a client socket, the DEST_IP/DEST_PORT inputs are used to specify the IP address and IP port of the server to communicate with.

WARNING
Unintended machine operation
Verify that the influence of the output data cannot result in an unintended or hazardous behavior of the entire system.

Notes
  • The function blocks for TLS communication are processed asynchronously. This means, the function blocks issue commands and wait for their processing.
  • The TLS socket handle created by the function block is not compatible with the TCP socket handle created by the TCP_SOCKET function block. The TLS socket handle can only be used with the TLS_SEND/TLS_RECEIVE function blocks and the TCP socket only with the TCP_SEND/TCP_RECEIVE function blocks.
  • The number of TLS sockets that are currently opened is indicated by the system variable TLS_ACTIVE_SOCKETS (contained in the Data List of the controller node and 'PLC' node in the PLANT).
  • In case of a warm start or cold start or a controller reset, the firmware closes all sockets that have been opened with the corresponding instance of the TLS_SOCKET instance.
  • For controllers with integrated firewall, make sure that the firewall does not block the ports involved in the communication. Otherwise, the connection cannot be established.
  • All IP addresses used are IPv4 addresses that consist of four numbers (0 to 255) separated by dot.
  • Function blocks have to be instantiated.
    The instance name of the function block has to be declared in the 'Variables' table of the POU where the FB is going to be used. The instance name must be unique within the POU.
ParametersInputs

ACTIVATE

IS_SRV

BIND_IP

BIND_PORT

DEST_IP

DEST_PORT

CONNECT_INFO

START_TLS

Outputs

HANDLE

ACTIVE

BUSY

ERROR

STATUS

USED_PORT
Additional informationManaging and linking certificates of TrustStores and IdentityStores