lib/silcsftp/silcsftp_fs.h

   1 /*
   2
   3   silcsftp_fs.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2001 Pekka Riikonen
   8
   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.
  12
  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.
  17
  18 */
  19
  20 #ifndef SILCSFTP_FS_H
  21 #define SILCSFTP_FS_H
  22
  23 /****h* silcsftp/SilcSFTPFSAPI
  24  *
  25  * DESCRIPTION
  26  *
  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.
  30  *
  31  *    Currently only implemented filesystem is memory file system.
  32  *
  33  *    Memory Filesystem:
  34  *
  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://".
  45  *
  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.
  55  *
  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.
  65  *
  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.
  71  *
  72  *    The memory filesystem does not provide symbolic links.
  73  *
  74  ***/
  75
  76 /* Available filesystems. These can be given as argument to the
  77    silc_sftp_server_start function. */
  78 extern struct SilcSFTPFilesystemStruct silc_sftp_fs_memory;
  79
  80
  81 /* Memory filesystem */
  82
  83 /****d* silcsftp/SilcSFTPFSAPI/SilcSFTPFSMemoryPerm
  84  *
  85  * NAME
  86  *
  87  *    typedef enum { ... } SilcSFTPFSMemoryPerm;
  88  *
  89  * DESCRIPTION
  90  *
  91  *    Memory filesystem permission definition.  These enumerations can
  92  *    be used to set the permission mask for directories and files.
  93  *    The permissions behave in POSIX style.
  94  *
  95  * SOURCE
  96  */
  97 typedef enum {
  98   SILC_SFTP_FS_PERM_READ    = 0x0001,    /* Reading allowed */
  99   SILC_SFTP_FS_PERM_WRITE   = 0x0002,    /* Writing allowed */
 100   SILC_SFTP_FS_PERM_EXEC    = 0x0004,    /* Execution allowed */
 101 } SilcSFTPFSMemoryPerm;
 102 /***/
 103
 104 /****f* silcsftp/SilcSFTPFSAPI/silc_sftp_fs_memory_alloc
 105  *
 106  * SYNOPSIS
 107  *
 108  *    void *silc_sftp_fs_memory_alloc(SilcSFTPFSMemoryPerm perm);
 109  *
 110  * DESCRIPTION
 111  *
 112  *    Allocates memory filesystem context and returns the context.  The
 113  *    context can be given as argument to the silc_sftp_server_start
 114  *    function. The context must be freed by the caller using the function
 115  *    silc_sftp_fs_memory_free. The `perm' is the permissions for the root
 116  *    directory of the filesystem (/ dir).
 117  *
 118  ***/
 119 void *silc_sftp_fs_memory_alloc(SilcSFTPFSMemoryPerm perm);
 120
 121 /****f* silcsftp/SilcSFTPFSAPI/silc_sftp_fs_memory_free
 122  *
 123  * SYNOPSIS
 124  *
 125  *    void silc_sftp_fs_memory_free(void *context);
 126  *
 127  * DESCRIPTION
 128  *
 129  *    Frees the memory filesystem context.
 130  *
 131  ***/
 132 void silc_sftp_fs_memory_free(void *context);
 133
 134 /****f* silcsftp/SilcSFTPFSAPI/silc_sftp_fs_memory_add_dir
 135  *
 136  * SYNOPSIS
 137  *
 138  *    void *silc_sftp_fs_memory_add_dir(void *context, void *dir,
 139  *                                      SilcSFTPFSMemoryPerm perm,
 140  *                                      const char *name);
 141  *
 142  * DESCRIPTION
 143  *
 144  *    Adds a new directory to the memory filesystem. Returns the directory
 145  *    context that can be used to add for example files to the directory
 146  *    or new subdirectories under the directory. The `dir' is the parent
 147  *    directory of the directory to be added. If this directory is to be
 148  *    added to the root directory the `dir' is NULL.  The `name' is the name
 149  *    of the directory. If error occurs this returns NULL. The `perm' will
 150  *    indicate the permissions for the directory and they work in POSIX
 151  *    style.
 152  *
 153  ***/
 154 void *silc_sftp_fs_memory_add_dir(void *context, void *dir,
 155                                   SilcSFTPFSMemoryPerm perm,
 156                                   const char *name);
 157
 158 /****f* silcsftp/SilcSFTPFSAPI/silc_sftp_fs_memory_del_dir
 159  *
 160  * SYNOPSIS
 161  *
 162  *    bool silc_sftp_fs_memory_del_dir(void *context, void *dir);
 163  *
 164  * DESCRIPTION
 165  *
 166  *    Deletes a directory indicated by the `dir'. All files and
 167  *    subdirectories in this directory is also removed.  If the `dir' is
 168  *    NULL then all directories and files are removed from the filesystem.
 169  *    Returns TRUE if the removing was success. This is the only way to
 170  *    remove directories in memory file system. The filesystem does not
 171  *    allow removing directories with remote access using the filesystem
 172  *    access function sftp_rmdir.
 173  *
 174  ***/
 175 bool silc_sftp_fs_memory_del_dir(void *context, void *dir);
 176
 177 /****f* silcsftp/SilcSFTPFSAPI/silc_sftp_fs_memory_add_file
 178  *
 179  * SYNOPSIS
 180  *
 181  *    bool silc_sftp_fs_memory_add_file(void *context, void *dir,
 182  *                                      SilcSFTPFSMemoryPerm perm,
 183  *                                      const char *filename,
 184  *                                      const char *realpath);
 185  *
 186  * DESCRIPTION
 187  *
 188  *    Adds a new file to the directory indicated by the `dir'.  If the `dir'
 189  *    is NULL the file is added to the root directory. The `filename' is the
 190  *    filename in the directory. The `realpath' is the real filepath in the
 191  *    physical filesystem. The real path must include the schema to
 192  *    indicate where the file is actually located.  The only supported
 193  *    schema currently is "file://".  It is used to actually access the fil
 194  *    from the memory filesystem. The `perm' will indicate the permissions
 195  *    for the file and they work in POSIX style. Returns TRUE if the file
 196  *    was added to the directory.
 197  *
 198  ***/
 199 bool silc_sftp_fs_memory_add_file(void *context, void *dir,
 200                                   SilcSFTPFSMemoryPerm perm,
 201                                   const char *filename,
 202                                   const char *realpath);
 203
 204 /****f* silcsftp/SilcSFTPFSAPI/silc_sftp_fs_memory_del_file
 205  *
 206  * SYNOPSIS
 207  *
 208  *    bool silc_sftp_fs_memory_del_file(void *context, void *dir,
 209  *                                      const char *filename);
 210  *
 211  * DESCRIPTION
 212  *
 213  *    Removes a file indicated by the `filename' from the directory
 214  *    indicated by the `dir'. Returns TRUE if the removing was success. This
 215  *    is the only way to remove files in the filesystem.  The filesystem does
 216  *    not allow removing files with remote access using the filesystem
 217  *    access function sftp_remove.
 218  *
 219  ***/
 220 bool silc_sftp_fs_memory_del_file(void *context, void *dir,
 221                                   const char *filename);
 222
 223 #endif /* SILCSFTP_FS_H */