dorian
/
paramiko
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Transport info fields cleanup.

This commit is contained in:
Jeff Forcier 2014-02-26 18:48:28 -08:00
parent 9c3f2c2122
commit 5ee1fb4781
1 changed files with 112 additions and 147 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

259
paramiko/transport.py
View File

@ -150,7 +150,8 @@ class Transport (threading.Thread):
address and used for communication. Exceptions from the ``socket`` address and used for communication. Exceptions from the ``socket``
call may be thrown in this case. call may be thrown in this case.
:param socket sock: a socket or socket-like object to create the session over. :param socket sock:
a socket or socket-like object to create the session over.
""" """
if isinstance(sock, (str, unicode)): if isinstance(sock, (str, unicode)):
# convert "host:port" into (host, port) # convert "host:port" into (host, port)
@ -249,8 +250,6 @@ class Transport (threading.Thread):
def __repr__(self): def __repr__(self):
""" """
Returns a string representation of this object, for debugging. Returns a string representation of this object, for debugging.
:rtype: str
""" """
out = '<paramiko.Transport at %s' % hex(long(id(self)) & 0xffffffffL) out = '<paramiko.Transport at %s' % hex(long(id(self)) & 0xffffffffL)
if not self.active: if not self.active:
@ -284,12 +283,9 @@ class Transport (threading.Thread):
def get_security_options(self): def get_security_options(self):
""" """
Return a `.SecurityOptions` object which can be used to tweak the Return a `.SecurityOptions` object which can be used to tweak the
encryption algorithms this transport will permit, and the order of encryption algorithms this transport will permit (for encryption,
preference for them. digest/hash operations, public keys, and key exchanges) and the order
of preference for them.
:return: an object that can be used to change the preferred algorithms
for encryption, digest (hash), public key, and key exchange.
:rtype: `.SecurityOptions`
""" """
return SecurityOptions(self) return SecurityOptions(self)
@ -317,9 +313,8 @@ class Transport (threading.Thread):
you should no longer directly read from or write to the original you should no longer directly read from or write to the original
socket object. socket object.
:param event: an event to trigger when negotiation is complete :param .threading.Event event:
(optional) an event to trigger when negotiation is complete (optional)
:type event: threading.Event
:raises SSHException: if negotiation fails (and no ``event`` was passed :raises SSHException: if negotiation fails (and no ``event`` was passed
in) in)
@ -377,12 +372,11 @@ class Transport (threading.Thread):
should no longer directly read from or write to the original socket should no longer directly read from or write to the original socket
object. object.
:param event: an event to trigger when negotiation is complete. :param .threading.Event event:
:type event: threading.Event an event to trigger when negotiation is complete.
:param server: :param .ServerInterface server:
an object used to perform authentication and create `channels an object used to perform authentication and create `channels
<.Channel>` <.Channel>`
:type server: `.ServerInterface`
:raises SSHException: if negotiation fails (and no ``event`` was passed :raises SSHException: if negotiation fails (and no ``event`` was passed
in) in)
@ -420,8 +414,8 @@ class Transport (threading.Thread):
key info, not just the public half. Only one key of each type (RSA or key info, not just the public half. Only one key of each type (RSA or
DSS) is kept. DSS) is kept.
:param key: the host key to add, usually an `.RSAKey` or `.DSSKey`. :param .PKey key:
:type key: `.PKey` the host key to add, usually an `.RSAKey` or `.DSSKey`.
""" """
self.server_key_dict[key.get_name()] = key self.server_key_dict[key.get_name()] = key
@ -436,8 +430,9 @@ class Transport (threading.Thread):
key of the type agreed on. If the host key has not been negotiated key of the type agreed on. If the host key has not been negotiated
yet, ``None`` is returned. In client mode, the behavior is undefined. yet, ``None`` is returned. In client mode, the behavior is undefined.
:return: host key of the type negotiated by the client, or ``None``. :return:
:rtype: `.PKey` host key (`.PKey`) of the type negotiated by the client, or
``None``.
""" """
try: try:
return self.server_key_dict[self.host_key_type] return self.server_key_dict[self.host_key_type]
@ -467,7 +462,6 @@ class Transport (threading.Thread):
not in a standard location. not in a standard location.
:return: :return:
True if a moduli file was successfully loaded; False otherwise. True if a moduli file was successfully loaded; False otherwise.
:rtype: bool
.. note:: This has no effect when used in client mode. .. note:: This has no effect when used in client mode.
""" """
@ -510,8 +504,7 @@ class Transport (threading.Thread):
:raises SSHException: if no session is currently active. :raises SSHException: if no session is currently active.
:return: public key of the remote server :return: public key (`.PKey`) of the remote server
:rtype: `.PKey`
""" """
if (not self.active) or (not self.initial_kex_done): if (not self.active) or (not self.initial_kex_done):
raise SSHException('No existing session') raise SSHException('No existing session')
@ -521,9 +514,9 @@ class Transport (threading.Thread):
""" """
Return true if this session is active (open). Return true if this session is active (open).
:return: True if the session is still active (open); False if the :return:
session is closed True if the session is still active (open); False if the session is
:rtype: bool closed
""" """
return self.active return self.active
@ -545,11 +538,10 @@ class Transport (threading.Thread):
Request a new channel to the client, of type ``"x11"``. This Request a new channel to the client, of type ``"x11"``. This
is just an alias for ``open_channel('x11', src_addr=src_addr)``. is just an alias for ``open_channel('x11', src_addr=src_addr)``.
:param src_addr: the source address of the x11 server (port is the :param tuple src_addr:
the source address (``(str, int)``) of the x11 server (port is the
x11 port, ie. 6010) x11 port, ie. 6010)
:type src_addr: (str, int)
:return: a new `.Channel` :return: a new `.Channel`
:rtype: `.Channel`
:raises SSHException: if the request is rejected or the session ends :raises SSHException: if the request is rejected or the session ends
prematurely prematurely
@ -564,7 +556,6 @@ class Transport (threading.Thread):
This is just an alias for ``open_channel('auth-agent@openssh.com')``. This is just an alias for ``open_channel('auth-agent@openssh.com')``.
:return: a new `.Channel` :return: a new `.Channel`
:rtype: `.Channel`
:raises SSHException: :raises SSHException:
if the request is rejected or the session ends prematurely if the request is rejected or the session ends prematurely
@ -591,18 +582,16 @@ class Transport (threading.Thread):
session. You may only request a channel after negotiating encryption session. You may only request a channel after negotiating encryption
(using `connect` or `start_client`) and authenticating. (using `connect` or `start_client`) and authenticating.
:param kind: the kind of channel requested (usually ``"session"``, :param str kind:
the kind of channel requested (usually ``"session"``,
``"forwarded-tcpip"``, ``"direct-tcpip"``, or ``"x11"``) ``"forwarded-tcpip"``, ``"direct-tcpip"``, or ``"x11"``)
:type kind: str :param tuple dest_addr:
:param dest_addr: the destination address of this port forwarding, the destination address (address + port tuple) of this port
if ``kind`` is ``"forwarded-tcpip"`` or ``"direct-tcpip"`` (ignored forwarding, if ``kind`` is ``"forwarded-tcpip"`` or
for other channel types) ``"direct-tcpip"`` (ignored for other channel types)
:type dest_addr: (str, int)
:param src_addr: the source address of this port forwarding, if :param src_addr: the source address of this port forwarding, if
``kind`` is ``"forwarded-tcpip"``, ``"direct-tcpip"``, or ``"x11"`` ``kind`` is ``"forwarded-tcpip"``, ``"direct-tcpip"``, or ``"x11"``
:type src_addr: (str, int)
:return: a new `.Channel` on success :return: a new `.Channel` on success
:rtype: `.Channel`
:raises SSHException: if the request is rejected or the session ends :raises SSHException: if the request is rejected or the session ends
prematurely prematurely
@ -669,15 +658,13 @@ class Transport (threading.Thread):
forwarded connections into the accept queue, to be picked up via forwarded connections into the accept queue, to be picked up via
`accept`. `accept`.
:param address: the address to bind when forwarding :param str address: the address to bind when forwarding
:type address: str :param int port:
:param port: the port to forward, or 0 to ask the server to allocate the port to forward, or 0 to ask the server to allocate any port
any port :param callable handler:
:type port: int optional handler for incoming forwarded connections, of the form
:param handler: optional handler for incoming forwarded connections ``func(Channel, (str, int), (str, int))``.
:type handler: function(Channel, (str, int), (str, int)) :return: the port number (`int`) allocated by the server
:return: the port # allocated by the server
:rtype: int
:raises SSHException: if the server refused the TCP forward request :raises SSHException: if the server refused the TCP forward request
""" """
@ -703,10 +690,8 @@ class Transport (threading.Thread):
connections to the given address & port will be forwarded across this connections to the given address & port will be forwarded across this
ssh connection. ssh connection.
:param address: the address to stop forwarding :param str address: the address to stop forwarding
:type address: str :param int port: the port to stop forwarding
:param port: the port to stop forwarding
:type port: int
""" """
if not self.active: if not self.active:
return return
@ -719,9 +704,9 @@ class Transport (threading.Thread):
SFTP session will be opened with the remote host, and a new SFTP session will be opened with the remote host, and a new
`.SFTPClient` object will be returned. `.SFTPClient` object will be returned.
:return: a new `.SFTPClient` object, referring to an sftp session :return:
(channel) across this transport a new `.SFTPClient` referring to an sftp session (channel) across
:rtype: `.SFTPClient` this transport
""" """
return SFTPClient.from_transport(self) return SFTPClient.from_transport(self)
@ -732,9 +717,9 @@ class Transport (threading.Thread):
also be used as a keep-alive for long lived connections traversing also be used as a keep-alive for long lived connections traversing
firewalls. firewalls.
:param bytes: the number of random bytes to send in the payload of the :param int bytes:
ignored packet -- defaults to a random number from 10 to 41. the number of random bytes to send in the payload of the ignored
:type bytes: int packet -- defaults to a random number from 10 to 41.
""" """
m = Message() m = Message()
m.add_byte(chr(MSG_IGNORE)) m.add_byte(chr(MSG_IGNORE))
@ -775,9 +760,9 @@ class Transport (threading.Thread):
"keepalive" packet will be sent (and ignored by the remote host). This "keepalive" packet will be sent (and ignored by the remote host). This
can be useful to keep connections alive over a NAT, for example. can be useful to keep connections alive over a NAT, for example.
:param interval: seconds to wait before sending a keepalive packet (or :param int interval:
seconds to wait before sending a keepalive packet (or
0 to disable keepalives). 0 to disable keepalives).
:type interval: int
""" """
self.packetizer.set_keepalive(interval, self.packetizer.set_keepalive(interval,
lambda x=weakref.proxy(self): x.global_request('keepalive@lag.net', wait=False)) lambda x=weakref.proxy(self): x.global_request('keepalive@lag.net', wait=False))
@ -787,18 +772,17 @@ class Transport (threading.Thread):
Make a global request to the remote host. These are normally Make a global request to the remote host. These are normally
extensions to the SSH2 protocol. extensions to the SSH2 protocol.
:param kind: name of the request. :param str kind: name of the request.
:type kind: str :param tuple data:
:param data: an optional tuple containing additional data to attach an optional tuple containing additional data to attach to the
to the request. request.
:type data: tuple :param bool wait:
:param wait: ``True`` if this method should not return until a response ``True`` if this method should not return until a response is
is received; ``False`` otherwise. received; ``False`` otherwise.
:type wait: bool :return:
:return: a `.Message` containing possible additional data if the a `.Message` containing possible additional data if the request was
request was successful (or an empty `.Message` if ``wait`` was successful (or an empty `.Message` if ``wait`` was ``False``);
``False``); ``None`` if the request was denied. ``None`` if the request was denied.
:rtype: `.Message`
""" """
if wait: if wait:
self.completion_event = threading.Event() self.completion_event = threading.Event()
@ -826,11 +810,9 @@ class Transport (threading.Thread):
server mode. If no channel is opened before the given timeout, ``None`` server mode. If no channel is opened before the given timeout, ``None``
is returned. is returned.
:param timeout: seconds to wait for a channel, or ``None`` to wait :param int timeout:
forever seconds to wait for a channel, or ``None`` to wait forever
:type timeout: int
:return: a new `.Channel` opened by the client :return: a new `.Channel` opened by the client
:rtype: `.Channel`
""" """
self.lock.acquire() self.lock.acquire()
try: try:
@ -867,17 +849,16 @@ class Transport (threading.Thread):
succeed, but a subsequent `open_channel` or `open_session` call may succeed, but a subsequent `open_channel` or `open_session` call may
fail because you haven't authenticated yet. fail because you haven't authenticated yet.
:param hostkey: the host key expected from the server, or ``None`` if :param .PKey hostkey:
you don't want to do host key verification. the host key expected from the server, or ``None`` if you don't
:type hostkey: `.PKey` want to do host key verification.
:param username: the username to authenticate as. :param str username: the username to authenticate as.
:type username: str :param str password:
:param password: a password to use for authentication, if you want to a password to use for authentication, if you want to use password
use password authentication; otherwise ``None``. authentication; otherwise ``None``.
:type password: str :param .PKey pkey:
:param pkey: a private key to use for authentication, if you want to a private key to use for authentication, if you want to use private
use private key authentication; otherwise ``None``. key authentication; otherwise ``None``.
:type pkey: `.PKey`
:raises SSHException: if the SSH2 negotiation fails, the host key :raises SSHException: if the SSH2 negotiation fails, the host key
supplied by the server is incorrect, or authentication fails. supplied by the server is incorrect, or authentication fails.
@ -914,8 +895,8 @@ class Transport (threading.Thread):
calls like `start_client`. The exception (if any) is cleared after calls like `start_client`. The exception (if any) is cleared after
this call. this call.
:return: an exception, or ``None`` if there is no stored exception. :return:
:rtype: Exception an exception, or ``None`` if there is no stored exception.
.. versionadded:: 1.1 .. versionadded:: 1.1
""" """
@ -937,11 +918,9 @@ class Transport (threading.Thread):
Any extra parameters (including keyword arguments) are saved and Any extra parameters (including keyword arguments) are saved and
passed to the `.SubsystemHandler` constructor later. passed to the `.SubsystemHandler` constructor later.
:param name: name of the subsystem. :param str name: name of the subsystem.
:type name: str :param class handler:
:param handler: subclass of `.SubsystemHandler` that handles this subclass of `.SubsystemHandler` that handles this subsystem.
subsystem.
:type handler: class
""" """
try: try:
self.lock.acquire() self.lock.acquire()
@ -953,10 +932,10 @@ class Transport (threading.Thread):
""" """
Return true if this session is active and authenticated. Return true if this session is active and authenticated.
:return: True if the session is still open and has been authenticated :return:
True if the session is still open and has been authenticated
successfully; False if authentication failed and/or the session is successfully; False if authentication failed and/or the session is
closed. closed.
:rtype: bool
""" """
return self.active and (self.auth_handler is not None) and self.auth_handler.is_authenticated() return self.active and (self.auth_handler is not None) and self.auth_handler.is_authenticated()
@ -966,8 +945,7 @@ class Transport (threading.Thread):
session is not authenticated (or authentication failed), this method session is not authenticated (or authentication failed), this method
returns ``None``. returns ``None``.
:return: username that was authenticated, or ``None``. :return: username that was authenticated (a `str`), or ``None``.
:rtype: string
""" """
if not self.active or (self.auth_handler is None): if not self.active or (self.auth_handler is None):
return None return None
@ -980,11 +958,10 @@ class Transport (threading.Thread):
list of authentication types supported by the server, by catching the list of authentication types supported by the server, by catching the
`.BadAuthenticationType` exception raised. `.BadAuthenticationType` exception raised.
:param username: the username to authenticate as :param str username: the username to authenticate as
:type username: string :return:
:return: list of auth types permissible for the next stage of `list` of auth types permissible for the next stage of
authentication (normally empty) authentication (normally empty)
:rtype: list
:raises BadAuthenticationType: if "none" authentication isn't allowed :raises BadAuthenticationType: if "none" authentication isn't allowed
by the server for this user by the server for this user
@ -1027,20 +1004,17 @@ class Transport (threading.Thread):
this method will return a list of auth types permissible for the next this method will return a list of auth types permissible for the next
step. Otherwise, in the normal case, an empty list is returned. step. Otherwise, in the normal case, an empty list is returned.
:param username: the username to authenticate as :param str username: the username to authenticate as
:type username: str :param basestring password: the password to authenticate with
:param password: the password to authenticate with :param .threading.Event event:
:type password: basestring an event to trigger when the authentication attempt is complete
:param event: an event to trigger when the authentication attempt is (whether it was successful or not)
complete (whether it was successful or not) :param bool fallback:
:type event: threading.Event ``True`` if an attempt at an automated "interactive" password auth
:param fallback: ``True`` if an attempt at an automated "interactive" should be made if the server doesn't support normal password auth
password auth should be made if the server doesn't support normal :return:
password auth `list` of auth types permissible for the next stage of
:type fallback: bool
:return: list of auth types permissible for the next stage of
authentication (normally empty) authentication (normally empty)
:rtype: list
:raises BadAuthenticationType: if password authentication isn't :raises BadAuthenticationType: if password authentication isn't
allowed by the server for this user (and no event was passed in) allowed by the server for this user (and no event was passed in)
@ -1101,16 +1075,14 @@ class Transport (threading.Thread):
this method will return a list of auth types permissible for the next this method will return a list of auth types permissible for the next
step. Otherwise, in the normal case, an empty list is returned. step. Otherwise, in the normal case, an empty list is returned.
:param username: the username to authenticate as :param str username: the username to authenticate as
:type username: string :param .PKey key: the private key to authenticate with
:param key: the private key to authenticate with :param .threading.Event event:
:type key: `.PKey` an event to trigger when the authentication attempt is complete
:param event: an event to trigger when the authentication attempt is (whether it was successful or not)
complete (whether it was successful or not) :return:
:type event: threading.Event `list` of auth types permissible for the next stage of
:return: list of auth types permissible for the next stage of
authentication (normally empty) authentication (normally empty)
:rtype: list
:raises BadAuthenticationType: if public-key authentication isn't :raises BadAuthenticationType: if public-key authentication isn't
allowed by the server for this user (and no event was passed in) allowed by the server for this user (and no event was passed in)
@ -1161,15 +1133,12 @@ class Transport (threading.Thread):
this method will return a list of auth types permissible for the next this method will return a list of auth types permissible for the next
step. Otherwise, in the normal case, an empty list is returned. step. Otherwise, in the normal case, an empty list is returned.
:param username: the username to authenticate as :param str username: the username to authenticate as
:type username: string :param callable handler: a handler for responding to server questions
:param handler: a handler for responding to server questions :param str submethods: a string list of desired submethods (optional)
:type handler: callable :return:
:param submethods: a string list of desired submethods (optional) `list` of auth types permissible for the next stage of
:type submethods: str
:return: list of auth types permissible for the next stage of
authentication (normally empty). authentication (normally empty).
:rtype: list
:raises BadAuthenticationType: if public-key authentication isn't :raises BadAuthenticationType: if public-key authentication isn't
allowed by the server for this user allowed by the server for this user
@ -1193,8 +1162,7 @@ class Transport (threading.Thread):
the `.logging` module for more info.) SSH Channels will log to a the `.logging` module for more info.) SSH Channels will log to a
sub-channel of the one specified. sub-channel of the one specified.
:param name: new channel name for logging :param str name: new channel name for logging
:type name: str
.. versionadded:: 1.1 .. versionadded:: 1.1
""" """
@ -1206,8 +1174,7 @@ class Transport (threading.Thread):
""" """
Return the channel name used for this transport's logging. Return the channel name used for this transport's logging.
:return: channel name. :return: channel name as a `str`
:rtype: str
.. versionadded:: 1.2 .. versionadded:: 1.2
""" """
@ -1219,9 +1186,9 @@ class Transport (threading.Thread):
the logs. Normally you would want this off (which is the default), the logs. Normally you would want this off (which is the default),
but if you are debugging something, it may be useful. but if you are debugging something, it may be useful.
:param hexdump: ``True`` to log protocol traffix (in hex) to the log; :param bool hexdump:
``False`` otherwise. ``True`` to log protocol traffix (in hex) to the log; ``False``
:type hexdump: bool otherwise.
""" """
self.packetizer.set_hexdump(hexdump) self.packetizer.set_hexdump(hexdump)
@ -1230,8 +1197,7 @@ class Transport (threading.Thread):
Return ``True`` if the transport is currently logging hex dumps of Return ``True`` if the transport is currently logging hex dumps of
protocol traffic. protocol traffic.
:return: ``True`` if hex dumps are being logged :return: ``True`` if hex dumps are being logged, else ``False``.
:rtype: bool
.. versionadded:: 1.4 .. versionadded:: 1.4
""" """
@ -1243,9 +1209,9 @@ class Transport (threading.Thread):
the transport (ie before calling `connect`, etc). By default, the transport (ie before calling `connect`, etc). By default,
compression is off since it negatively affects interactive sessions. compression is off since it negatively affects interactive sessions.
:param compress: ``True`` to ask the remote client/server to compress :param bool compress:
traffic; ``False`` to refuse compression ``True`` to ask the remote client/server to compress traffic;
:type compress: bool ``False`` to refuse compression
.. versionadded:: 1.5.2 .. versionadded:: 1.5.2
""" """
@ -1261,8 +1227,9 @@ class Transport (threading.Thread):
socket. If the socket-like object has no ``'getpeername'`` method, socket. If the socket-like object has no ``'getpeername'`` method,
then ``("unknown", 0)`` is returned. then ``("unknown", 0)`` is returned.
:return: the address if the remote host, if known :return:
:rtype: tuple(str, int) the address of the remote host, if known, as a ``(str, int)``
tuple.
""" """
gp = getattr(self.sock, 'getpeername', None) gp = getattr(self.sock, 'getpeername', None)
if gp is None: if gp is None:
@ -2057,8 +2024,6 @@ class SecurityOptions (object):
def __repr__(self): def __repr__(self):
""" """
Returns a string representation of this object, for debugging. Returns a string representation of this object, for debugging.
:rtype: str
""" """
return '<paramiko.SecurityOptions for %s>' % repr(self._transport) return '<paramiko.SecurityOptions for %s>' % repr(self._transport)