FTP Client API

Table of Contents >> Application Reference

The FTP Client Application Program Interface allows the user to interact with a remote FTP server: sending and receiving data and performing various file maintenance functions on the remote filesystem. It consists primarily of two parts:

1. User Interface:

The user interface allows the user to send commands to the remote FTP server.

2. File System Interface:

The file system interface allows the FTP client to interact with the operating system's file system to store and retrieve files for example.

User Interface

There are two types of calls provided in the FTP Client User Interface. The first of these is to create and end an FTP session. A session can be composed of multiple consecutive connects to various servers. These calls include tfFtpNewSession() and tfFtpFreeSession(). A session can be called in either blocking mode or non-blocking mode.

Blocking Mode

In this mode, each FTP command will return only once the operation has completed and will block until completed. Choose this mode if you are using an RTOS/Kernel.

Non-Blocking Mode

In this mode, each FTP command returns immediately after beginning the operation. After each initial command is made, it is necessary for the user to call tfFtpUserExecute() until the command has completed, which is indicated by tfFtpUserExecute() returning a value other than TM_EWOULDBLOCK.

The next type of call is to send various commands to the FTP server. These commands perform various file operations such as send or receive, delete and create directory. These calls are composed of routines such as tfFtpConnect(), tfFtpStor() and tfFtpDirList().

As an example of the FTP client user interface, suppose we have an embedded device that wishes to upload a log file to a main server, and also to retrieve the most recent configuration settings.

Here is example code that would perform these functions:

 
ttUserFtpHandle ftpHandle;
int             errorCode;
 
/*
 * Create a new FTP client session, which includes
 * logging into the local filesystem.
 */
ftpHandle = tfFtpNewSession(0, 
                            TM_BLOCKING_ON,   
                            "fsusername",
                            "fspassword");
 
/* Connect to the FTP server */
errorCode = tfFtpConnect(ftpHandle,"10.129.5.10");
 
/* Login to the server */
errorCode = tfFtpLogin(ftpHandle,
                       "ftpuser",
                       "ftppass",
                       "ftpacct");
 
/* Transmit daily log file to server */
errorCode = tfFtpStor(ftpHandle,
                      0,
                      "/home/treck/100999.log",
                      "logfile");
 
/* Retrieve most recent configuration file from server. */
errorCode = tfFtpRetr(ftpHandle,
                      0,
                      "/home/treck/device.cfg",
                      "configfile");
 
/* Close FTP connection */
errorCode = tfFtpQuit(ftpHandle);
 
/* End FTP session */
errorCode = tfFtpFreeSession(ftpHandle);
 

File System Interface

The user must provide this interface to the file system. These functions, outlined below, allow the FTP client to access the local file system. This interface is a subset of that required by the FTP server (FTPD) and the same routines may be used for both the FTP client and server.

Entry points from the FTP client to the file system:

tfFSCloseDir()	Close a directory that we had opened earlier.
tfFSCloseFile()	Close a file.
tfFSOpenDir()	Open specified directory, or directory corresponding to a specified pattern to allow getting a long or short listing of the directory or of the directory entries matching the specified pattern.
tfFSOpenFile()	Open a file (creating it if it does not exist), for read, write, or append, specifying type (ASCII, or binary), structure (stream, or record).
tfFSReadFile()	Read n bytes from a file into a buffer.
tfFSUserLogin()	Login a user if password is valid.
tfFSUserLogout()	Logout a user.
tfFSWriteFile()	Write some bytes from a buffer to a file.

Note:

File system calls for the FTP server can be found on the File System Interface page.

FTP Client API Summary

tfFtpNewSession()	Creates a new FTP session
tfFtpFreeSession()	Frees a FTP session
tfFtpClose()	Closes a FTP connection; used if tfFtpQuit() cannot close the connection properly.
tfFtpConnect()	Connects to a remote FTP server
tfFtpLogin()	Log on and authenticate to a FTP server
tfFtpCwd()	Changes current remote directory
tfFtpCdup()	Changes to the current directory's parent directory.
tfFtpQuit()	Ends current FTP connection.
tfFtpRein()	Resets current FTP connection
tfFtpType()	Sets the current transfer type (ASCII or binary)
tfFtpRetr()	Retrieves a file from the remote file system.
tfFtpStor()	Stores a file on the remote file system.
tfFtpAppe()	Appends a file to a file on the remote file system.
tfFtpRename()	Rename a remote file
tfFtpAbor()	Aborts the transfer in progress.
tfFtpDele()	Deletes a remote file
tfFtpRmd()	Removes a remote directory
tfFtpMkd()	Creates a directory
tfFtpPwd()	Retrieves the present working directory
tfFtpDirList()	Retrieves a directory listing
tfFtpSyst()	Returns information about the system hosting the remote file system
tfFtpHelp()	Retrieves help from the FTP server about a command
tfFtpMode()	Sets the FTP transfer mode.
tfFtpNoop()	Does nothing; used to keep an idle connection open
tfFtpPort()	Sets the port used for incoming data connections
tfFtpGetReplyText()	Returns the full text reply from the last executed command
tfFtpUserExecute()	Called only in non-blocking mode. Should be called periodically to allow the FTP client to continue to process requests.
tfFtpSslEnable()	Enables SSL/TLS for the current FTP session.
tfFtpSslSetProposals()	Sets the acceptable SSL cipher suites for the specified FTP session.
tfFtpSslDisable()	Disables SSL/TLS for the current FTP session.
tfFtpSslSecureDataConn()	Forces all future data connections to use SSL/TLS.
tfFtpSslUnsecureDataConn()	Disables the use of SSL/TLS on all future data connections.

Return Codes

All of the functions in the FTP Client API return standard error codes. In cases where the call itself succeeded, but the FTP server returned an error, a different, but mutually exclusive, set of error codes are used. These constants are included with each of the user interface calls below and all begin with TM_FTP. For further information on the meaning of these codes, please see RFC 640.

Using SSL/TLS with the Treck FTP Client

The Treck FTP client can be used with SSL/TLS to secure the control and/or data connections during operation. This is done using the following APIs.

• tfFtpSslEnable()
• tfFtpSslSetProposals()
• tfFtpSslDisable()
• tfFtpSslSecureDataConn()
• tfFtpSslUnsecureDataConn()

Securing the Control Connection

When tfFtpSslEnable() is called:

• FTP client sends "AUTH" command with "TLS" parameter.
• Server should respond with reply message.
• If reply from FTP server was OK, enable SSL on the control connection:

• Set TM_TCP_SSL_CLIENT option on control connection socket using setsockopt.
• Create new SSL session using tfSslNewSession and certificate name stored in the FTP client state vector.
• Start the SSL client on the control connection (tfSslClientUserStart()).
• If SSL/TLS negotiation fails, or completes with unacceptable parameters, issue a "QUIT" command.
• If SSL/TLS negotiation fails during SSL/TLS handshake, close the control connection.

• If data connections are to be secured:

• Send 'PBSZ 0' command, await reply.

• If reply indicates error, tfFtpSslEnable() returns an error.

• Send 'PROT P' command, await reply.

• If reply indicates error, tfFtpSslEnable() returns an error.

• A 521 reply indicates that the PROT setting is incorrect.

Note:

This must only be done if SSL is enabled on the control connection. Additionally, the PBSZ command must always be sent before the PROT command.

• If SSL negotiation was OK, tfFtpSslEnable() returns TM_ENOERROR.

When tfFtpSslDisable() is called:

• FTP client sends "CCC" command to the server.
• Server should respond with reply message. If server does not support the "CCC" command, it should return an error.
• If data connections are not to be secured (i.e. SSL should be disabled on the data connection):

• Send 'PROT C' command and await a reply.

When tfFtpSslSecureDataConn() is called:

• FTP client sends "PROT P" command to the server and awaits the reply.

When tfFtpSslUnsecureDataConn() is called:

• FTP client sends "PROT C" command to the server and awaits the reply.

Securing the Data Connection

Establish normal (plaintext) data connection first, as usual.

• If a 521 reply is returned, this indicates that data connection cannot be established using currently security level (e.g. SSL is not enabled when it needs to be).

After normal (plaintext) data connection is established, if SSL is enabled, start SSL on the FTP client:

• Set TM_TCP_SSL_CLIENT option on data connection socket via setsockopt().
• Create new SSL session via tfSslNewSession(), using certificate name stored in the FTP client state vector.
• Start the SSL client on the data connection via tfSslClientUserStart().
• If SSL/TLS negotiation fails, a 522 reply will be returned from server and the data connection immediately closed.

Reinitialization

When the reply to a REIN command is received, SSL sessions on the control and data channels must be closed using tfSslConnectUserClose().

FTP over SSL/TLS Example Code

Starting SSL before sending USER command

 
ftpHandle = tfFtpNewSession(...);
/* connect to FTP server. */
tfFtpConnect(ftpHandle,...);
/* Send AUTH command to server and start SSL session for control
* connection. After authenticating, future data connections
* should be secure */
tfFtpSslEnable(ftpHandle,...,secureDataConn=true);
/* Send USER/PASS/SITE (encrypted) commands to server. */
tfFtpLogin(ftpHandle,...);
.
.
.
/* Get directory listing (protected) */
tfFtpDirList(ftpHandle,...);
/* Transmit a file (protected) */
tfFtpStor(ftpHandle,...);
 

Starting SSL after sending USER command

 
ftpHandle = tfFtpNewSession(…);
/* connect to FTP server. */
tfFtpConnect(ftpHandle...);
/* Send USER/PASS/SITE (plaintext) command to server. */
tfFtpLogin(ftpHandle...);
/* Send AUTH command to server and start SSL session for control
* connection. After authenticating, future data connections
* should be secure */
tfFtpSslEnable(ftpHandle...,secureDataConn=true);
.
.
.
/* Get directory listing (protected) */
tfFtpDirList(ftpHandle...);
/* Transmit a file (protected) */
tfFtpStor(ftpHandle...);
 

Manually securing the data connection

 
ftpHandle = tfFtpNewSession(...);
/* connect to FTP server. */
tfFtpConnect(ftpHandle,...);
/* Send USER/PASS/SITE (plaintext) command to server. */
tfFtpLogin(ftpHandle,...);
/* Send AUTH command to server and start SSL session for control
* connection. After authenticating, future data connections will not
* be secure */
tfFtpSslEnable(ftpHandle,...,secureDataConn=false);
/* Get directory listing (plaintext) */
tfFtpDirList(ftpHandle,...);
/* Secure the data connection. */
tfFtpSslSecureDataConn(ftpHandle);
/* Transmit a file (protected) */
tfFtpStor(ftpHandle,...);
 

Manually unsecuring the data connection

 
ftpHandle = tfFtpNewSession(...);
/* connect to FTP server. */
tfFtpConnect(ftpHandle,...);
/* Send USER/PASS/SITE (plaintext) command to server. */
tfFtpLogin(ftpHandle,...);
/* Send AUTH command to server and start SSL session for control
* connection. After authenticating, future data connections will be
* secure */
tfFtpSslEnable(ftpHandle,...,secureDataConn=true);
/* Transmit a file (protected) */
tfFtpStor(ftpHandle,...);
/* Un-secure the data connection. */
tfFtpSslUnsecureDataConn(ftpHandle);
/* Get directory listing (plaintext) */
tfFtpDirList(ftpHandle,...);
 

Disabling SSL on the control and data connection

 
ftpHandle = tfFtpNewSession(...);
/* connect to FTP server. */
tfFtpConnect(ftpHandle,...);
/* Send USER/PASS/SITE (plaintext) command to server. */
tfFtpLogin(ftpHandle,...);
/* Send AUTH command to server and start SSL session for control
* connection. After authenticating, future data connections
* will be secure */
tfFtpSslEnable(ftpHandle,...,secureDataConn=true);
/* Transmit a file (protected) */
tfFtpStor(ftpHandle,...);
/* Disable SSL on the control and data connection */
tfFtpSslDisable(ftpHandle, secureDataConn=true);
/* Transmit a file (plaintext) */
tfFtpStor(ftpHandle,...);
 

Disabling SSL on just the control connection

 
ftpHandle = tfFtpNewSession(...);
/* connect to FTP server. */
tfFtpConnect(ftpHandle,...);
/* Send USER/PASS/SITE (plaintext) command to server. */
tfFtpLogin(ftpHandle,...);
/* Send AUTH command to server and start SSL session for control
* connection. After authenticating, future data connections
* will be secure */
tfFtpSslEnable(ftpHandle,...,secureDataConn=true);
/* Transmit a file (protected) */
tfFtpStor(ftpHandle,...);
/* Disable SSL on the control and data connection */
tfFtpSslDisable(ftpHandle, secureDataConn=false);
/* Transmit a file (protected) */
tfFtpStor(ftpHandle,...);
 
 
 

Table of Contents >> Application Reference