Package libssh2 :: Module session

[frames] | no frames]

# Source Code for Module libssh2.session

      1  #
      2  # pylibssh2 - python bindings for libssh2 library
      3  #
      4  # Copyright (C) 2010 Wallix Inc.
      5  #
      6  # This library is free software; you can redistribute it and/or modify it
      7  # under the terms of the GNU Lesser General Public License as published by the
      8  # Free Software Foundation; either version 2.1 of the License, or (at your
      9  # option) any later version.
     10  #
     11  # This library is distributed in the hope that it will be useful, but WITHOUT
     12  # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
     13  # FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
     14  # details.
     15  #
     16  # You should have received a copy of the GNU Lesser General Public License
     17  # along with this library; if not, write to the Free Software Foundation, Inc.,
     18  # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
     19  #
     20  """
     21  Abstraction for libssh2 L{Session} object
     22  """
     23
     24  import _libssh2
     25
     26  from channel import Channel
     27
     28 -class SessionException(Exception):
     29      """
     30      Exception raised when L{Session} actions fails.
     31      """
     32      pass
     33
     34 -class Session(object):
     35      """
     36      Session object
     37      """
     38 -    def __init__(self):
     39          """
     40          Create a new session object.
     41          """
     42          self._session = _libssh2.Session()
     43
     44 -    def callback_set(self, callback_type, callback):
     45          """
     46          Sets callback on the session.
     47
     48          @param callback_type: value of libssh2.LIBSSH2_CALLBACK_* constant
     49          @type callback_set: int
     50          @param callback: a callback Python object
     51          @type callback: function
     52          """
     53          self._session.callback_set(callback_type, callback)
     54
     55 -    def close(self, reason="Disconnect"):
     56          """
     57          Closes the session.
     58
     59          @param reason: human readable reason for disconnection
     60          @type reason: str
     61
     62          @return: 0 on success or negative on failure
     63          @rtype: int
     64          """
     65          self._session.close(reason)
     66
     67 -    def direct_tcpip(self, host, port, shost, sport):
     68          """
     69          Tunnels a TCP connection through the session.
     70
     71          @param host: remote host
     72          @type host: str
     73          @param port: remote port
     74          @type port: int
     75          @param shost: local host
     76          @type shost: str
     77          @param sport: local port
     78          @type sport: int
     79
     80          @return: new opened L{Channel}
     81          @rtype: L{Channel}
     82          """
     83          return self._session.direct_tcpip(host, port, shost, sport)
     84
     85 -    def forward_listen(self, host, port, bound_port, queue_maxsize):
     86          """
     87          Forwards a TCP connection through the session.
     88
     89          @param host: remote host
     90          @type host: str
     91          @param port: remote port
     92          @type port: int
     93          @param bound_port: populated with the actual port on the remote host
     94          @type bound_port: int
     95          @param queue_maxsize: maxium number of pending connections
     96          @type int
     97
     98          @return: new L{Listener} instance on success or None on failure
     99          @rtype: L{Listener}
    100          """
    101          return self._session.forward_listen(
    102              host, port, bound_port, queue_maxsize
    103          )
    104
    105 -    def hostkey_hash(self, hashtype):
    106          """
    107          Returns the computed digest of the remote host's key.
    108
    109          @param hashtype: values possible are 1 (HASH_MD5) or 2 (HASH_SHA1)
    110          @type hashtype: int
    111
    112          @return: string representation of the computed hash value
    113          @rtype: str
    114          """
    115          return self._session.hostkey_hash(hashtype)
    116
    117 -    def last_error(self):
    118          """
    119          Returns the last error in tuple format (code, message).
    120
    121          @return: error tuple (int, str)
    122          @rtype: tuple
    123          """
    124          return self._session.last_error()
    125
    126 -    def open_session(self):
    127          """
    128          Allocates a new L{Channel} for the session.
    129
    130          @return: new channel opened
    131          @rtype: L{Channel}
    132          """
    133          return Channel(self._session.open_session())
    134
    135
    136 -    def set_trace(self, bitmask):
    137          """
    138          Sets trace level on the session.
    139
    140          @param bitmask: bitmask on libssh2.LIBSSH2_TRACE_* constant
    141          """
    142          self._session.set_trace(bitmask)
    143
    144
    145 -    def scp_recv(self, remote_path):
    146          """
    147          Gets a remote file via SCP Protocol.
    148
    149          @param remote_path: absolute path of remote file to transfer
    150          @type remote_path: str
    151
    152          @return: new channel opened
    153          @rtype: L{Channel}
    154          """
    155          return Channel(self._session.scp_recv(remote_path))
    156
    157 -    def scp_send(self, path, mode, size):
    158          """
    159          Sends a file to remote host via SCP protocol.
    160
    161          @param path: absolute path of file to transfer
    162          @type path: str
    163          @param mode: file access mode to create file
    164          @type mode: int
    165          @param size: size of file being transmitted
    166          @type size: int
    167
    168          @return: new channel opened
    169          @rtype: L{Channel}
    170          """
    171          return Channel(self._session.scp_send(path, mode, size))
    172
    173 -    def session_method_pref(self, method_type, pref):
    174          """
    175          Sets preferred methods to be negociated. Theses preferences must be
    176          prior to calling L{startup}.
    177
    178          @param method_type: the method type constants
    179          @type method_type: int
    180          @param pref: coma delimited list of preferred methods
    181          @type pref: str
    182
    183          @return: 0 on success or negative on failure
    184          @rtype: int
    185          """
    186          self._session.session_methods(method_type, pref)
    187
    188 -    def session_methods(self):
    189          """
    190          Returns dictionnary with the current actives algorithms.
    191          CS keys is Client to Server and SC keys is Server to Client.
    192
    193          @return: dictionnary with actual method negociated
    194          @rtype: dict
    195          """
    196          return self.session_methods()
    197
    198 -    def set_banner(self, banner=_libssh2.DEFAULT_BANNER):
    199          """
    200          Sets the banner that will be sent to remote host. This is optional, the
    201          banner L{_libssh2.DEFAULT_BANNER} will be sent by default.
    202
    203          @param banner: an user defined banner
    204          @type banner: str
    205
    206          @return: 0 on success or negative on failure
    207          @rtype: int
    208          """
    209          self._session.set_banner(banner)
    210
    211 -    def sftp_init(self):
    212          """
    213          Open an Sftp Channel.
    214
    215          @return: new Sftp channel opened
    216          @rtype: L{Sftp}
    217          """
    218          raise NotImplementedError()
    219
    220 -    def startup(self, sock):
    221          """
    222          Starts up the session form a socket created by a socket.socket() call.
    223
    224          @param sock: a connected socket object
    225          @type sock: socket._socketobject
    226
    227          @return: 0 on success or negative on failure
    228          @rtype: int
    229          """
    230          self._session.startup(sock)
    231
    232 -    def userauth_authenticated(self):
    233          """
    234          Returns authentification status for the given session.
    235
    236          @return: non-zero if authenticated or 0 if not
    237          @rtype: int
    238          """
    239          return self._session.userauth_authenticated()
    240
    241 -    def userauth_list(self, username):
    242          """
    243          Lists the authentification methods supported by a server.
    244
    245          @param username: username which will be used while authenticating
    246          @type username: str
    247
    248          @return: string containing a comma-separated list of authentication
    249          methods
    250          @rtype: str
    251          """
    252          self._session.userauth_list(username)
    253
    254 -    def userauth_password(self, username, password):
    255          """
    256          Authenticates a session with the given username and password.
    257
    258          @param username: user to authenticate
    259          @type username: str
    260          @param password: password to use for the authentication
    261          @type password: str
    262
    263          @return: 0 on success or negative on failure
    264          @rtype: int
    265          """
    266          self._session.userauth_password(username, password)
    267
    268 -    def userauth_publickey_fromfile(
    269              self, username, publickey, privatekey, passphrase
    270          ):
    271          """
    272          Authenticates a session as username using a key pair found in the
    273          pulickey and privatekey files, and passphrase if provided.
    274
    275          @param username: user to authenticate
    276          @type username: str
    277          @param publickey: path and name of public key file
    278          @type publickey: str
    279          @param privatekey: path and name of private key file
    280          @type privatekey: str
    281          @param passphrase: passphrase to use when decoding private file
    282          @type passphrase: str
    283
    284          @return: 0 on success or negative on failure
    285          @rtype: int
    286          """
    287          raise NotImplementedError()
    288