ftp_server.h

00001 /**
00002  * @file ftp_server.h
00003  * @brief FTP server (File Transfer Protocol)
00004  *
00005  * @section License
00006  *
00007  * Copyright (C) 2010-2017 Oryx Embedded SARL. All rights reserved.
00008  *
00009  * This file is part of CycloneTCP Open.
00010  *
00011  * This program is free software; you can redistribute it and/or
00012  * modify it under the terms of the GNU General Public License
00013  * as published by the Free Software Foundation; either version 2
00014  * of the License, or (at your option) any later version.
00015  *
00016  * This program is distributed in the hope that it will be useful,
00017  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00018  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00019  * GNU General Public License for more details.
00020  *
00021  * You should have received a copy of the GNU General Public License
00022  * along with this program; if not, write to the Free Software Foundation,
00023  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
00024  *
00025  * @author Oryx Embedded SARL (www.oryx-embedded.com)
00026  * @version 1.7.6
00027  **/
00028 
00029 #ifndef _FTP_SERVER_H
00030 #define _FTP_SERVER_H
00031 
00032 //Dependencies
00033 #include "core/net.h"
00034 #include "core/socket.h"
00035 #include "fs_port.h"
00036 
00037 //FTP server support
00038 #ifndef FTP_SERVER_SUPPORT
00039    #define FTP_SERVER_SUPPORT ENABLED
00040 #elif (FTP_SERVER_SUPPORT != ENABLED && FTP_SERVER_SUPPORT != DISABLED)
00041    #error FTP_SERVER_SUPPORT parameter is not valid
00042 #endif
00043 
00044 //Stack size required to run the FTP server
00045 #ifndef FTP_SERVER_STACK_SIZE
00046    #define FTP_SERVER_STACK_SIZE 650
00047 #elif (FTP_SERVER_STACK_SIZE < 1)
00048    #error FTP_SERVER_STACK_SIZE parameter is not valid
00049 #endif
00050 
00051 //Priority at which the FTP server should run
00052 #ifndef FTP_SERVER_PRIORITY
00053    #define FTP_SERVER_PRIORITY OS_TASK_PRIORITY_NORMAL
00054 #endif
00055 
00056 //Maximum number of simultaneous connections
00057 #ifndef FTP_SERVER_MAX_CONNECTIONS
00058    #define FTP_SERVER_MAX_CONNECTIONS 4
00059 #elif (FTP_SERVER_MAX_CONNECTIONS < 1)
00060    #error FTP_SERVER_MAX_CONNECTIONS parameter is not valid
00061 #endif
00062 
00063 //Maximum time the server will wait before closing the connection
00064 #ifndef FTP_SERVER_TIMEOUT
00065    #define FTP_SERVER_TIMEOUT 60000
00066 #elif (FTP_SERVER_TIMEOUT < 1000)
00067    #error FTP_SERVER_TIMEOUT parameter is not valid
00068 #endif
00069 
00070 //Socket polling timeout
00071 #ifndef FTP_SERVER_SOCKET_POLLING_TIMEOUT
00072    #define FTP_SERVER_SOCKET_POLLING_TIMEOUT 2000
00073 #elif (FTP_SERVER_SOCKET_POLLING_TIMEOUT < 1000)
00074    #error FTP_SERVER_SOCKET_POLLING_TIMEOUT parameter is not valid
00075 #endif
00076 
00077 //Maximum length of the pending connection queue
00078 #ifndef FTP_SERVER_BACKLOG
00079    #define FTP_SERVER_BACKLOG 4
00080 #elif (FTP_SERVER_BACKLOG < 1)
00081    #error FTP_SERVER_BACKLOG parameter is not valid
00082 #endif
00083 
00084 //Maximum line length
00085 #ifndef FTP_SERVER_MAX_LINE_LEN
00086    #define FTP_SERVER_MAX_LINE_LEN 255
00087 #elif (FTP_SERVER_MAX_LINE_LEN < 64)
00088    #error FTP_SERVER_MAX_LINE_LEN parameter is not valid
00089 #endif
00090 
00091 //Size of buffer used for input/output operations
00092 #ifndef FTP_SERVER_BUFFER_SIZE
00093    #define FTP_SERVER_BUFFER_SIZE 1536
00094 #elif (FTP_SERVER_BUFFER_SIZE < 128)
00095    #error FTP_SERVER_BUFFER_SIZE parameter is not valid
00096 #endif
00097 
00098 //Maximum size of root directory
00099 #ifndef FTP_SERVER_MAX_ROOT_DIR_LEN
00100    #define FTP_SERVER_MAX_ROOT_DIR_LEN 63
00101 #elif (FTP_SERVER_MAX_ROOT_DIR_LEN < 7)
00102    #error FTP_SERVER_MAX_ROOT_DIR_LEN parameter is not valid
00103 #endif
00104 
00105 //Maximum size of home directory
00106 #ifndef FTP_SERVER_MAX_HOME_DIR_LEN
00107    #define FTP_SERVER_MAX_HOME_DIR_LEN 63
00108 #elif (FTP_SERVER_MAX_HOME_DIR_LEN < 7)
00109    #error FTP_SERVER_MAX_HOME_DIR_LEN parameter is not valid
00110 #endif
00111 
00112 //Maximum user name length
00113 #ifndef FTP_SERVER_MAX_USERNAME_LEN
00114    #define FTP_SERVER_MAX_USERNAME_LEN 63
00115 #elif (FTP_SERVER_MAX_USERNAME_LEN < 7)
00116    #error FTP_SERVER_MAX_USERNAME_LEN parameter is not valid
00117 #endif
00118 
00119 //Maximum path length
00120 #ifndef FTP_SERVER_MAX_PATH_LEN
00121    #define FTP_SERVER_MAX_PATH_LEN 255
00122 #elif (FTP_SERVER_MAX_PATH_LEN < 7)
00123    #error FTP_SERVER_MAX_PATH_LEN parameter is not valid
00124 #endif
00125 
00126 //Socket buffer size (control connection)
00127 #ifndef FTP_SERVER_CTRL_SOCKET_BUFFER_SIZE
00128    #define FTP_SERVER_CTRL_SOCKET_BUFFER_SIZE 1430
00129 #elif (FTP_SERVER_CTRL_SOCKET_BUFFER_SIZE < 1)
00130    #error FTP_SERVER_CTRL_SOCKET_BUFFER_SIZE parameter is not valid
00131 #endif
00132 
00133 //Socket buffer size (data connection)
00134 #ifndef FTP_SERVER_DATA_SOCKET_BUFFER_SIZE
00135    #define FTP_SERVER_DATA_SOCKET_BUFFER_SIZE 2860
00136 #elif (FTP_SERVER_DATA_SOCKET_BUFFER_SIZE < 1)
00137    #error FTP_SERVER_DATA_SOCKET_BUFFER_SIZE parameter is not valid
00138 #endif
00139 
00140 //Passive port range (lower limit)
00141 #ifndef FTP_SERVER_PASSIVE_PORT_MIN
00142    #define FTP_SERVER_PASSIVE_PORT_MIN 48128
00143 #elif (FTP_SERVER_PASSIVE_PORT_MIN < 1024)
00144    #error FTP_SERVER_PASSIVE_PORT_MIN parameter is not valid
00145 #endif
00146 
00147 //Passive port range (upper limit)
00148 #ifndef FTP_SERVER_PASSIVE_PORT_MAX
00149    #define FTP_SERVER_PASSIVE_PORT_MAX 49151
00150 #elif (FTP_SERVER_PASSIVE_PORT_MAX <= FTP_SERVER_PASSIVE_PORT_MIN || FTP_SERVER_PASSIVE_PORT_MAX > 65535)
00151    #error FTP_SERVER_PASSIVE_PORT_MAX parameter is not valid
00152 #endif
00153 
00154 //FTP port number
00155 #define FTP_PORT 21
00156 //FTP data port number
00157 #define FTP_DATA_PORT 20
00158 
00159 //FTPS port number (implicit mode)
00160 #define FTPS_PORT 990
00161 //FTPS data port number (implicit mode)
00162 #define FTPS_DATA_PORT 989
00163 
00164 
00165 /**
00166  * @brief Control connection state
00167  **/
00168 
00169 typedef enum
00170 {
00171    FTP_CONTROL_STATE_CLOSED      = 0,
00172    FTP_CONTROL_STATE_IDLE        = 1,
00173    FTP_CONTROL_STATE_DISCARD     = 2,
00174    FTP_CONTROL_STATE_USER        = 3,
00175    FTP_CONTROL_STATE_LIST        = 4,
00176    FTP_CONTROL_STATE_RETR        = 5,
00177    FTP_CONTROL_STATE_STOR        = 6,
00178    FTP_CONTROL_STATE_APPE        = 7,
00179    FTP_CONTROL_STATE_RNFR        = 8,
00180    FTP_CONTROL_STATE_WAIT_ACK    = 9,
00181    FTP_CONTROL_STATE_SHUTDOWN_TX = 10,
00182    FTP_CONTROL_STATE_SHUTDOWN_RX = 11
00183 } FtpControlConnState;
00184 
00185 
00186 /**
00187  * @brief Data connection state
00188  **/
00189 
00190 typedef enum
00191 {
00192    FTP_DATA_STATE_CLOSED      = 0,
00193    FTP_DATA_STATE_LISTEN      = 1,
00194    FTP_DATA_STATE_IDLE        = 2,
00195    FTP_DATA_STATE_SEND        = 3,
00196    FTP_DATA_STATE_RECEIVE     = 4,
00197    FTP_DATA_STATE_WAIT_ACK    = 5,
00198    FTP_DATA_STATE_SHUTDOWN_TX = 6,
00199    FTP_DATA_STATE_SHUTDOWN_RX = 7
00200 } FtpDataConnState;
00201 
00202 
00203 /**
00204  * @brief FTP server access status
00205  **/
00206 
00207 typedef enum
00208 {
00209    FTP_ACCESS_DENIED     = 0,
00210    FTP_ACCESS_ALLOWED    = 1,
00211    FTP_PASSWORD_REQUIRED = 2
00212 } FtpAccessStatus;
00213 
00214 
00215 /**
00216  * @brief File permissions
00217  **/
00218 
00219 typedef enum
00220 {
00221    FTP_FILE_PERM_LIST  = 0x01,
00222    FTP_FILE_PERM_READ  = 0x02,
00223    FTP_FILE_PERM_WRITE = 0x04
00224 } FtpFilePerm;
00225 
00226 
00227 /**
00228  * @brief FTP client connection
00229  **/
00230 
00231 typedef struct
00232 {
00233    NetInterface *interface;                         ///<Underlying network interface
00234    bool_t userLoggedIn;                             ///<This flag tells whether the user is logged in
00235    systime_t timestamp;                             ///<Time stamp to manage timeout
00236    FtpControlConnState controlState;                ///<Control connection state
00237    Socket *controlSocket;                           ///<Control connection socket
00238    FtpDataConnState dataState;                      ///<Data connection state
00239    Socket *dataSocket;                              ///<Data connection socket
00240    FsFile *file;                                    ///<File pointer
00241    FsDir *dir;                                      ///<Directory pointer
00242    bool_t passiveMode;                              ///<Passive data transfer
00243    IpAddr remoteIpAddr;                             ///<Remote IP address
00244    uint16_t remotePort;                             ///<Remote port number
00245    char_t user[FTP_SERVER_MAX_USERNAME_LEN + 1];    ///<User name
00246    char_t homeDir[FTP_SERVER_MAX_HOME_DIR_LEN + 1]; ///<Home directory
00247    char_t currentDir[FTP_SERVER_MAX_PATH_LEN + 1];  ///<Current directory
00248    char_t path[FTP_SERVER_MAX_PATH_LEN + 1];        ///<Pathname
00249    char_t command[FTP_SERVER_MAX_LINE_LEN + 1];     ///<Incoming command
00250    size_t commandLength;                            ///<Number of bytes available in the command buffer
00251    char_t response[FTP_SERVER_MAX_LINE_LEN + 1];    ///<Response buffer
00252    size_t responseLength;                           ///<Number of bytes available in the response buffer
00253    size_t responsePos;                              ///<Current position in the response buffer
00254    char_t *buffer;                                  ///<Memory buffer for I/O operations
00255    size_t bufferLength;                             ///<Number of bytes available in the I/O buffer
00256    size_t bufferPos;                                ///<Current position in the I/O buffer
00257 } FtpClientConnection;
00258 
00259 
00260 /**
00261  * @brief User verification callback function
00262  **/
00263 
00264 typedef uint_t (*FtpCheckUserCallback)(FtpClientConnection *connection,
00265    const char_t *user);
00266 
00267 
00268 /**
00269  * @brief Password verification callback function
00270  **/
00271 
00272 typedef uint_t (*FtpCheckPasswordCallback)(FtpClientConnection *connection,
00273    const char_t *user, const char_t *password);
00274 
00275 
00276 /**
00277  * @brief Callback used to retrieve file permissions
00278  **/
00279 
00280 typedef uint_t (*FtpGetFilePermCallback)(FtpClientConnection *connection,
00281    const char_t *user, const char_t *path);
00282 
00283 
00284 /**
00285  * @brief Unknown command callback function
00286  **/
00287 
00288 typedef error_t (*FtpUnknownCommandCallback)(FtpClientConnection *connection,
00289    const char_t *command, const char_t *param);
00290 
00291 
00292 /**
00293  * @brief FTP server settings
00294  **/
00295 
00296 typedef struct
00297 {
00298    NetInterface *interface;                          ///<Underlying network interface
00299    uint16_t port;                                    ///<FTP command port number
00300    uint16_t dataPort;                                ///<FTP data port number
00301    uint16_t passivePortMin;                          ///<Passive port range (lower value)
00302    uint16_t passivePortMax;                          ///<Passive port range (upper value)
00303    char_t rootDir[FTP_SERVER_MAX_ROOT_DIR_LEN + 1];  ///<Root directory
00304    FtpCheckUserCallback checkUserCallback;           ///<User verification callback function
00305    FtpCheckPasswordCallback checkPasswordCallback;   ///<Password verification callback function
00306    FtpGetFilePermCallback getFilePermCallback;       ///<Callback used to retrieve file permissions
00307    FtpUnknownCommandCallback unknownCommandCallback; ///<Unknown command callback function
00308 } FtpServerSettings;
00309 
00310 
00311 /**
00312  * @brief FTP server context
00313  **/
00314 
00315 typedef struct
00316 {
00317    FtpServerSettings settings;                                    ///<User settings
00318    OsEvent event;                                                 ///<Event object used to poll the sockets
00319    Socket *socket;                                                ///<Listening socket
00320    uint16_t passivePort;                                          ///<Current passive port number
00321    FtpClientConnection *connection[FTP_SERVER_MAX_CONNECTIONS];   ///<Client connections
00322    SocketEventDesc eventDesc[2 * FTP_SERVER_MAX_CONNECTIONS + 1]; ///<The events the application is interested in
00323 } FtpServerContext;
00324 
00325 
00326 //FTP server related functions
00327 void ftpServerGetDefaultSettings(FtpServerSettings *settings);
00328 error_t ftpServerInit(FtpServerContext *context, const FtpServerSettings *settings);
00329 error_t ftpServerStart(FtpServerContext *context);
00330 error_t ftpServerSetHomeDir(FtpClientConnection *connection, const char_t *homeDir);
00331 
00332 void ftpServerTask(FtpServerContext *context);
00333 
00334 #endif
00335