ftp_server.h
Go to the documentation of this file.
1 /**
2  * @file ftp_server.h
3  * @brief FTP server (File Transfer Protocol)
4  *
5  * @section License
6  *
7  * Copyright (C) 2010-2018 Oryx Embedded SARL. All rights reserved.
8  *
9  * This file is part of CycloneTCP Open.
10  *
11  * This program is free software; you can redistribute it and/or
12  * modify it under the terms of the GNU General Public License
13  * as published by the Free Software Foundation; either version 2
14  * of the License, or (at your option) any later version.
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19  * GNU General Public License for more details.
20  *
21  * You should have received a copy of the GNU General Public License
22  * along with this program; if not, write to the Free Software Foundation,
23  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
24  *
25  * @author Oryx Embedded SARL (www.oryx-embedded.com)
26  * @version 1.9.0
27  **/
28 
29 #ifndef _FTP_SERVER_H
30 #define _FTP_SERVER_H
31 
32 //Dependencies
33 #include "core/net.h"
34 #include "core/socket.h"
35 #include "fs_port.h"
36 
37 //FTP server support
38 #ifndef FTP_SERVER_SUPPORT
39  #define FTP_SERVER_SUPPORT ENABLED
40 #elif (FTP_SERVER_SUPPORT != ENABLED && FTP_SERVER_SUPPORT != DISABLED)
41  #error FTP_SERVER_SUPPORT parameter is not valid
42 #endif
43 
44 //Stack size required to run the FTP server
45 #ifndef FTP_SERVER_STACK_SIZE
46  #define FTP_SERVER_STACK_SIZE 650
47 #elif (FTP_SERVER_STACK_SIZE < 1)
48  #error FTP_SERVER_STACK_SIZE parameter is not valid
49 #endif
50 
51 //Priority at which the FTP server should run
52 #ifndef FTP_SERVER_PRIORITY
53  #define FTP_SERVER_PRIORITY OS_TASK_PRIORITY_NORMAL
54 #endif
55 
56 //Maximum number of simultaneous connections
57 #ifndef FTP_SERVER_MAX_CONNECTIONS
58  #define FTP_SERVER_MAX_CONNECTIONS 4
59 #elif (FTP_SERVER_MAX_CONNECTIONS < 1)
60  #error FTP_SERVER_MAX_CONNECTIONS parameter is not valid
61 #endif
62 
63 //Maximum time the server will wait before closing the connection
64 #ifndef FTP_SERVER_TIMEOUT
65  #define FTP_SERVER_TIMEOUT 60000
66 #elif (FTP_SERVER_TIMEOUT < 1000)
67  #error FTP_SERVER_TIMEOUT parameter is not valid
68 #endif
69 
70 //Socket polling timeout
71 #ifndef FTP_SERVER_SOCKET_POLLING_TIMEOUT
72  #define FTP_SERVER_SOCKET_POLLING_TIMEOUT 2000
73 #elif (FTP_SERVER_SOCKET_POLLING_TIMEOUT < 1000)
74  #error FTP_SERVER_SOCKET_POLLING_TIMEOUT parameter is not valid
75 #endif
76 
77 //Maximum length of the pending connection queue
78 #ifndef FTP_SERVER_BACKLOG
79  #define FTP_SERVER_BACKLOG 4
80 #elif (FTP_SERVER_BACKLOG < 1)
81  #error FTP_SERVER_BACKLOG parameter is not valid
82 #endif
83 
84 //Maximum line length
85 #ifndef FTP_SERVER_MAX_LINE_LEN
86  #define FTP_SERVER_MAX_LINE_LEN 255
87 #elif (FTP_SERVER_MAX_LINE_LEN < 64)
88  #error FTP_SERVER_MAX_LINE_LEN parameter is not valid
89 #endif
90 
91 //Size of buffer used for input/output operations
92 #ifndef FTP_SERVER_BUFFER_SIZE
93  #define FTP_SERVER_BUFFER_SIZE 1536
94 #elif (FTP_SERVER_BUFFER_SIZE < 128)
95  #error FTP_SERVER_BUFFER_SIZE parameter is not valid
96 #endif
97 
98 //Maximum size of root directory
99 #ifndef FTP_SERVER_MAX_ROOT_DIR_LEN
100  #define FTP_SERVER_MAX_ROOT_DIR_LEN 63
101 #elif (FTP_SERVER_MAX_ROOT_DIR_LEN < 7)
102  #error FTP_SERVER_MAX_ROOT_DIR_LEN parameter is not valid
103 #endif
104 
105 //Maximum size of home directory
106 #ifndef FTP_SERVER_MAX_HOME_DIR_LEN
107  #define FTP_SERVER_MAX_HOME_DIR_LEN 63
108 #elif (FTP_SERVER_MAX_HOME_DIR_LEN < 7)
109  #error FTP_SERVER_MAX_HOME_DIR_LEN parameter is not valid
110 #endif
111 
112 //Maximum user name length
113 #ifndef FTP_SERVER_MAX_USERNAME_LEN
114  #define FTP_SERVER_MAX_USERNAME_LEN 63
115 #elif (FTP_SERVER_MAX_USERNAME_LEN < 7)
116  #error FTP_SERVER_MAX_USERNAME_LEN parameter is not valid
117 #endif
118 
119 //Maximum path length
120 #ifndef FTP_SERVER_MAX_PATH_LEN
121  #define FTP_SERVER_MAX_PATH_LEN 255
122 #elif (FTP_SERVER_MAX_PATH_LEN < 7)
123  #error FTP_SERVER_MAX_PATH_LEN parameter is not valid
124 #endif
125 
126 //Socket buffer size (control connection)
127 #ifndef FTP_SERVER_CTRL_SOCKET_BUFFER_SIZE
128  #define FTP_SERVER_CTRL_SOCKET_BUFFER_SIZE 1430
129 #elif (FTP_SERVER_CTRL_SOCKET_BUFFER_SIZE < 1)
130  #error FTP_SERVER_CTRL_SOCKET_BUFFER_SIZE parameter is not valid
131 #endif
132 
133 //Socket buffer size (data connection)
134 #ifndef FTP_SERVER_DATA_SOCKET_BUFFER_SIZE
135  #define FTP_SERVER_DATA_SOCKET_BUFFER_SIZE 2860
136 #elif (FTP_SERVER_DATA_SOCKET_BUFFER_SIZE < 1)
137  #error FTP_SERVER_DATA_SOCKET_BUFFER_SIZE parameter is not valid
138 #endif
139 
140 //Passive port range (lower limit)
141 #ifndef FTP_SERVER_PASSIVE_PORT_MIN
142  #define FTP_SERVER_PASSIVE_PORT_MIN 48128
143 #elif (FTP_SERVER_PASSIVE_PORT_MIN < 1024)
144  #error FTP_SERVER_PASSIVE_PORT_MIN parameter is not valid
145 #endif
146 
147 //Passive port range (upper limit)
148 #ifndef FTP_SERVER_PASSIVE_PORT_MAX
149  #define FTP_SERVER_PASSIVE_PORT_MAX 49151
150 #elif (FTP_SERVER_PASSIVE_PORT_MAX <= FTP_SERVER_PASSIVE_PORT_MIN || FTP_SERVER_PASSIVE_PORT_MAX > 65535)
151  #error FTP_SERVER_PASSIVE_PORT_MAX parameter is not valid
152 #endif
153 
154 //FTP port number
155 #define FTP_PORT 21
156 //FTP data port number
157 #define FTP_DATA_PORT 20
158 
159 //FTPS port number (implicit mode)
160 #define FTPS_PORT 990
161 //FTPS data port number (implicit mode)
162 #define FTPS_DATA_PORT 989
163 
164 //C++ guard
165 #ifdef __cplusplus
166  extern "C" {
167 #endif
168 
169 
170 /**
171  * @brief Control connection state
172  **/
173 
174 typedef enum
175 {
189 
190 
191 /**
192  * @brief Data connection state
193  **/
194 
195 typedef enum
196 {
206 
207 
208 /**
209  * @brief FTP server access status
210  **/
211 
212 typedef enum
213 {
218 
219 
220 /**
221  * @brief File permissions
222  **/
223 
224 typedef enum
225 {
229 } FtpFilePerm;
230 
231 
232 /**
233  * @brief FTP client connection
234  **/
235 
236 typedef struct
237 {
238  NetInterface *interface; ///<Underlying network interface
239  bool_t userLoggedIn; ///<This flag tells whether the user is logged in
240  systime_t timestamp; ///<Time stamp to manage timeout
241  FtpControlConnState controlState; ///<Control connection state
242  Socket *controlSocket; ///<Control connection socket
243  FtpDataConnState dataState; ///<Data connection state
244  Socket *dataSocket; ///<Data connection socket
245  FsFile *file; ///<File pointer
246  FsDir *dir; ///<Directory pointer
247  bool_t passiveMode; ///<Passive data transfer
248  IpAddr remoteIpAddr; ///<Remote IP address
249  uint16_t remotePort; ///<Remote port number
250  char_t user[FTP_SERVER_MAX_USERNAME_LEN + 1]; ///<User name
251  char_t homeDir[FTP_SERVER_MAX_HOME_DIR_LEN + 1]; ///<Home directory
252  char_t currentDir[FTP_SERVER_MAX_PATH_LEN + 1]; ///<Current directory
253  char_t path[FTP_SERVER_MAX_PATH_LEN + 1]; ///<Pathname
254  char_t command[FTP_SERVER_MAX_LINE_LEN + 1]; ///<Incoming command
255  size_t commandLength; ///<Number of bytes available in the command buffer
256  char_t response[FTP_SERVER_MAX_LINE_LEN + 1]; ///<Response buffer
257  size_t responseLength; ///<Number of bytes available in the response buffer
258  size_t responsePos; ///<Current position in the response buffer
259  char_t *buffer; ///<Memory buffer for I/O operations
260  size_t bufferLength; ///<Number of bytes available in the I/O buffer
261  size_t bufferPos; ///<Current position in the I/O buffer
263 
264 
265 /**
266  * @brief User verification callback function
267  **/
268 
270  const char_t *user);
271 
272 
273 /**
274  * @brief Password verification callback function
275  **/
276 
278  const char_t *user, const char_t *password);
279 
280 
281 /**
282  * @brief Callback used to retrieve file permissions
283  **/
284 
286  const char_t *user, const char_t *path);
287 
288 
289 /**
290  * @brief Unknown command callback function
291  **/
292 
294  const char_t *command, const char_t *param);
295 
296 
297 /**
298  * @brief FTP server settings
299  **/
300 
301 typedef struct
302 {
303  NetInterface *interface; ///<Underlying network interface
304  uint16_t port; ///<FTP command port number
305  uint16_t dataPort; ///<FTP data port number
306  uint16_t passivePortMin; ///<Passive port range (lower value)
307  uint16_t passivePortMax; ///<Passive port range (upper value)
308  Ipv4Addr publicIpv4Addr; ///<Public IPv4 address to be used in PASV replies
309  char_t rootDir[FTP_SERVER_MAX_ROOT_DIR_LEN + 1]; ///<Root directory
310  FtpCheckUserCallback checkUserCallback; ///<User verification callback function
311  FtpCheckPasswordCallback checkPasswordCallback; ///<Password verification callback function
312  FtpGetFilePermCallback getFilePermCallback; ///<Callback used to retrieve file permissions
313  FtpUnknownCommandCallback unknownCommandCallback; ///<Unknown command callback function
315 
316 
317 /**
318  * @brief FTP server context
319  **/
320 
321 typedef struct
322 {
323  FtpServerSettings settings; ///<User settings
324  OsEvent event; ///<Event object used to poll the sockets
325  Socket *socket; ///<Listening socket
326  uint16_t passivePort; ///<Current passive port number
327  FtpClientConnection *connection[FTP_SERVER_MAX_CONNECTIONS]; ///<Client connections
328  SocketEventDesc eventDesc[2 * FTP_SERVER_MAX_CONNECTIONS + 1]; ///<The events the application is interested in
330 
331 
332 //FTP server related functions
334 error_t ftpServerInit(FtpServerContext *context, const FtpServerSettings *settings);
336 error_t ftpServerSetHomeDir(FtpClientConnection *connection, const char_t *homeDir);
337 
338 void ftpServerTask(FtpServerContext *context);
339 
340 //C++ guard
341 #ifdef __cplusplus
342  }
343 #endif
344 
345 #endif
size_t responsePos
Current position in the response buffer.
Definition: ftp_server.h:258
uint32_t Ipv4Addr
IPv4 network address.
Definition: ipv4.h:232
size_t bufferLength
Number of bytes available in the I/O buffer.
Definition: ftp_server.h:260
uint32_t systime_t
Definition: compiler_port.h:44
void FsDir
Directory handle.
Definition: fs_port.h:127
char char_t
Definition: compiler_port.h:41
Socket * socket
Listening socket.
Definition: ftp_server.h:325
FtpUnknownCommandCallback unknownCommandCallback
Unknown command callback function.
Definition: ftp_server.h:313
NetInterface * interface
Underlying network interface.
Definition: ftp_server.h:303
error_t ftpServerStart(FtpServerContext *context)
Start FTP server.
Definition: ftp_server.c:201
error_t ftpServerSetHomeDir(FtpClientConnection *connection, const char_t *homeDir)
Set home directory.
Definition: ftp_server.c:232
FtpControlConnState
Control connection state.
Definition: ftp_server.h:174
TCP/IP stack core.
Socket * controlSocket
Control connection socket.
Definition: ftp_server.h:242
FtpDataConnState
Data connection state.
Definition: ftp_server.h:195
error_t(* FtpUnknownCommandCallback)(FtpClientConnection *connection, const char_t *command, const char_t *param)
Unknown command callback function.
Definition: ftp_server.h:293
FtpControlConnState controlState
Control connection state.
Definition: ftp_server.h:241
FtpFilePerm
File permissions.
Definition: ftp_server.h:224
size_t commandLength
Number of bytes available in the command buffer.
Definition: ftp_server.h:255
FtpCheckPasswordCallback checkPasswordCallback
Password verification callback function.
Definition: ftp_server.h:311
IP network address.
Definition: ip.h:57
FtpCheckUserCallback checkUserCallback
User verification callback function.
Definition: ftp_server.h:310
Event object.
Ipv4Addr publicIpv4Addr
Public IPv4 address to be used in PASV replies.
Definition: ftp_server.h:308
FTP server context.
Definition: ftp_server.h:321
void ftpServerGetDefaultSettings(FtpServerSettings *settings)
Initialize settings with default values.
Definition: ftp_server.c:60
#define Socket
Definition: socket.h:34
FtpDataConnState dataState
Data connection state.
Definition: ftp_server.h:243
error_t ftpServerInit(FtpServerContext *context, const FtpServerSettings *settings)
FTP server initialization.
Definition: ftp_server.c:94
size_t responseLength
Number of bytes available in the response buffer.
Definition: ftp_server.h:257
FTP server settings.
Definition: ftp_server.h:301
uint16_t remotePort
Remote port number.
Definition: ftp_server.h:249
void ftpServerTask(FtpServerContext *context)
FTP server task.
Definition: ftp_server.c:257
uint_t(* FtpCheckPasswordCallback)(FtpClientConnection *connection, const char_t *user, const char_t *password)
Password verification callback function.
Definition: ftp_server.h:277
OsEvent event
Event object used to poll the sockets.
Definition: ftp_server.h:324
bool_t passiveMode
Passive data transfer.
Definition: ftp_server.h:247
File system abstraction layer.
FtpGetFilePermCallback getFilePermCallback
Callback used to retrieve file permissions.
Definition: ftp_server.h:312
#define FTP_SERVER_MAX_CONNECTIONS
Definition: ftp_server.h:58
Structure describing socket events.
Definition: socket.h:303
IpAddr remoteIpAddr
Remote IP address.
Definition: ftp_server.h:248
#define FTP_SERVER_MAX_USERNAME_LEN
Definition: ftp_server.h:114
error_t
Error codes.
Definition: error.h:40
void FsFile
File handle.
Definition: fs_port.h:120
bool_t userLoggedIn
This flag tells whether the user is logged in.
Definition: ftp_server.h:239
unsigned int uint_t
Definition: compiler_port.h:43
size_t bufferPos
Current position in the I/O buffer.
Definition: ftp_server.h:261
FtpAccessStatus
FTP server access status.
Definition: ftp_server.h:212
#define NetInterface
Definition: net.h:34
FsDir * dir
Directory pointer.
Definition: ftp_server.h:246
uint16_t passivePortMax
Passive port range (upper value)
Definition: ftp_server.h:307
Socket * dataSocket
Data connection socket.
Definition: ftp_server.h:244
char_t * buffer
Memory buffer for I/O operations.
Definition: ftp_server.h:259
FtpServerSettings settings
User settings.
Definition: ftp_server.h:323
#define FTP_SERVER_MAX_HOME_DIR_LEN
Definition: ftp_server.h:107
#define FTP_SERVER_MAX_LINE_LEN
Definition: ftp_server.h:86
uint16_t passivePort
Current passive port number.
Definition: ftp_server.h:326
uint_t(* FtpCheckUserCallback)(FtpClientConnection *connection, const char_t *user)
User verification callback function.
Definition: ftp_server.h:269
Socket API.
uint16_t port
FTP command port number.
Definition: ftp_server.h:304
uint_t(* FtpGetFilePermCallback)(FtpClientConnection *connection, const char_t *user, const char_t *path)
Callback used to retrieve file permissions.
Definition: ftp_server.h:285
FsFile * file
File pointer.
Definition: ftp_server.h:245
#define FTP_SERVER_MAX_PATH_LEN
Definition: ftp_server.h:121
uint16_t dataPort
FTP data port number.
Definition: ftp_server.h:305
systime_t timestamp
Time stamp to manage timeout.
Definition: ftp_server.h:240
NetInterface * interface
Underlying network interface.
Definition: ftp_server.h:238
int bool_t
Definition: compiler_port.h:47
uint16_t passivePortMin
Passive port range (lower value)
Definition: ftp_server.h:306
#define FTP_SERVER_MAX_ROOT_DIR_LEN
Definition: ftp_server.h:100
FTP client connection.
Definition: ftp_server.h:236