emFTP server
File Transfer Protocol server for embedded
The emFTP server is an optional extension that adds the server part of the FTP protocol to an IP stack.
Overview
FTP stands for File Transfer Protocol. It is the basic mechanism for moving files between machines over TCP/IP based networks such as the Internet. FTP is a client/server protocol, meaning that one machine, the client, initiates a file transfer by contacting another machine, the server and making requests. The server must be operating before the client initiates his requests. Generally a client communicates with one server at a time, while most servers are designed to work with multiple simultaneous clients.
Key features
- Low memory footprint
- Multiple connections supported
- Independent of the file system: Any file system can be used
- Independent of the TCP/IP stack: Any stack with sockets can be used
- Project for executable on PC for Microsoft Visual Studio included
- FTPS and FTPES supported
Free FTP Server for Windows, Mac, Linux
The SEGGER FTP Server is a free and complete application. It makes it possible to easily evaluate the emFTPServer core.
The Host applications (available for Windows, Linux and macOS) use the exact same "engine", so the exact same emFTPServer code available for embedded applications. This way they are guaranteed to behave the same when run on a host as when run on an embedded target.
You are more than welcome to use Wireshark to sniff the communication between the server and any FTP client. emFTPServer is compatible with any RFC compliant FPC client, from browsers such as Firefox or Chrome to dedicated FTP Clients such as FileZilla down to simple command line clients such as ftp clients that come with most host operating systems. The provided utilities are for both evaluation as well as "productive use", meaning you are free to use them if you find them useful.
FTP Backgrounds
The File Transfer Protocol (FTP) is an application layer protocol. FTP is an unusual service in that it utilizes two ports, a 'Data' port and a 'CMD' (command) port. Traditionally these are port 21 for the command port and port 20 for the data port. FTP can be used in two modes, active and passive. Depending on the mode, the data port is not always on port 20.
When an FTP client contacts a server, a TCP connection is established between the two machines. The server does a passive open (a socket is listen) when it begins operation; thereafter clients can connect with the server via active opens. This TCP connection persists for as long as the client maintains a session with the server, (usually determined by a human user). This connection is then used to convey commands from the client to the server, and the server replies back to the client. This connection is referred to as the FTP command connection.
The FTP commands from the client to the server consist of short sets of ASCII characters, followed by optional command parameters.
For example, the FTP command to display the current working directory is PWD (Print Working Directory). All commands are terminated by a carriage return-linefeed sequence (CRLF) (ASCII 10,13; or Ctrl-J, Ctrl-M). The servers replies consist of a 3 digit code (in ASCII) followed by some explanatory text. Generally codes in the 200s are success and 500s are failures. See the RFC for a complete guide to reply codes. Most FTP clients support a verbose mode which will allow the user to see these codes as commands progress.
If the FTP command requires the server to move a large piece of data (like a file), a second TCP connection is required to do this. This is referred to as the FTP data connection (as opposed to the previously mentioned command connection). In active mode, the data connection is opened by the server back to a listening client. In passive mode, the client opens also the data connection. The data connection persists only for transporting the required data. It is closed as soon as all the data has been sent.
Active Mode FTP
In active mode FTP the client connects from a random unprivileged port P (P > 1023) to the FTP server's command port, port 21. Then, the client starts listening to port P+1 and sends the FTP command PORT P+1 to the FTP server. The server will then connect back to the client's specified data port from its local data port, which is port 20.
Passive Mode FTP
In passive mode FTP the client connects from a random unprivileged port P (P > 1023) to the FTP server's command port, port 21. In opposite to an active mode FTP connection where the client opens a passive port for data transmission and waits for the connection from server-side, the client sends in passive mode the "PASV" command to the server and expects an answer with the information on which port the server is listening for the data connection.
After receiving this information, the client connects to the specified data port of the server from its local data port.
Different secure FTP protocols
With FTP (File Transfer Protocol) commands and data transfer take place in plain text.
Securing the connection using SSL/TLS is available in two different ways, FTPES and FTPS.
FTPS
Implicit mode: The implicit mode is what typically comes to mind when securing an established TCP protocol using SSL/TLS by simply wrapping the whole protocol in a secure connection, similar to how it is done for HTTP => HTTPS. For FTPS this means that instead of the well known port 21 now the port 990 is used to and the connection is secured via SSL/TLS from the start. Any non secure transaction therefore is simply not understood by the connection and is discarded.
FTPES
Explicit mode: In the explicit mode the client starts with an standard non secure connection on the well known port 21 and explicitly requests an upgrade to a secure connection. This comes with the advantage that most firewalls do not block the standard port 21 to allow basic internet operations to succeeds without causing too much hassle for customers when adding security otherwise. This also allows the server to provide optional security along with a non secure connection if necessary for older equipment. Of yourse the server can also reject the client if the client does not request an upgrade of the connection.
SFTP
Unlike FTPS and FTPES the SFTP protocol does not simply wrap the FTP protocol into a secure layer (either directly from the start or in case of FTPES at a defined time during a plain text connection). SFTP stands for SSH FTP and is not related to the original FTP protocol. It is an extension to the SSH (Secure SHell) terminal protocol mostly used in Unix systems.
FTP Reply Codes
Every FTP command is answered by one or more reply codes defined in [RFC 959]. A reply is an acknowledgment (positive or negative) sent from server to user via the control connection in response to FTP commands. The general form of a reply is a 3-digit completion code (including error codes) followed by Space , followed by one line of text and terminated by carriage return line feed . The codes are for use by programs and the text is usually intended for human users.
The first digit of the reply code defines the class of response. There are 5 values for the first digit:
- 1yz: Positive preliminary reply
- 2yz: Positive completion reply
- 3yz: Positive intermediate reply
- 4yz: Transient negative Completion reply
- 5yz: Permanent negative Completion reply
The second digit of the reply code defines the group of the response.
- x0z: Syntax - Syntax errors, syntactically correct commands that don't fit any functional category, unimplemented or superfluous commands.
- x1z: Information - These are replies to requests for information, such as status or help.
- x2z: Connections - Replies referring to the control and data connections.
- x3z: Authentication and accounting - Replies for the login process and accounting procedures.x4z: Unspecified as yet.
- x5z: File system - These replies indicate the status of the Server file system vis-a-vis the requested transfer or other file system action.
The third digit gives a finer gradation of meaning in each of the function categories, specified by the second digit.
Supported FTP Commands
emFTP FTP server supports a subset of the defined FTP commands. Refer to [RFC 959] for a complete deteailed description of the FTP commands.
The following FTP commands are implemented:
| FTP command | Description |
|---|---|
| CDUP | Change to parent directory |
| CWD | Change working directory |
| DELE | Delete |
| LIST | List |
| MKD | Make directory |
| NLST | Name list |
| NOOP | No operation |
| PASS | Password |
| PASV | Passive |
| PORT | Data port |
| PWD | Print the current working directory |
| RETR | Retrieve |
| RMD | Remove directory |
| SIZE | Size of file |
| STOR | Store |
| SYST | System |
| TYPE | Representation type |
| USER | User name |
| XCUP | Change to parent directory |
| XMKD | Make directory |
| XPWD | Print the current working directory |
| XRMD | Remove directory |
Requirements
TCP/IP Stack
The emFTP FTP server requires a TCP/IP stack. It is optimized for emNet, but any RFC-compliant TCP/IP stack can be used. The shipment includes a Win32 simulation, which uses the standard Winsock API and an implementation which uses the socket API of emNet.
Multitasking
The FTP server needs to run as a separate thread. Therefore, a multi tasking system is required to use the emFTP FTP server.
Resource Usage
ROM Usage
The ROM usage depends on the compiler options, the compiler version and the used CPU. The memory requirements of the FTP server presented in the tables below have been measured on an ARM7 and a Cortex-M3 system. Details about the further configuration can be found in the sections of the specific example.
Configuration used
#define FTPS_AUTH_BUFFER_SIZE 32
#define FTPS_BUFFER_SIZE 512
#define FTPS_MAX_PATH 128
#define FTPS_MAX_PATH_DIR 64
#define FTPS_ERR_BUFFER_SIZE (FTPS_BUFFER_SIZE / 2)ROM Usage on an ARM7 System
The following resource usage has been measured on an ARM7 system using IAR Embedded Workbench V6.30.6, Thumb mode, no interwork, size optimization.
| Add-on | ROM |
|---|---|
| emFTP FTP Server | Approximately 6.6 KByte |
ROM Usage on a Cortex-M3 System
The following resource usage has been measured on a Cortex-M3 system using IAR Embedded Workbench V6.30.6, size optimization.
| Add-on | ROM |
|---|---|
| emFTP FTP Server | Approximately 5.6 KByte |
RAM Usage
Almost all of the RAM used by the FTP server is taken from task stacks. The amount of RAM required for every child task depends on the configuration of your server. The table below shows typical RAM requirements for your task stacks.
| Task | Description | RAM |
|---|---|---|
| ParentTask | Listens for incoming connection | Approximately 500 Bytes |
| ChildTask | Handles a request | Approximately 1800 Bytes |
Note: The FTP server requires at least 1 child task. The approximately RAM usage for the FTP server can be calculated as follows: RAM usage = 0.2 KBytes + ParentTask + (NumberOfChildTasks * 1.8 KBytes)
Example: FTP server accepting only 1 connection
RAM usage = 0.2 KBytes + 0.5 KBytes + (1 * 1.8 KBytes)
RAM usage = 2.5 KBytes
Relevant Parts
The FTP server implements the relevant parts of the following Request For Comments (RFC):
| RFC | Description |
|---|---|
| [RFC 959] | Direct Link: FTP - File Transfer Protocol |