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 /****s* silcsftp/SilcSFTPFSAPI/SilcSFTPFilesystemOps
  77  *
  78  * NAME
  79  *
  80  *    typedef struct SilcSFTPFilesystemOpsStruct { ... }
  81  *                     *SilcSFTPFilesystemOps;
  82  *
  83  * DESCRIPTION
  84  *
  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.
  90  *
  91  * SOURCE
  92  */
  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,
  98                                     SilcUInt32 data_len);
  99
 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);
 105
 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);
 115
 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);
 122
 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,
 128                     SilcUInt64 offset,
 129                     SilcUInt32 len,
 130                     SilcSFTPDataCallback callback,
 131                     void *callback_context);
 132
 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,
 138                      SilcUInt64 offset,
 139                      const unsigned char *data,
 140                      SilcUInt32 data_len,
 141                      SilcSFTPStatusCallback callback,
 142                      void *callback_context);
 143
 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);
 150
 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,
 154                       const char *oldname,
 155                       const char *newname,
 156                       SilcSFTPStatusCallback callback,
 157                       void *callback_context);
 158
 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
 161      creation. */
 162   void (*sftp_mkdir)(void *context, SilcSFTP sftp,
 163                      const char *path,
 164                      SilcSFTPAttributes attrs,
 165                      SilcSFTPStatusCallback callback,
 166                      void *callback_context);
 167
 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,
 171                      const char *path,
 172                      SilcSFTPStatusCallback callback,
 173                      void *callback_context);
 174
 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,
 178                        const char *path,
 179                        SilcSFTPHandleCallback callback,
 180                        void *callback_context);
 181
 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);
 188
 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
 191      file attributes. */
 192   void (*sftp_stat)(void *context, SilcSFTP sftp,
 193                     const char *path,
 194                     SilcSFTPAttrCallback callback,
 195                     void *callback_context);
 196
 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
 199      file attributes. */
 200   void (*sftp_lstat)(void *context, SilcSFTP sftp,
 201                      const char *path,
 202                      SilcSFTPAttrCallback callback,
 203                      void *callback_context);
 204
 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);
 211
 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,
 216                        const char *path,
 217                        SilcSFTPAttributes attrs,
 218                        SilcSFTPStatusCallback callback,
 219                        void *callback_context);
 220
 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);
 229
 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,
 233                         const char *path,
 234                         SilcSFTPNameCallback callback,
 235                         void *callback_context);
 236
 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);
 245
 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,
 249                         const char *path,
 250                         SilcSFTPNameCallback callback,
 251                         void *callback_context);
 252
 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,
 257                         const char *request,
 258                         const unsigned char *data,
 259                         SilcUInt32 data_len,
 260                         SilcSFTPExtendedCallback callback,
 261                         void *callback_context);
 262 } *SilcSFTPFilesystemOps;
 263 /****/
 264
 265 /****s* silcsftp/SilcSFTPFSAPI/SilcSFTPFilesystem
 266  *
 267  * NAME
 268  *
 269  *    typedef struct { ... } *SilcSFTPFilesystem;
 270  *
 271  * DESCRIPTION
 272  *
 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.
 277  *
 278  * SOURCE
 279  */
 280 typedef struct {
 281   SilcSFTPFilesystemOps fs;
 282   void *fs_context;
 283 } *SilcSFTPFilesystem;
 284 /***/
 285
 286 /* Memory filesystem */
 287
 288 /****d* silcsftp/SilcSFTPFSAPI/SilcSFTPFSMemoryPerm
 289  *
 290  * NAME
 291  *
 292  *    typedef enum { ... } SilcSFTPFSMemoryPerm;
 293  *
 294  * DESCRIPTION
 295  *
 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.
 299  *
 300  * SOURCE
 301  */
 302 typedef enum {
 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;
 307 /***/
 308
 309 /****f* silcsftp/SilcSFTPFSAPI/silc_sftp_fs_memory_alloc
 310  *
 311  * SYNOPSIS
 312  *
 313  *    void *silc_sftp_fs_memory_alloc(SilcSFTPFSMemoryPerm perm);
 314  *
 315  * DESCRIPTION
 316  *
 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).
 322  *
 323  ***/
 324 SilcSFTPFilesystem silc_sftp_fs_memory_alloc(SilcSFTPFSMemoryPerm perm);
 325
 326 /****f* silcsftp/SilcSFTPFSAPI/silc_sftp_fs_memory_free
 327  *
 328  * SYNOPSIS
 329  *
 330  *    void silc_sftp_fs_memory_free(void *context);
 331  *
 332  * DESCRIPTION
 333  *
 334  *    Frees the memory filesystem context.
 335  *
 336  ***/
 337 void silc_sftp_fs_memory_free(SilcSFTPFilesystem fs);
 338
 339 /****f* silcsftp/SilcSFTPFSAPI/silc_sftp_fs_memory_add_dir
 340  *
 341  * SYNOPSIS
 342  *
 343  *    void *silc_sftp_fs_memory_add_dir(void *context, void *dir,
 344  *                                      SilcSFTPFSMemoryPerm perm,
 345  *                                      const char *name);
 346  *
 347  * DESCRIPTION
 348  *
 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
 356  *    style.
 357  *
 358  ***/
 359 void *silc_sftp_fs_memory_add_dir(SilcSFTPFilesystem fs, void *dir,
 360                                   SilcSFTPFSMemoryPerm perm,
 361                                   const char *name);
 362
 363 /****f* silcsftp/SilcSFTPFSAPI/silc_sftp_fs_memory_del_dir
 364  *
 365  * SYNOPSIS
 366  *
 367  *    bool silc_sftp_fs_memory_del_dir(SilcSFTPFilesystem fs, void *dir);
 368  *
 369  * DESCRIPTION
 370  *
 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.
 378  *
 379  ***/
 380 bool silc_sftp_fs_memory_del_dir(SilcSFTPFilesystem fs, void *dir);
 381
 382 /****f* silcsftp/SilcSFTPFSAPI/silc_sftp_fs_memory_add_file
 383  *
 384  * SYNOPSIS
 385  *
 386  *    bool silc_sftp_fs_memory_add_file(SilcSFTPFilesystem fs, void *dir,
 387  *                                      SilcSFTPFSMemoryPerm perm,
 388  *                                      const char *filename,
 389  *                                      const char *realpath);
 390  *
 391  * DESCRIPTION
 392  *
 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.
 402  *
 403  ***/
 404 bool silc_sftp_fs_memory_add_file(SilcSFTPFilesystem fs, void *dir,
 405                                   SilcSFTPFSMemoryPerm perm,
 406                                   const char *filename,
 407                                   const char *realpath);
 408
 409 /****f* silcsftp/SilcSFTPFSAPI/silc_sftp_fs_memory_del_file
 410  *
 411  * SYNOPSIS
 412  *
 413  *    bool silc_sftp_fs_memory_del_file(SilcSFTPFilesystem fs, void *dir,
 414  *                                      const char *filename);
 415  *
 416  * DESCRIPTION
 417  *
 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.
 423  *
 424  ***/
 425 bool silc_sftp_fs_memory_del_file(SilcSFTPFilesystem fs, void *dir,
 426                                   const char *filename);
 427
 428 #endif /* SILCSFTP_FS_H */