sftp_si.py 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316
  1. # Copyright (C) 2003-2007 Robey Pointer <robeypointer@gmail.com>
  2. #
  3. # This file is part of paramiko.
  4. #
  5. # Paramiko is free software; you can redistribute it and/or modify it under the
  6. # terms of the GNU Lesser General Public License as published by the Free
  7. # Software Foundation; either version 2.1 of the License, or (at your option)
  8. # any later version.
  9. #
  10. # Paramiko is distributed in the hope that it will be useful, but WITHOUT ANY
  11. # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  12. # A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
  13. # details.
  14. #
  15. # You should have received a copy of the GNU Lesser General Public License
  16. # along with Paramiko; if not, write to the Free Software Foundation, Inc.,
  17. # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  18. """
  19. An interface to override for SFTP server support.
  20. """
  21. import os
  22. import sys
  23. from paramiko.sftp import SFTP_OP_UNSUPPORTED
  24. class SFTPServerInterface(object):
  25. """
  26. This class defines an interface for controlling the behavior of paramiko
  27. when using the `.SFTPServer` subsystem to provide an SFTP server.
  28. Methods on this class are called from the SFTP session's thread, so you can
  29. block as long as necessary without affecting other sessions (even other
  30. SFTP sessions). However, raising an exception will usually cause the SFTP
  31. session to abruptly end, so you will usually want to catch exceptions and
  32. return an appropriate error code.
  33. All paths are in string form instead of unicode because not all SFTP
  34. clients & servers obey the requirement that paths be encoded in UTF-8.
  35. """
  36. def __init__(self, server, *largs, **kwargs):
  37. """
  38. Create a new SFTPServerInterface object. This method does nothing by
  39. default and is meant to be overridden by subclasses.
  40. :param .ServerInterface server:
  41. the server object associated with this channel and SFTP subsystem
  42. """
  43. super(SFTPServerInterface, self).__init__(*largs, **kwargs)
  44. def session_started(self):
  45. """
  46. The SFTP server session has just started. This method is meant to be
  47. overridden to perform any necessary setup before handling callbacks
  48. from SFTP operations.
  49. """
  50. pass
  51. def session_ended(self):
  52. """
  53. The SFTP server session has just ended, either cleanly or via an
  54. exception. This method is meant to be overridden to perform any
  55. necessary cleanup before this `.SFTPServerInterface` object is
  56. destroyed.
  57. """
  58. pass
  59. def open(self, path, flags, attr):
  60. """
  61. Open a file on the server and create a handle for future operations
  62. on that file. On success, a new object subclassed from `.SFTPHandle`
  63. should be returned. This handle will be used for future operations
  64. on the file (read, write, etc). On failure, an error code such as
  65. ``SFTP_PERMISSION_DENIED`` should be returned.
  66. ``flags`` contains the requested mode for opening (read-only,
  67. write-append, etc) as a bitset of flags from the ``os`` module:
  68. - ``os.O_RDONLY``
  69. - ``os.O_WRONLY``
  70. - ``os.O_RDWR``
  71. - ``os.O_APPEND``
  72. - ``os.O_CREAT``
  73. - ``os.O_TRUNC``
  74. - ``os.O_EXCL``
  75. (One of ``os.O_RDONLY``, ``os.O_WRONLY``, or ``os.O_RDWR`` will always
  76. be set.)
  77. The ``attr`` object contains requested attributes of the file if it
  78. has to be created. Some or all attribute fields may be missing if
  79. the client didn't specify them.
  80. .. note:: The SFTP protocol defines all files to be in "binary" mode.
  81. There is no equivalent to Python's "text" mode.
  82. :param str path:
  83. the requested path (relative or absolute) of the file to be opened.
  84. :param int flags:
  85. flags or'd together from the ``os`` module indicating the requested
  86. mode for opening the file.
  87. :param .SFTPAttributes attr:
  88. requested attributes of the file if it is newly created.
  89. :return: a new `.SFTPHandle` or error code.
  90. """
  91. return SFTP_OP_UNSUPPORTED
  92. def list_folder(self, path):
  93. """
  94. Return a list of files within a given folder. The ``path`` will use
  95. posix notation (``"/"`` separates folder names) and may be an absolute
  96. or relative path.
  97. The list of files is expected to be a list of `.SFTPAttributes`
  98. objects, which are similar in structure to the objects returned by
  99. ``os.stat``. In addition, each object should have its ``filename``
  100. field filled in, since this is important to a directory listing and
  101. not normally present in ``os.stat`` results. The method
  102. `.SFTPAttributes.from_stat` will usually do what you want.
  103. In case of an error, you should return one of the ``SFTP_*`` error
  104. codes, such as ``SFTP_PERMISSION_DENIED``.
  105. :param str path: the requested path (relative or absolute) to be
  106. listed.
  107. :return:
  108. a list of the files in the given folder, using `.SFTPAttributes`
  109. objects.
  110. .. note::
  111. You should normalize the given ``path`` first (see the `os.path`
  112. module) and check appropriate permissions before returning the list
  113. of files. Be careful of malicious clients attempting to use
  114. relative paths to escape restricted folders, if you're doing a
  115. direct translation from the SFTP server path to your local
  116. filesystem.
  117. """
  118. return SFTP_OP_UNSUPPORTED
  119. def stat(self, path):
  120. """
  121. Return an `.SFTPAttributes` object for a path on the server, or an
  122. error code. If your server supports symbolic links (also known as
  123. "aliases"), you should follow them. (`lstat` is the corresponding
  124. call that doesn't follow symlinks/aliases.)
  125. :param str path:
  126. the requested path (relative or absolute) to fetch file statistics
  127. for.
  128. :return:
  129. an `.SFTPAttributes` object for the given file, or an SFTP error
  130. code (like ``SFTP_PERMISSION_DENIED``).
  131. """
  132. return SFTP_OP_UNSUPPORTED
  133. def lstat(self, path):
  134. """
  135. Return an `.SFTPAttributes` object for a path on the server, or an
  136. error code. If your server supports symbolic links (also known as
  137. "aliases"), you should not follow them -- instead, you should
  138. return data on the symlink or alias itself. (`stat` is the
  139. corresponding call that follows symlinks/aliases.)
  140. :param str path:
  141. the requested path (relative or absolute) to fetch file statistics
  142. for.
  143. :type path: str
  144. :return:
  145. an `.SFTPAttributes` object for the given file, or an SFTP error
  146. code (like ``SFTP_PERMISSION_DENIED``).
  147. """
  148. return SFTP_OP_UNSUPPORTED
  149. def remove(self, path):
  150. """
  151. Delete a file, if possible.
  152. :param str path:
  153. the requested path (relative or absolute) of the file to delete.
  154. :return: an SFTP error code `int` like ``SFTP_OK``.
  155. """
  156. return SFTP_OP_UNSUPPORTED
  157. def rename(self, oldpath, newpath):
  158. """
  159. Rename (or move) a file. The SFTP specification implies that this
  160. method can be used to move an existing file into a different folder,
  161. and since there's no other (easy) way to move files via SFTP, it's
  162. probably a good idea to implement "move" in this method too, even for
  163. files that cross disk partition boundaries, if at all possible.
  164. .. note:: You should return an error if a file with the same name as
  165. ``newpath`` already exists. (The rename operation should be
  166. non-desctructive.)
  167. .. note::
  168. This method implements 'standard' SFTP ``RENAME`` behavior; those
  169. seeking the OpenSSH "POSIX rename" extension behavior should use
  170. `posix_rename`.
  171. :param str oldpath:
  172. the requested path (relative or absolute) of the existing file.
  173. :param str newpath: the requested new path of the file.
  174. :return: an SFTP error code `int` like ``SFTP_OK``.
  175. """
  176. return SFTP_OP_UNSUPPORTED
  177. def posix_rename(self, oldpath, newpath):
  178. """
  179. Rename (or move) a file, following posix conventions. If newpath
  180. already exists, it will be overwritten.
  181. :param str oldpath:
  182. the requested path (relative or absolute) of the existing file.
  183. :param str newpath: the requested new path of the file.
  184. :return: an SFTP error code `int` like ``SFTP_OK``.
  185. :versionadded: 2.2
  186. """
  187. return SFTP_OP_UNSUPPORTED
  188. def mkdir(self, path, attr):
  189. """
  190. Create a new directory with the given attributes. The ``attr``
  191. object may be considered a "hint" and ignored.
  192. The ``attr`` object will contain only those fields provided by the
  193. client in its request, so you should use ``hasattr`` to check for
  194. the presence of fields before using them. In some cases, the ``attr``
  195. object may be completely empty.
  196. :param str path:
  197. requested path (relative or absolute) of the new folder.
  198. :param .SFTPAttributes attr: requested attributes of the new folder.
  199. :return: an SFTP error code `int` like ``SFTP_OK``.
  200. """
  201. return SFTP_OP_UNSUPPORTED
  202. def rmdir(self, path):
  203. """
  204. Remove a directory if it exists. The ``path`` should refer to an
  205. existing, empty folder -- otherwise this method should return an
  206. error.
  207. :param str path:
  208. requested path (relative or absolute) of the folder to remove.
  209. :return: an SFTP error code `int` like ``SFTP_OK``.
  210. """
  211. return SFTP_OP_UNSUPPORTED
  212. def chattr(self, path, attr):
  213. """
  214. Change the attributes of a file. The ``attr`` object will contain
  215. only those fields provided by the client in its request, so you
  216. should check for the presence of fields before using them.
  217. :param str path:
  218. requested path (relative or absolute) of the file to change.
  219. :param attr:
  220. requested attributes to change on the file (an `.SFTPAttributes`
  221. object)
  222. :return: an error code `int` like ``SFTP_OK``.
  223. """
  224. return SFTP_OP_UNSUPPORTED
  225. def canonicalize(self, path):
  226. """
  227. Return the canonical form of a path on the server. For example,
  228. if the server's home folder is ``/home/foo``, the path
  229. ``"../betty"`` would be canonicalized to ``"/home/betty"``. Note
  230. the obvious security issues: if you're serving files only from a
  231. specific folder, you probably don't want this method to reveal path
  232. names outside that folder.
  233. You may find the Python methods in ``os.path`` useful, especially
  234. ``os.path.normpath`` and ``os.path.realpath``.
  235. The default implementation returns ``os.path.normpath('/' + path)``.
  236. """
  237. if os.path.isabs(path):
  238. out = os.path.normpath(path)
  239. else:
  240. out = os.path.normpath("/" + path)
  241. if sys.platform == "win32":
  242. # on windows, normalize backslashes to sftp/posix format
  243. out = out.replace("\\", "/")
  244. return out
  245. def readlink(self, path):
  246. """
  247. Return the target of a symbolic link (or shortcut) on the server.
  248. If the specified path doesn't refer to a symbolic link, an error
  249. should be returned.
  250. :param str path: path (relative or absolute) of the symbolic link.
  251. :return:
  252. the target `str` path of the symbolic link, or an error code like
  253. ``SFTP_NO_SUCH_FILE``.
  254. """
  255. return SFTP_OP_UNSUPPORTED
  256. def symlink(self, target_path, path):
  257. """
  258. Create a symbolic link on the server, as new pathname ``path``,
  259. with ``target_path`` as the target of the link.
  260. :param str target_path:
  261. path (relative or absolute) of the target for this new symbolic
  262. link.
  263. :param str path:
  264. path (relative or absolute) of the symbolic link to create.
  265. :return: an error code `int` like ``SFTP_OK``.
  266. """
  267. return SFTP_OP_UNSUPPORTED