sftp_server.h
Go to the documentation of this file.
1 /**
2  * @file sftp_server.h
3  * @brief SFTP server
4  *
5  * @section License
6  *
7  * SPDX-License-Identifier: GPL-2.0-or-later
8  *
9  * Copyright (C) 2019-2026 Oryx Embedded SARL. All rights reserved.
10  *
11  * This file is part of CycloneSSH Open.
12  *
13  * This program is free software; you can redistribute it and/or
14  * modify it under the terms of the GNU General Public License
15  * as published by the Free Software Foundation; either version 2
16  * of the License, or (at your option) any later version.
17  *
18  * This program is distributed in the hope that it will be useful,
19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21  * GNU General Public License for more details.
22  *
23  * You should have received a copy of the GNU General Public License
24  * along with this program; if not, write to the Free Software Foundation,
25  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
26  *
27  * @author Oryx Embedded SARL (www.oryx-embedded.com)
28  * @version 2.6.6
29  **/
30 
31 #ifndef _SFTP_SERVER_H
32 #define _SFTP_SERVER_H
33 
34 //Dependencies
35 #include "ssh/ssh_server.h"
36 #include "sftp/sftp_common.h"
37 #include "fs_port.h"
38 
39 //SFTP server support
40 #ifndef SFTP_SERVER_SUPPORT
41  #define SFTP_SERVER_SUPPORT DISABLED
42 #elif (SFTP_SERVER_SUPPORT != ENABLED && SFTP_SERVER_SUPPORT != DISABLED)
43  #error SFTP_SERVER_SUPPORT parameter is not valid
44 #endif
45 
46 //Stack size required to run the SFTP server
47 #ifndef SFTP_SERVER_STACK_SIZE
48  #define SFTP_SERVER_STACK_SIZE 650
49 #elif (SFTP_SERVER_STACK_SIZE < 1)
50  #error SFTP_SERVER_STACK_SIZE parameter is not valid
51 #endif
52 
53 //Priority at which the SFTP server should run
54 #ifndef SFTP_SERVER_PRIORITY
55  #define SFTP_SERVER_PRIORITY OS_TASK_PRIORITY_NORMAL
56 #endif
57 
58 //Maximum number of simultaneous SFTP sessions
59 #ifndef SFTP_SERVER_MAX_SESSIONS
60  #define SFTP_SERVER_MAX_SESSIONS 10
61 #elif (SFTP_SERVER_MAX_SESSIONS < 1)
62  #error SFTP_SERVER_MAX_SESSIONS parameter is not valid
63 #endif
64 
65 //SFTP server tick interval
66 #ifndef SFTP_SERVER_TICK_INTERVAL
67  #define SFTP_SERVER_TICK_INTERVAL 1000
68 #elif (SFTP_SERVER_TICK_INTERVAL < 100)
69  #error SFTP_SERVER_TICK_INTERVAL parameter is not valid
70 #endif
71 
72 //Minimum SFTP protocol version that can be negotiated
73 #ifndef SFTP_SERVER_MIN_VERSION
74  #define SFTP_SERVER_MIN_VERSION 1
75 #elif (SFTP_SERVER_MIN_VERSION < 1)
76  #error SFTP_SERVER_MIN_VERSION parameter is not valid
77 #endif
78 
79 //Maximum SFTP protocol version that can be negotiated
80 #ifndef SFTP_SERVER_MAX_VERSION
81  #define SFTP_SERVER_MAX_VERSION 3
82 #elif (SFTP_SERVER_MAX_VERSION > 3 || SFTP_SERVER_MAX_VERSION < SFTP_CLIENT_MIN_VERSION)
83  #error SFTP_SERVER_MAX_VERSION parameter is not valid
84 #endif
85 
86 //Size of buffer used for input/output operations
87 #ifndef SFTP_SERVER_BUFFER_SIZE
88  #define SFTP_SERVER_BUFFER_SIZE 1024
89 #elif (SFTP_SERVER_BUFFER_SIZE < 128)
90  #error SFTP_SERVER_BUFFER_SIZE parameter is not valid
91 #endif
92 
93 //Maximum length of root directory
94 #ifndef SFTP_SERVER_MAX_ROOT_DIR_LEN
95  #define SFTP_SERVER_MAX_ROOT_DIR_LEN 63
96 #elif (SFTP_SERVER_MAX_ROOT_DIR_LEN < 7)
97  #error SFTP_SERVER_MAX_ROOT_DIR_LEN parameter is not valid
98 #endif
99 
100 //Maximum length of home directory
101 #ifndef SFTP_SERVER_MAX_HOME_DIR_LEN
102  #define SFTP_SERVER_MAX_HOME_DIR_LEN 63
103 #elif (SFTP_SERVER_MAX_HOME_DIR_LEN < 7)
104  #error SFTP_SERVER_MAX_HOME_DIR_LEN parameter is not valid
105 #endif
106 
107 //Maximum path length
108 #ifndef SFTP_SERVER_MAX_PATH_LEN
109  #define SFTP_SERVER_MAX_PATH_LEN 255
110 #elif (SFTP_SERVER_MAX_PATH_LEN < 7)
111  #error SFTP_SERVER_MAX_PATH_LEN parameter is not valid
112 #endif
113 
114 //Application specific context
115 #ifndef SFTP_SERVER_CONTEXT_PRIVATE
116  #define SFTP_SERVER_CONTEXT_PRIVATE
117 #endif
118 
119 //Application specific context
120 #ifndef SFTP_SERVER_SESSION_PRIVATE
121  #define SFTP_SERVER_SESSION_PRIVATE
122 #endif
123 
124 //Forward declaration of SftpServerContext structure
125 struct _SftpServerContext;
126 #define SftpServerContext struct _SftpServerContext
127 
128 //Forward declaration of SftpServerSession structure
129 struct _SftpServerSession;
130 #define SftpServerSession struct _SftpServerSession
131 
132 //C++ guard
133 #ifdef __cplusplus
134 extern "C" {
135 #endif
136 
137 
138 /**
139  * @brief Access status
140  **/
141 
142 typedef enum
143 {
147 
148 
149 /**
150  * @brief File permissions
151  **/
152 
153 typedef enum
154 {
157  SFTP_FILE_PERM_WRITE = 0x04
159 
160 
161 /**
162  * @brief SFTP session state
163  **/
164 
165 typedef enum
166 {
173 
174 
175 /**
176  * @brief User verification callback function
177  **/
178 
180  const char_t *user);
181 
182 
183 /**
184  * @brief Callback used to retrieve file permissions
185  **/
186 
188  const char_t *user, const char_t *path);
189 
190 
191 /**
192  * @brief File or directory object
193  **/
194 
195 typedef struct
196 {
197  SftpFileType type; ///<File type
198  SftpServerSession *session; ///<Pointer to the SFTP session
199  char_t path[SFTP_SERVER_MAX_PATH_LEN + 1]; ///<Path name
200  uint32_t handle; ///<Opaque value that identifies the file
201  uint64_t size; ///<Size of the file
202  uint64_t offset; ///<Offset within the file
203  FsFile *file; ///<File pointer
204  FsDir *dir; ///<Directory pointer
206 
207 
208 /**
209  * @brief SFTP server settings
210  **/
211 
212 typedef struct
213 {
214  OsTaskParameters task; ///<Task parameters
215  SshServerContext *sshServerContext; ///<SSH server context
216  uint_t numSessions; ///<Maximum number of SFTP sessions
217  SftpServerSession *sessions; ///<SFTP sessions
218  uint_t numFileObjects; ///<Maximum number of file objects
219  SftpFileObject *fileObjects; ///<File objects
220  const char_t *rootDir; ///<Root directory
221  SftpServerCheckUserCallback checkUserCallback; ///<User verification callback function
222  SftpServerGetFilePermCallback getFilePermCallback; ///<Callback used to retrieve file permissions
224 
225 
226 /**
227  * @brief SFTP session
228  **/
229 
231 {
232  SftpServerSessionState state; ///<Session state
233  SftpVersion version; ///<SFTP protocol version
234  SftpServerContext *context; ///<SFTP server context
235  SshChannel *channel; ///<Underlying SSH channel
236  char_t rootDir[SFTP_SERVER_MAX_ROOT_DIR_LEN + 1]; ///<Root directory
237  char_t homeDir[SFTP_SERVER_MAX_HOME_DIR_LEN + 1]; ///<Home directory
238  uint32_t requestId; ///<Request identifier
239  error_t requestStatus; ///<Status of the request
240  FsFile *file; ///<File pointer
241  size_t dataLen; ///<Length of the data payload
242  uint8_t buffer[SFTP_SERVER_BUFFER_SIZE]; ///<Memory buffer for input/output operations
243  size_t bufferPos; ///<Current position in the buffer
244  size_t bufferLen; ///<Actual length of the buffer, in bytes
245  size_t totalLen;
246  uint32_t handle; ///<File or directory handle
247  SFTP_SERVER_SESSION_PRIVATE ///<Application specific context
248 };
249 
250 
251 /**
252  * @brief SFTP server context
253  **/
254 
256 {
257  SshServerContext *sshServerContext; ///<SSH server context
258  uint_t numSessions; ///<Maximum number of SFTP sessions
259  SftpServerSession *sessions; ///<SFTP sessions
260  uint_t numFileObjects; ///<Maximum number of file objects
261  SftpFileObject *fileObjects; ///<File objects
262  char_t rootDir[SFTP_SERVER_MAX_ROOT_DIR_LEN + 1]; ///<Root directory
263  SftpServerCheckUserCallback checkUserCallback; ///<User verification callback function
264  SftpServerGetFilePermCallback getFilePermCallback; ///<Callback used to retrieve file permissions
265  bool_t running; ///<Operational state of the FTP server
266  bool_t stop; ///<Stop request
267  OsEvent event; ///<Event object used to poll the channels
268  OsTaskParameters taskParams; ///<Task parameters
269  OsTaskId taskId; ///<Task identifier
270  SshChannelEventDesc eventDesc[SFTP_SERVER_MAX_SESSIONS]; ///<The events the application is interested in
272  SFTP_SERVER_CONTEXT_PRIVATE ///<Application specific context
273 };
274 
275 
276 //SFTP server related functions
278 
280  const SftpServerSettings *settings);
281 
284 
285 error_t sftpServerSetRootDir(SftpServerSession *session, const char_t *rootDir);
286 error_t sftpServerSetHomeDir(SftpServerSession *session, const char_t *homeDir);
287 
288 void sftpServerTask(void *param);
289 
290 void sftpServerDeinit(SftpServerContext *context);
291 
292 //C++ guard
293 #ifdef __cplusplus
294 }
295 #endif
296 
297 #endif
uint_t numSessions
Maximum number of SFTP sessions.
Definition: sftp_server.h:216
char_t path[SFTP_SERVER_MAX_PATH_LEN+1]
Path name.
Definition: sftp_server.h:271
SftpFileType
File types.
Definition: sftp_common.h:188
size_t dataLen
Length of the data payload.
Definition: sftp_server.h:241
int bool_t
Definition: compiler_port.h:63
#define SFTP_SERVER_BUFFER_SIZE
Definition: sftp_server.h:88
uint_t numSessions
Maximum number of SFTP sessions.
Definition: sftp_server.h:258
error_t sftpServerSetRootDir(SftpServerSession *session, const char_t *rootDir)
Set user's root directory.
Definition: sftp_server.c:297
SFtpFilePerm
File permissions.
Definition: sftp_server.h:154
OsTaskParameters task
Task parameters.
Definition: sftp_server.h:214
SftpServerSession * sessions
SFTP sessions.
Definition: sftp_server.h:259
SftpServerCheckUserCallback checkUserCallback
User verification callback function.
Definition: sftp_server.h:221
FsFile * file
File pointer.
Definition: sftp_server.h:203
Event object.
@ SFTP_SERVER_SESSION_STATE_RECEIVING_DATA
Definition: sftp_server.h:170
SftpAccessStatus(* SftpServerCheckUserCallback)(SftpServerSession *session, const char_t *user)
User verification callback function.
Definition: sftp_server.h:179
FsDir * dir
Directory pointer.
Definition: sftp_server.h:204
@ SFTP_ACCESS_DENIED
Definition: sftp_server.h:144
SftpServerSession * session
Pointer to the SFTP session.
Definition: sftp_server.h:198
SshServerContext * sshServerContext
SSH server context.
Definition: sftp_server.h:215
error_t sftpServerStop(SftpServerContext *context)
Stop SFTP server.
Definition: sftp_server.c:242
char_t rootDir[SFTP_SERVER_MAX_ROOT_DIR_LEN+1]
Root directory.
Definition: sftp_server.h:262
OsEvent event
Event object used to poll the channels.
Definition: sftp_server.h:267
SFTP server context.
Definition: sftp_server.h:256
Directory descriptor.
Definition: fs_port_posix.h:60
size_t bufferLen
Actual length of the buffer, in bytes.
Definition: sftp_server.h:244
#define SFTP_SERVER_CONTEXT_PRIVATE
Definition: sftp_server.h:116
SFTP server settings.
Definition: sftp_server.h:213
FsFile * file
File pointer.
Definition: sftp_server.h:240
@ SFTP_FILE_PERM_READ
Definition: sftp_server.h:156
size_t bufferPos
Current position in the buffer.
Definition: sftp_server.h:243
OsTaskParameters taskParams
Task parameters.
Definition: sftp_server.h:268
error_t
Error codes.
Definition: error.h:43
SftpFileType type
File type.
Definition: sftp_server.h:197
#define SFTP_SERVER_MAX_PATH_LEN
Definition: sftp_server.h:109
const char_t * rootDir
Root directory.
Definition: sftp_server.h:220
uint8_t buffer[SFTP_SERVER_BUFFER_SIZE]
Memory buffer for input/output operations.
Definition: sftp_server.h:242
#define SFTP_SERVER_SESSION_PRIVATE
Definition: sftp_server.h:121
uint64_t offset
Offset within the file.
Definition: sftp_server.h:202
SftpFileObject * fileObjects
File objects.
Definition: sftp_server.h:261
OsTaskId taskId
Task identifier.
Definition: sftp_server.h:269
#define SFTP_SERVER_MAX_ROOT_DIR_LEN
Definition: sftp_server.h:95
SftpServerSession * sessions
SFTP sessions.
Definition: sftp_server.h:217
SftpAccessStatus
Access status.
Definition: sftp_server.h:143
SftpVersion version
SFTP protocol version.
Definition: sftp_server.h:233
SFTP session.
Definition: sftp_server.h:231
SSH server context.
Definition: ssh_server.h:121
bool_t running
Operational state of the FTP server.
Definition: sftp_server.h:265
uint32_t requestId
Request identifier.
Definition: sftp_server.h:238
Task parameters.
bool_t stop
Stop request.
Definition: sftp_server.h:266
void sftpServerTask(void *param)
SFTP server task.
Definition: sftp_server.c:360
@ SFTP_SERVER_SESSION_STATE_SENDING_DATA
Definition: sftp_server.h:171
File or directory object.
Definition: sftp_server.h:196
uint32_t handle
File or directory handle.
Definition: sftp_server.h:246
error_t sftpServerStart(SftpServerContext *context)
Start SFTP server.
Definition: sftp_server.c:183
File system abstraction layer.
char_t rootDir[SFTP_SERVER_MAX_ROOT_DIR_LEN+1]
Root directory.
Definition: sftp_server.h:236
SftpServerSessionState state
Session state.
Definition: sftp_server.h:232
void sftpServerDeinit(SftpServerContext *context)
Release SFTP server context.
Definition: sftp_server.c:457
error_t requestStatus
Status of the request.
Definition: sftp_server.h:239
@ SFTP_SERVER_SESSION_STATE_CLOSED
Definition: sftp_server.h:167
char char_t
Definition: compiler_port.h:55
SftpServerContext * context
SFTP server context.
Definition: sftp_server.h:234
uint_t numFileObjects
Maximum number of file objects.
Definition: sftp_server.h:260
#define SFTP_SERVER_MAX_SESSIONS
Definition: sftp_server.h:60
uint_t(* SftpServerGetFilePermCallback)(SftpServerSession *session, const char_t *user, const char_t *path)
Callback used to retrieve file permissions.
Definition: sftp_server.h:187
Structure describing channel events.
Definition: ssh.h:1620
SftpServerSessionState
SFTP session state.
Definition: sftp_server.h:166
uint64_t size
Size of the file.
Definition: sftp_server.h:201
SftpServerCheckUserCallback checkUserCallback
User verification callback function.
Definition: sftp_server.h:263
SftpFileObject * fileObjects
File objects.
Definition: sftp_server.h:219
SSH server.
@ SFTP_FILE_PERM_LIST
Definition: sftp_server.h:155
SshChannel * channel
Underlying SSH channel.
Definition: sftp_server.h:235
error_t sftpServerSetHomeDir(SftpServerSession *session, const char_t *homeDir)
Set user's home directory.
Definition: sftp_server.c:331
SshServerContext * sshServerContext
SSH server context.
Definition: sftp_server.h:257
void sftpServerGetDefaultSettings(SftpServerSettings *settings)
Initialize settings with default values.
Definition: sftp_server.c:50
@ SFTP_ACCESS_ALLOWED
Definition: sftp_server.h:145
@ SFTP_SERVER_SESSION_STATE_RECEIVING
Definition: sftp_server.h:168
Definitions common to SFTP client and server.
SftpVersion
SFTP protocol version.
Definition: sftp_common.h:118
SftpServerGetFilePermCallback getFilePermCallback
Callback used to retrieve file permissions.
Definition: sftp_server.h:264
@ SFTP_FILE_PERM_WRITE
Definition: sftp_server.h:157
thread_t * OsTaskId
Task identifier.
SftpServerGetFilePermCallback getFilePermCallback
Callback used to retrieve file permissions.
Definition: sftp_server.h:222
#define SftpServerSession
Definition: sftp_server.h:130
unsigned int uint_t
Definition: compiler_port.h:57
#define SftpServerContext
Definition: sftp_server.h:126
uint32_t handle
Opaque value that identifies the file.
Definition: sftp_server.h:200
error_t sftpServerInit(SftpServerContext *context, const SftpServerSettings *settings)
Initialize SFTP server context.
Definition: sftp_server.c:85
SshChannelEventDesc eventDesc[SFTP_SERVER_MAX_SESSIONS]
The events the application is interested in.
Definition: sftp_server.h:270
uint_t numFileObjects
Maximum number of file objects.
Definition: sftp_server.h:218
@ SFTP_SERVER_SESSION_STATE_SENDING
Definition: sftp_server.h:169
#define SshChannel
Definition: ssh.h:939
#define SFTP_SERVER_MAX_HOME_DIR_LEN
Definition: sftp_server.h:102
void FsFile
File descriptor.
Definition: fs_port_fatfs.h:60
char_t homeDir[SFTP_SERVER_MAX_HOME_DIR_LEN+1]
Home directory.
Definition: sftp_server.h:237