5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2001 Pekka Riikonen
9 This program is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; version 2 of the License.
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
23 /****h* silcsftp/SilcSFTPFSAPI
27 * SILC SFTP Filesystem interface defines filesystems for the SFTP server
28 * usage. The filesystems may be for example virtual memory filesystem
29 * or real filesystem access.
31 * Currently only implemented filesystem is memory file system.
35 * Memory filesystem is a virtual filesystem which provides safe access
36 * to files without actually revealing the underlaying physical filesystem
37 * hierarchy or real filenames. Virtual directories can be added to the
38 * filesystem and freely create filesystem hierarchy. The directories
39 * can have subdirectories and files. The filesystem also provides limited
40 * status information for files. The files in the filesystem are
41 * virtual but they include the path to the real file. The real path
42 * includes always a schema which indicates where the file really is
43 * available. The only supported schema currently is "file://". In
44 * the future it could support various others like "http://" and "ldap://".
46 * The filesystem also provides security and permission handling for
47 * directories and files. Normal POSIX style permissions can be set
48 * giving thus rights to reading, writing and/or executing. They behave
49 * same way as defined in POSIX. It is also guaranteed that if the
50 * writing to a file is not allowed in the memory filesystem, but it is
51 * allowed in real physical filesystem the file still cannot be written.
52 * However, the real physical filesystem permissions still matter, for
53 * example if writing is enabled in the memory filesystem but it is not
54 * enabled on physical filesystem, the file cannot be written.
56 * The directories cannot be removed from remote access using the
57 * filesystem access function sftp_rmdir. This is because the filesystem
58 * is one-user filesystem and differentiating between users is not
59 * possible. Thus, it would allow anyone to remove directories and
60 * their contents. Removing directories is possible only locally using
61 * the silc_sftp_fs_memory_del_dir function. The same thing is with
62 * removing files as well. Files too can be removed only locally using
63 * the silc_sftp_fs_memory_del_file function. Also, files can not ever
64 * be executed from remote access.
66 * Also some of the file operation flags are not supported, such as
67 * SILC_SFTP_FXF_CREAT, SILC_SFTP_FXF_TRUNC and SILC_SFTP_FXF_EXCL
68 * since they would require access to a real filesystem file which does
69 * not exist yet, or would mean destroying the file. However, the
70 * SILC_SFTP_FXF_WRITE is supported since the file aready exists.
72 * The memory filesystem does not provide symbolic links.
76 /****s* silcsftp/SilcSFTPFSAPI/SilcSFTPFilesystemOps
80 * typedef struct SilcSFTPFilesystemOpsStruct { ... }
81 * *SilcSFTPFilesystemOps;
85 * This structure defines the generic filesystem access. When the
86 * filesystem is accessed these functions are called to do the requested
87 * filesystem operation. The level that implements the actual filesystem
88 * must fill this structure with the callback functions providing the
89 * access to the filesystem.
93 typedef struct SilcSFTPFilesystemOpsStruct {
94 /* Find a file handle by the file handle data indicated by the `data'.
95 If the handle is not found this returns NULL. */
96 SilcSFTPHandle (*sftp_get_handle)(void *context, SilcSFTP sftp,
97 const unsigned char *data,
100 /* Return encoded handle of `handle' or NULL on error. The caller
101 must free the returned buffer. */
102 unsigned char *(*sftp_encode_handle)(void *context, SilcSFTP sftp,
103 SilcSFTPHandle handle,
104 SilcUInt32 *handle_len);
106 /* Open a file indicated by the `filename' with flags indicated by the
107 `pflags', and with attributes indicated by the `attr'. Calls the
108 `callback' to return the opened file handle. */
109 void (*sftp_open)(void *context, SilcSFTP sftp,
110 const char *filename,
111 SilcSFTPFileOperation pflags,
112 SilcSFTPAttributes attr,
113 SilcSFTPHandleCallback callback,
114 void *callback_context);
116 /* Closes the file indicated by the file handle `handle'. Calls the
117 `callback' to indicate the status of the closing. */
118 void (*sftp_close)(void *context, SilcSFTP sftp,
119 SilcSFTPHandle handle,
120 SilcSFTPStatusCallback callback,
121 void *callback_context);
123 /* Reads data from the file indicated by the file handle `handle' starting
124 from the offset of `offset' at most `len' bytes. The `callback' is
125 called to return the read data. */
126 void (*sftp_read)(void *context, SilcSFTP sftp,
127 SilcSFTPHandle handle,
130 SilcSFTPDataCallback callback,
131 void *callback_context);
133 /* Writes to a file indicated by the file handle `handle' starting from
134 offset of `offset' at most `data_len' bytes of `data'. The `callback'
135 is called to indicate the status of the writing. */
136 void (*sftp_write)(void *context, SilcSFTP sftp,
137 SilcSFTPHandle handle,
139 const unsigned char *data,
141 SilcSFTPStatusCallback callback,
142 void *callback_context);
144 /* Removes a file indicated by the `filename'. Calls the `callback'
145 to indicate the status of the removing. */
146 void (*sftp_remove)(void *context, SilcSFTP sftp,
147 const char *filename,
148 SilcSFTPStatusCallback callback,
149 void *callback_context);
151 /* Renames a file indicated by the `oldname' to the name `newname'. The
152 `callback' is called to indicate the status of the renaming. */
153 void (*sftp_rename)(void *context, SilcSFTP sftp,
156 SilcSFTPStatusCallback callback,
157 void *callback_context);
159 /* Creates a new directory indicated by the `path' with attributes indicated
160 by the `attrs'. The `callback' is called to indicate the status of the
162 void (*sftp_mkdir)(void *context, SilcSFTP sftp,
164 SilcSFTPAttributes attrs,
165 SilcSFTPStatusCallback callback,
166 void *callback_context);
168 /* Removes a directory indicated by the `path' and calls the `callback'
169 to indicate the status of the removal. */
170 void (*sftp_rmdir)(void *context, SilcSFTP sftp,
172 SilcSFTPStatusCallback callback,
173 void *callback_context);
175 /* Opens a directory indicated by the `path'. The `callback' is called
176 to return the opened file handle. */
177 void (*sftp_opendir)(void *context, SilcSFTP sftp,
179 SilcSFTPHandleCallback callback,
180 void *callback_context);
182 /* Reads the contents of the directory indicated by the `handle' and
183 calls the `callback' to return the read file(s) from the directory. */
184 void (*sftp_readdir)(void *context, SilcSFTP sftp,
185 SilcSFTPHandle handle,
186 SilcSFTPNameCallback callback,
187 void *callback_context);
189 /* Gets the file attributes for a file indicated by the `path'. This
190 will follow symbolic links also. Calls the `callback' to return the
192 void (*sftp_stat)(void *context, SilcSFTP sftp,
194 SilcSFTPAttrCallback callback,
195 void *callback_context);
197 /* Gets the file attributes for a file indicated by the `path'. This
198 will not follow symbolic links. Calls the `callback' to return the
200 void (*sftp_lstat)(void *context, SilcSFTP sftp,
202 SilcSFTPAttrCallback callback,
203 void *callback_context);
205 /* Gets a file attributes for a opened file indicated by the `handle'.
206 Calls the `callback' to return the file attributes. */
207 void (*sftp_fstat)(void *context, SilcSFTP sftp,
208 SilcSFTPHandle handle,
209 SilcSFTPAttrCallback callback,
210 void *callback_context);
212 /* Sets a file attributes to a file indicated by the `path' with the
213 attributes indicated by the `attrs'. Calls the `callback' to indicate
214 the status of the setting. */
215 void (*sftp_setstat)(void *context, SilcSFTP sftp,
217 SilcSFTPAttributes attrs,
218 SilcSFTPStatusCallback callback,
219 void *callback_context);
221 /* Sets a file attributes to a opened file indicated by the `handle' with
222 the attributes indicated by the `attrs'. Calls the `callback' to
223 indicate the status of the setting. */
224 void (*sftp_fsetstat)(void *context, SilcSFTP sftp,
225 SilcSFTPHandle handle,
226 SilcSFTPAttributes attrs,
227 SilcSFTPStatusCallback callback,
228 void *callback_context);
230 /* Reads the target of a symbolic link indicated by the `path'. The
231 `callback' is called to return the target of the symbolic link. */
232 void (*sftp_readlink)(void *context, SilcSFTP sftp,
234 SilcSFTPNameCallback callback,
235 void *callback_context);
237 /* Creates a new symbolic link indicated by the `linkpath' to the target
238 indicated by the `targetpath'. The `callback' is called to indicate
239 the status of creation. */
240 void (*sftp_symlink)(void *context, SilcSFTP sftp,
241 const char *linkpath,
242 const char *targetpath,
243 SilcSFTPStatusCallback callback,
244 void *callback_context);
246 /* Canonicalizes the path indicated by the `path' to a absolute path.
247 The `callback' is called to return the absolute path. */
248 void (*sftp_realpath)(void *context, SilcSFTP sftp,
250 SilcSFTPNameCallback callback,
251 void *callback_context);
253 /* Performs an extended operation indicated by the `request' with
254 optional extended operation data indicated by the `data'. The callback
255 is called to return any data associated with the extended request. */
256 void (*sftp_extended)(void *context, SilcSFTP sftp,
258 const unsigned char *data,
260 SilcSFTPExtendedCallback callback,
261 void *callback_context);
262 } *SilcSFTPFilesystemOps;
265 /****s* silcsftp/SilcSFTPFSAPI/SilcSFTPFilesystem
269 * typedef struct { ... } *SilcSFTPFilesystem;
273 * This context is allocated and returned by all filesystem allocation
274 * routines. The returned context is given as argument to the
275 * silc_sftp_server_start function. The caller must also free the
276 * context after the SFTP server is shutdown.
281 SilcSFTPFilesystemOps fs;
283 } *SilcSFTPFilesystem;
286 /* Memory filesystem */
288 /****d* silcsftp/SilcSFTPFSAPI/SilcSFTPFSMemoryPerm
292 * typedef enum { ... } SilcSFTPFSMemoryPerm;
296 * Memory filesystem permission definition. These enumerations can
297 * be used to set the permission mask for directories and files.
298 * The permissions behave in POSIX style.
303 SILC_SFTP_FS_PERM_READ = 0x0001, /* Reading allowed */
304 SILC_SFTP_FS_PERM_WRITE = 0x0002, /* Writing allowed */
305 SILC_SFTP_FS_PERM_EXEC = 0x0004, /* Execution allowed */
306 } SilcSFTPFSMemoryPerm;
309 /****f* silcsftp/SilcSFTPFSAPI/silc_sftp_fs_memory_alloc
313 * void *silc_sftp_fs_memory_alloc(SilcSFTPFSMemoryPerm perm);
317 * Allocates memory filesystem context and returns the context. The
318 * context can be given as argument to the silc_sftp_server_start
319 * function. The context must be freed by the caller using the function
320 * silc_sftp_fs_memory_free. The `perm' is the permissions for the root
321 * directory of the filesystem (/ dir).
324 SilcSFTPFilesystem silc_sftp_fs_memory_alloc(SilcSFTPFSMemoryPerm perm);
326 /****f* silcsftp/SilcSFTPFSAPI/silc_sftp_fs_memory_free
330 * void silc_sftp_fs_memory_free(void *context);
334 * Frees the memory filesystem context.
337 void silc_sftp_fs_memory_free(SilcSFTPFilesystem fs);
339 /****f* silcsftp/SilcSFTPFSAPI/silc_sftp_fs_memory_add_dir
343 * void *silc_sftp_fs_memory_add_dir(void *context, void *dir,
344 * SilcSFTPFSMemoryPerm perm,
349 * Adds a new directory to the memory filesystem. Returns the directory
350 * context that can be used to add for example files to the directory
351 * or new subdirectories under the directory. The `dir' is the parent
352 * directory of the directory to be added. If this directory is to be
353 * added to the root directory the `dir' is NULL. The `name' is the name
354 * of the directory. If error occurs this returns NULL. The `perm' will
355 * indicate the permissions for the directory and they work in POSIX
359 void *silc_sftp_fs_memory_add_dir(SilcSFTPFilesystem fs, void *dir,
360 SilcSFTPFSMemoryPerm perm,
363 /****f* silcsftp/SilcSFTPFSAPI/silc_sftp_fs_memory_del_dir
367 * bool silc_sftp_fs_memory_del_dir(SilcSFTPFilesystem fs, void *dir);
371 * Deletes a directory indicated by the `dir'. All files and
372 * subdirectories in this directory is also removed. If the `dir' is
373 * NULL then all directories and files are removed from the filesystem.
374 * Returns TRUE if the removing was success. This is the only way to
375 * remove directories in memory file system. The filesystem does not
376 * allow removing directories with remote access using the filesystem
377 * access function sftp_rmdir.
380 bool silc_sftp_fs_memory_del_dir(SilcSFTPFilesystem fs, void *dir);
382 /****f* silcsftp/SilcSFTPFSAPI/silc_sftp_fs_memory_add_file
386 * bool silc_sftp_fs_memory_add_file(SilcSFTPFilesystem fs, void *dir,
387 * SilcSFTPFSMemoryPerm perm,
388 * const char *filename,
389 * const char *realpath);
393 * Adds a new file to the directory indicated by the `dir'. If the `dir'
394 * is NULL the file is added to the root directory. The `filename' is the
395 * filename in the directory. The `realpath' is the real filepath in the
396 * physical filesystem. The real path must include the schema to
397 * indicate where the file is actually located. The only supported
398 * schema currently is "file://". It is used to actually access the fil
399 * from the memory filesystem. The `perm' will indicate the permissions
400 * for the file and they work in POSIX style. Returns TRUE if the file
401 * was added to the directory.
404 bool silc_sftp_fs_memory_add_file(SilcSFTPFilesystem fs, void *dir,
405 SilcSFTPFSMemoryPerm perm,
406 const char *filename,
407 const char *realpath);
409 /****f* silcsftp/SilcSFTPFSAPI/silc_sftp_fs_memory_del_file
413 * bool silc_sftp_fs_memory_del_file(SilcSFTPFilesystem fs, void *dir,
414 * const char *filename);
418 * Removes a file indicated by the `filename' from the directory
419 * indicated by the `dir'. Returns TRUE if the removing was success. This
420 * is the only way to remove files in the filesystem. The filesystem does
421 * not allow removing files with remote access using the filesystem
422 * access function sftp_remove.
425 bool silc_sftp_fs_memory_del_file(SilcSFTPFilesystem fs, void *dir,
426 const char *filename);
428 #endif /* SILCSFTP_FS_H */