FB_FtpSecureClient
Task
The FB_FtpSecureClient function block is dedicated to secured FTP (FTP over TLS) connections. It includes the related FTP functionalities for operations on files and directories. Each instance handles one secured FTP connection. In case you attempt to establish a second transfer, the function block responds with ET_Result.UnableToEstablishMutlipleConnections.
Functional Description
The FB_FtpSecureClient function block is the user-interface to interact with the external FTP server via a secured connection over TLS. As a prerequisite for secured communication, the connection to the FTP server must be declared as trusted. For further information, refer to Declaring the Connection to the FTP Server as Trusted.
After the function block has been enabled, a secured FTP connection is established using the secured user credentials that are submitted using iq_stCredentials. As soon as the secured connection has been established, the function block is capable of processing commands submitted by i_etCommand and a rising edge detected at i_xExecute.
As long as commands are executed, the output q_xBusy is set to TRUE. After a command has been successfully completed, q_xDone is set to TRUE.
Status messages and diagnostic information are provided using the outputs q_xError (TRUE if an error has been detected), q_etResult and q_etResultMsg.
If q_xError indicates TRUE, an error has been detected during execution. Another execution of the function block is not possible as long the error state is present. Certain error messages can be reset using the input i_xErrorQuit.
If the error state persists upon a rising edge of i_xErrorQuit, the function block must be disabled in order to reset the error state.
When disabling the function block (i_xEnable = FALSE), it must be called as long as q_xActive = TRUE in order to complete the internal cleanup routines. Afterwards it can be re-enabled.
If a timeout is exceeded after the connection has been established, the execution of the next FTP command (ET_FtpCommand) is detected as an error. To avoid this behavior, enable the function block just before performing the related operations and disable it afterwards.
Declaring the Connection to the FTP Server as Trusted
In the context of TLS, certificates can be used to verify the identity of the communication partners. Certificates are sent during the establishing of a connection; referred to as the TLS handshake. The sending of the certificate is optional for the client, unless the server requests the client certificate. The server is sending its certificate every time. Only if the result of the verification of the certificate is positive, a connection with the communication partner can be established. For secured FTP connections, the FTP server certificate must be provided to the Modicon M262 Logic/Motion Controller in the /pki/trusted/certs folder of the controller file system. The procedures for self-signed and signed certificates are described in the following:
Procedure for Self-Signed FTP Server Certificates
On the first connection attempt to the FTP server, the self-signed server certificate is stored in the /pki/untrusted directory of the controller. The following procedure describes how to shift the certificate to the /pki/trusted/certs directory using the Files tab of the device editor in the Logic Builder:
|
Step |
Action |
|---|---|
|
1 |
Login to your controller from your EcoStruxure Machine Expert FTP client application. |
|
2 |
Select the Files tab of the device editor and click the Refresh icon. |
|
3 |
In the right part of the device editor that displays the Runtime system, navigate to the /pki/untrusted directory and select the certificate (.crt) file of your FTP server. |
|
4 |
In the left part of the device editor that displays the Host, select a temporary location and transfer the certificate by clicking the << arrow button in the center of the device editor. |
|
5 |
In the right part of the device editor, navigate to the /pki/trusted/certs directory. |
|
6 |
Select the certificate in the left part of the device editor and transfer it from the temporary location to the /pki/trusted/certs directory by clicking the >> arrow button in the center of the device editor. |
Procedure for Signed FTP Server Certificates
If the FTP server certificate is signed by a Certificate Authority, you can save it to the /pki/trusted/certs directory of the controller before the first connection attempt to the FTP server is made. Proceed as follows:
|
Step |
Action |
|---|---|
|
1 |
Login to your controller from your EcoStruxure Machine Expert FTP client application. |
|
2 |
Select the Files tab of the device editor and click the Refresh icon. |
|
3 |
In the right part of the device editor, navigate to the /pki/trusted/certs directory. |
|
4 |
Select the certificate in the left part of the device editor and transfer it from the temporary location to the /pki/trusted/certs directory by clicking the >> arrow button in the center of the device editor. |
Interface
|
Input |
Data type |
Description |
|---|---|---|
|
i_xEnable |
BOOL |
Activation and initialization of the function block. Refer to Behavior of Function Blocks with the Inputs i_xEnable and i_xExecute and i_xErrorQuit. |
|
i_xExecute |
BOOL |
The command specified with the input i_etCommand is executed upon rising edge of this input. Refer to Behavior of Function Blocks with the Inputs i_xEnable and i_xExecute and i_xErrorQuit. |
|
i_xErrorQuit |
BOOL |
Certain diagnostic messages (for example, incorrect command or command with incorrect arguments) can be reset upon a rising edge of this input. Refer to Behavior of Function Blocks with the Inputs i_xEnable and i_xExecute and i_xErrorQuit. |
|
i_etCommand |
ET_FtpCommand |
The FTP command that is executed if the input i_xExecute is TRUE. |
|
Input/Output |
Data type |
Description |
|---|---|---|
|
iq_stCredentials |
ST_SecureCredentials |
Used to pass the structure containing secured user settings, such as user name or password. |
|
iq_stContent |
ST_Content |
Used to pass the working directory and, if applicable, the amount and names of files in this directory. |
|
Output |
Data type |
Description |
|---|---|---|
|
q_xActive |
BOOL |
If the function block is active, the output is set to TRUE. |
|
q_xReady |
BOOL |
If the initialization is successful, the output is set to TRUE as long as the function block is capable of accepting inputs. |
|
q_xBusy |
BOOL |
If this output is set to TRUE, the function block executes the command specified at i_etCommand. |
|
q_xDone |
BOOL |
If this output is set to TRUE, the function block has successfully completed the command specified at i_etCommand. |
|
q_xError |
BOOL |
If this output is set to TRUE, an error has been detected. For details, refer to q_etResult and q_etResultMsg. |
|
q_etResult |
ET_Result |
Provides diagnostic and status information. |
|
q_sResultMsg |
STRING[255] |
Provides additional diagnostic and status information. |