TLS_SOCKET_2

Type	Function block
Description	The function block opens and closes a TCP/TLS socket. (The TLS protocol works on top of TCP). This socket can be used either for standard TCP communication or for secure IP communication between a server and a client via Transport Layer Security (TLS). The TCP/TLS socket is represented by the HANDLE output parameter. This handle has to be forwarded to the function blocks TLS_SEND_2 and TLS_RECEIVE_2, which require the socket handle for the (secure) data exchange with a communication partner. When implementing a TCP/TLS server that is able to communicate with several TCP/TLS clients, one TLS_SOCKET_2 instance (with IS_SRV = TRUE) must be created for each client to be connected. In this scenario, the clients connect to the respective TLS_SOCKET_2 instance/HANDLE as specified by the DEST_IP/DEST_PORT. With a rising edge at the ACTIVATE input, the system starts to open the TCP/TLS 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_2/TLS_RECEIVE_2 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. While ACTIVE = FALSE, calling the TLS_SEND_2/TLS_RECEIVE_2 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. TLS on top of TCP The START_TLS input defines whether the TLS_SEND_2/TLS_RECEIVE_2 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_2 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_2/TLS_RECEIVE_2 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 the 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). Client or server functionality? 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. When implementing a TCP/TLS server that is able to communicate with several TCP/TLS clients, one dedicated instance of TLS_SOCKET_2 has to be used for each expected client. 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 TCP/TLS communication are processed asynchronously. This means, the function blocks issue commands and wait for their processing. The socket handle created by the TLS_SOCKET_2 function block is not compatible with the socket handle created by the TCP_SOCKET or TLS_SOCKET function block. The TCP/TLS socket handle can only be used with the TLS_SEND_2/TLS_RECEIVE_2 function blocks. The number of sockets that are currently opened is indicated by the system variable TLS_ACTIVE_SOCKETS (contained in the Data List of the controller node and 'IEC 61131-3' 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_2 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.
Parameters	Inputs Note The inputs specifically relevant for setting up the TLS communication on top of the TCP communication are CONNECT_INFO and START_TLS. The other inputs specify TCP functionality. ACTIVATE Data type: BOOL Description: The function block starts opening a TCP/TLS socket when a rising edge is detected at the input. The socket is kept open as long as the ACTIVATE input is TRUE. A falling edge triggers the closing of the socket. If the communication partner closes the connection while the ACTIVATE input remains TRUE, then the FB will attempt to establish a new connection. As closing the socket takes some time (three-way handshake between client and server), the next rising edge should be applied to ACTIVATE only after the outputs ACTIVE and BUSY are both FALSE. Otherwise, i.e., if a new connection is requested while the previous socket termination is not yet completed, an error occurs and the error code 16#C205 is shown at the STATUS output. IS_SRV Data type: BOOL Description: Defines whether the function block implements server or client functionality. TRUE: the function block creates a listening (server) socket. When implementing a TCP/TLS server that is able to communicate with several TCP/TLS clients, IS_SRV must be set to TRUE for each TLS_SOCKET_2 instance relating to this server. FALSE: the function block creates a client socket. The function block evaluates this parameter only in the task cycle in which a rising edge at the ACTIVATE input is detected. BIND_IP Data type: STRING Description: If IS_SRV = TRUE: This parameter specifies the IP address of the controller at which the server listens for incoming connections. Clients, which want to connect to this server, have to specify the same IP address as their DEST_IP input. If this string is empty (= initial value of the parameter) or contains the value '0.0.0.0', the server listens at every Ethernet adapter of the controller. IS_SRV = FALSE: In this case, the parameter is optional. If specified, it identifies which Ethernet adapter of the controller is used to establish the communication. Otherwise (if empty or contains the value '0.0.0.0'), the controller selects an appropriate Ethernet adapter using the DEST_IP parameter. The function block evaluates this parameter only in the task cycle in which a rising edge at the ACTIVATE input is detected. BIND_PORT Data type: UINT Description: Defines the local port number to which the created socket is bound (necessary for setting up TCP/TLS servers). The selected port number is used by the TCP/TLS server for incoming data. Clients, which want to connect to this server, have to specify the same port number as their DEST_PORT input. If the value is 0 (= initial value of the parameter), the stack assigns a temporary port. The function block evaluates this parameter only in the task cycle in which a rising edge at the ACTIVATE input is detected. DEST_IP Data type: STRING Description: Depending on whether the function block implements server or client functionality (set with the IS_SRV input), the input has the following meaning: With IS_SRV = TRUE (FB creates a listening socket), only requests from the client with this IP address are accepted. If the string is empty (= initial value of the parameter), any client IP address is accepted. When setting up a TCP/TLS server that is able to communicate with several TCP/TLS clients, one TLS_SOCKET_2 instance is required for each client to be connected. In this case, DEST_IP of a particular FB instance addresses one specific client. The output parameter SOURCE_IP of the TLS_RECEIVE_2 FB provides the IP address of its communication partner. With IS_SRV = FALSE (FB creates a client socket), the parameter contains the IP address of the partner server to communicate with. The function block evaluates this parameter only in the task cycle in which a rising edge at the ACTIVATE input is detected. DEST_PORT Data type: UINT Description: Depending on whether the function block implements server or client functionality (set with the IS_SRV input), the input has the following meaning: With IS_SRV = TRUE (FB creates a listening socket), only requests from the client with this IP port are accepted. If the value is 0 (= initial value of the parameter), any client IP port is accepted. The output parameter SOURCE_PORT of the TLS_RECEIVE_2 FB provides the port number of its communication partner. With IS_SRV = FALSE (FB creates a client socket), the parameter contains the IP port of the partner server to communicate with. The function block evaluates this parameter only in the task cycle in which a rising edge at the ACTIVATE input is detected. CONNECT_INFO Data type: ConnectInfo (predefined structure) Description: Attributes used for initialization of the TLS protocol on top of TCP. The values are applied in the cycle with the rising edge at the ACTIVATE input. The applied values are used as soon as the START_TLS input is TRUE. The structure contains the following predefined elements: Structure element Data type Description TrustStoreName STRING Trust Store name. The Trust Store is used to validate the remote certificate while communicating over SSL. Using the information in the Trust Store, the server can verify the identity of connecting clients by validating the authenticity of the certificates they present. The Trust Stores and the contained certificates can be managed via the Web Based Management (WBM) of the controller. This allows to exchange certificates even during operation, without having to modify the application program. For the description how to manage and link the certificates of IdentityStores and TrustStores in the WBM of the controller, see the "Additional info" description below. Further Info Further details on the certificates for secure controller communication can be found in the PLCnext Info Center. Background information A Trust Store is a special persistent memory area (identified by the Trust Store name) which contains criteria for verifying the certificates with which the communication partners authenticate their selves. In other words: the content of the Trust Store enables the verification of the authenticity of a certificate presented by a potential communication partner. IdentityStoreName STRING Identity Store name. The Identity Store contains the server certificates along with a private key. The certificates are used for authentication between the server and its clients while communicating over SSL. The value must be specified when using as TLS server. The Identity Store name is a mandatory information for servers during establishing a secure connection. The Identity Stores and the contained certificates and key pairs can be managed via the Web Based Management (WBM) of the controller. This allows to exchange certificates even during operation, without having to modify the application program. For the description how to manage and link the certificates of IdentityStores and TrustStores in the WBM of the controller, see the "Additional info" description below. Further Info Further details on the certificates for secure controller communication can be found in the PLCnext Info Center. Background information An Identity Store is a special persistent memory area (identified by the Identity Store name) which contains (partially strictly confidential) data, a device can use to authenticate itself to communication partners.   This data includes an asymmetric key pair (consisting of a public and a private key). The key pair is accompanied by a corresponding public key certificate (acc. to the X.509 standard) and optionally issuer certificates up to a Trusted Anchor.   For authentication, the device uses its asymmetric key pair. The communication partner either considers the public key as trustable because it knows its identity, or the device transmits additionally its certificate (which states its identity) and the communication partner verifies this certificate, too. In a hierarchical certification structure, the device also sends the issuer certificates stored in its Identity Store in order to enable the communication partner to validate the entire certification path. CipherList STRING List of ciphers to be used for the establishment of the secure TLS connection. As of controller firmware version 2019.6, the function block uses the default cipher list as implemented in the openSSL library if no cipher list is specified. For older firmware versions, you have to specify a (non-empty) cipher list, as otherwise no TLS connection is established when the FB is executed. Background information A cipher is a cryptographic algorithm used for encrypting and decrypting of information. Ciphers are combined in cipher suites. The cipher suite determines which algorithm should be used to establish the secure connection. The TLS protocol supports a variety of cipher suites which are used to authenticate the server and client to each other. During a secure TLS connection, the client and server negotiate which cipher suite to use based upon the available client and server ciphers for exchanging data. HostName STRING Name of remote station which is compared with the remote certificate. The HostName is used for clients and is optional. It increases the security when checking the authenticity. START_TLS Data type: BOOL Description: Defines whether communication is done via TCP or TLS. After a successful establishment of the connection, the following applies: With START_TLS = FALSE, the TLS_SEND_2/TLS_RECEIVE_2 function blocks use a pure TCP connection to send and receive data. With START_TLS = TRUE, the TLS protocol is initialized and the existing TCP connection is upgraded to a TLS connection. 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 (see above). Resetting START_TLS to FALSE during opened TLS socket causes an error (ERROR output is set to TRUE) with error code 16#C151 indicated at the STATUS output. Note The START_TLS value is compared with the value of the SEND_SECURE/RECEIVE_SECURE inputs of the TLS_SEND_2/TLS_RECEIVE_2 function blocks. If an inconsistency of the input values is detected, for example, SEND_SECURE = TRUE (IEC application requires secure transmission of data) and START_TLS = FALSE (TLS protocol not yet initialized), the TLS_SEND_2/TLS_RECEIVE_2 function blocks report an error (ERROR output = TRUE with error code 16#C150 indicated at the STATUS output). Note The function block does not support the deactivation of the TLS protocol and re-activation of the TCP protocol by resetting START_TLS to FALSE. Outputs HANDLE Data type: DWORD Description: Created TCP/TLS socket handle. The socket handle is required by subsequently calls to the function blocks TLS_RECEIVE_2 and TLS_SEND_2 in order to send or receive data, for example, to or from a TLS server. The socket handle can only be used for subsequent calls of the TLS_SEND_2/TLS_RECEIVE_2 function blocks as long as ACTIVE = TRUE. Calling the TLS_* function blocks while ACTIVE = FALSE causes an error at the function blocks (see the description of the TLS_* function blocks for the generated STATUS code). ACTIVE Data type: BOOL Description: Indicates whether a socket is open. TRUE: Connection established successfully and socket is open. As long as ACTIVE = TRUE, the socket HANDLE can be used for calls of the TLS_SEND_2/TLS_RECEIVE_2 function blocks for send/receive operations. Note Do not use a handle created with an instance of the older function block implementation TCP_SOCKET or TLS_SOCKET with the new function blocks TLS_SEND_2/TLS_RECEIVE_2 and vice versa. Only use handles within the same "FB generation". FALSE: Socket is closed. While ACTIVE = FALSE, calling the TLS_SEND_2/TLS_RECEIVE_2 function blocks with the socket HANDLE causes an error at the function blocks. BUSY Data type: BOOL Description: Set to TRUE if the ACTIVATE input is TRUE but the socket is not yet open. As soon as the socket has been opened, BUSY is set to FALSE and remains FALSE while ACTIVE = TRUE. When the ACTIVATE becomes FALSE (falling edge), the BUSY output is set to TRUE as long as the termination process lasts. ERROR Data type: BOOL Description: If an error occurs, the ERROR output is set to TRUE. The corresponding error code can be read at the STATUS output as long as ERROR = TRUE. See Error Codes / Status Codes for TLS_* Function Blocks. STATUS Data type: WORD Description: Provides the error code in the event of an error (ERROR = TRUE) or the current status of the function block (ERROR = FALSE). Error codes start with 16#Cxxx and status codes with 16#8xxx. See Error Codes / Status Codes for TLS_* Function Blocks. USED_PORT Data type: UINT Description: Indicates the port that is used for socket creation (automatically assigned or port number specified with the BIND_PORT input). The output can be used for diagnostic purposes, if needed.
Additional Info	Managing and linking certificates of TrustStores and IdentityStores The certificates of IdentityStores and TrustStores for secure controller communication are managed in the WBM of the controller. On the 'Certificate Authentication' page under the 'Security' area, you can create different TrustStores and IdentityStores and add certificates. To ensure a secure TLS communication between the server and client using the TLS_SOCKET_2 function block, the TrustStore and IdentityStore created on the 'Certificate Authentication' page must be assigned to the elements TrustStoreName and IdentityStoreName of the CONNECT_INFO structure (see above). To create the TrustStore and IdentityStore in the WBM of the controller and to add a certificate to the TrustStore and IdentityStore, proceed as follows: Adding a TrustStore and the relating certificate: In the WBM of the controller, open the 'Certificate Authentication' page under the 'Security' area. On the 'Trust Stores' tab, click on the '+' button at the end of the 'Trust Store' table. In the dialog that opens, enter a name in the 'Name' input field (for example, 'ServerTrustStore') and then click on the 'Add' button. Note The TrustStore name entered here (in our example, 'ServerTrustStore') must be assigned to the TrustStoreName element of the CONNECT_INFO structure. Click on the '+' button below the 'Certificates' table of the added TrustStore. The 'Add Certificate' dialog opens. In the 'Add Certificate' dialog, select the options as shown in the following figure and then click the 'Browse' button. In the file explorer that opens, select the certificate (in .pem format) and click 'Add'. Adding an IdentityStore and the relating certificate: In the WBM of the controller, open the 'Certificate Authentication' page under the 'Security' area. On the 'Identity Stores' tab, click on the '+' button at the end of the 'Identity Store' table. In the dialog that opens, enter a name in the 'Name' input field (for example, 'Client') and then click on the 'Add' button. Note The IdentityStore name entered here (in our example, 'Client') must be assigned to the IdentityStoreName element of the CONNECT_INFO structure. Click on the '+' button below the 'Certificates' table of the added IdentityStore. The 'Add Identity Store' dialog opens. In the 'Add Identity Store' dialog, select the options as shown in the following figure and then click the 'Browse' button. In the file explorer that opens, select the key pair (in .pem format) and click 'Add'. In the last step, the 'Client' certificate has to be added. For this, click on the button on the right of the 'Certificate' line in the 'Identity Store' table. The 'Set Key Certificate' dialog opens. In the 'Set Key Certificate' dialog set the options as shown in the previous step, select the key pair and click 'Add'.