angelos.lib.ssh.ssh

Module docstring.

class angelos.lib.ssh.ssh.SSHClient(ioc, keylist=(), delay=1)

Bases: angelos.lib.ioc.ContainerAware, asyncssh.client.SSHClient

auth_banner_received(msg, lang)

An incoming authentication banner was received

This method is called when the server sends a banner to display during authentication. Applications should implement this method if they wish to do something with the banner.

Parameters

  • msg (str) – The message the server wanted to display

  • lang (str) – The language the message is in

auth_completed()

Authentication was completed successfully

This method is called when authentication has completed succesfully. Applications may use this method to create whatever client sessions and direct TCP/IP or UNIX domain connections are needed and/or set up listeners for incoming TCP/IP or UNIX domain connections coming from the server. However, create_connection() now blocks until authentication is complete, so any code which wishes to use the SSH connection can simply follow that call and doesn’t need to be performed in a callback.

connection_lost(exc)

Called when a connection is lost or closed

This method is called when a connection is closed. If the connection is shut down cleanly, exc will be None. Otherwise, it will be an exception explaining the reason for the disconnect.

Parameters

exc (Exception) – The exception which caused the connection to close, or None if the connection closed cleanly

connection_made(conn)

Called when a connection is made

This method is called as soon as the TCP connection completes. The conn parameter should be stored if needed for later use.

Parameters

conn (SSHClientConnection) – The connection which was successfully opened

debug_msg_received(msg, lang, always_display)

A debug message was received on this connection

This method is called when the other end of the connection sends a debug message. Applications should implement this method if they wish to process these debug messages.

Parameters

  • msg (str) – The debug message sent

  • lang (str) – The language the message is in

  • always_display (bool) – Whether or not to display the message

public_key_auth_requested()

Public key authentication has been requested

This method should return a private key corresponding to the user that authentication is being attempted for.

This method may be called multiple times and can return a different key to try each time it is called. When there are no keys left to try, it should return None to indicate that some other authentication method should be tried.

If client keys were provided when the connection was opened, they will be tried before this method is called.

If blocking operations need to be performed to determine the key to authenticate with, this method may be defined as a coroutine.

Returns

A key as described in SpecifyingPrivateKeys or None to move on to another authentication method

class angelos.lib.ssh.ssh.SSHServer(ioc)

Bases: angelos.lib.ioc.LogAware, asyncssh.server.SSHServer

SSH server container aware baseclass.

auth_completed()

Authentication was completed successfully

This method is called when authentication has completed succesfully. Applications may use this method to perform processing based on the authenticated username or options in the authorized keys list or certificate associated with the user before any sessions are opened or forwarding requests are handled.

begin_auth(username)

Authentication has been requested by the client

This method will be called when authentication is attempted for the specified user. Applications should use this method to prepare whatever state they need to complete the authentication, such as loading in the set of authorized keys for that user. If no authentication is required for this user, this method should return False to cause the authentication to immediately succeed. Otherwise, it should return True to indicate that authentication should proceed.

If blocking operations need to be performed to prepare the state needed to complete the authentication, this method may be defined as a coroutine.

Parameters

username (str) – The name of the user being authenticated

Returns

A bool indicating whether authentication is required

connection_lost(exc)

Called when a connection is lost or closed

This method is called when a connection is closed. If the connection is shut down cleanly, exc will be None. Otherwise, it will be an exception explaining the reason for the disconnect.

connection_made(conn)

Called when a connection is made

This method is called when a new TCP connection is accepted. The conn parameter should be stored if needed for later use.

Parameters

conn (SSHServerConnection) – The connection which was successfully opened

connection_requested(dest_host, dest_port, orig_host, orig_port)

Handle a direct TCP/IP connection request

This method is called when a direct TCP/IP connection request is received by the server. Applications wishing to accept such connections must override this method.

To allow standard port forwarding of data on the connection to the requested destination host and port, this method should return True.

To reject this request, this method should return False to send back a “Connection refused” response or raise an ChannelOpenError exception with the reason for the failure.

If the application wishes to process the data on the connection itself, this method should return either an SSHTCPSession object which can be used to process the data received on the channel or a tuple consisting of of an SSHTCPChannel object created with create_tcp_channel() and an SSHTCPSession, if the application wishes to pass non-default arguments when creating the channel.

If blocking operations need to be performed before the session can be created, a coroutine which returns an SSHTCPSession object can be returned instead of the session iself. This can be either returned directly or as a part of a tuple with an SSHTCPChannel object.

By default, all connection requests are rejected.

Parameters

  • dest_host (str) – The address the client wishes to connect to

  • dest_port (int) – The port the client wishes to connect to

  • orig_host (str) – The address the connection was originated from

  • orig_port (int) – The port the connection was originated from

Returns

One of the following:

  • An SSHTCPSession object or a coroutine which returns an SSHTCPSession

  • A tuple consisting of an SSHTCPChannel and the above

  • A callable or coroutine handler function which takes AsyncSSH stream objects for reading from and writing to the connection

  • A tuple consisting of an SSHTCPChannel and the above

  • True to request standard port forwarding

  • False to refuse the connection

Raises

ChannelOpenError if the connection shouldn’t be accepted

debug_msg_received(msg, lang, always_display)

A debug message was received on this connection

This method is called when the other end of the connection sends a debug message. Applications should implement this method if they wish to process these debug messages.

Parameters

  • msg (str) – The debug message sent

  • lang (str) – The language the message is in

  • always_display (bool) – Whether or not to display the message

public_key_auth_supported()

Return whether or not public key authentication is supported

This method should return True if client public key authentication is supported. Applications wishing to support it must have this method return True and implement validate_public_key() and/or validate_ca_key() to return whether or not the key provided by the client is valid for the user being authenticated.

By default, it returns False indicating the client public key authentication is not supported.

Returns

A bool indicating if public key authentication is supported or not

server_requested(listen_host, listen_port)

Handle a request to listen on a TCP/IP address and port

This method is called when a client makes a request to listen on an address and port for incoming TCP connections. The port to listen on may be 0 to request a dynamically allocated port. Applications wishing to allow TCP/IP connection forwarding must override this method.

To set up standard port forwarding of connections received on this address and port, this method should return True.

If the application wishes to manage listening for incoming connections itself, this method should return an SSHListener object that listens for new connections and calls create_connection on each of them to forward them back to the client or return None if the listener can’t be set up.

If blocking operations need to be performed to set up the listener, a coroutine which returns an SSHListener can be returned instead of the listener itself.

To reject this request, this method should return False.

By default, this method rejects all server requests.

Parameters

  • listen_host (str) – The address the server should listen on

  • listen_port (int) – The port the server should listen on, or the value 0 to request that the server dynamically allocate a port

Returns

One of the following:

  • An SSHListener object

  • True to set up standard port forwarding

  • False to reject the request

  • A coroutine object which returns one of the above

session_requested()

Handle an incoming session request

This method is called when a session open request is received from the client, indicating it wishes to open a channel to be used for running a shell, executing a command, or connecting to a subsystem. If the application wishes to accept the session, it must override this method to return either an SSHServerSession object to use to process the data received on the channel or a tuple consisting of an SSHServerChannel object created with create_server_channel and an SSHServerSession, if the application wishes to pass non-default arguments when creating the channel.

If blocking operations need to be performed before the session can be created, a coroutine which returns an SSHServerSession object can be returned instead of the session iself. This can be either returned directly or as a part of a tuple with an SSHServerChannel object.

To reject this request, this method should return False to send back a “Session refused” response or raise a ChannelOpenError exception with the reason for the failure.

The details of what type of session the client wants to start will be delivered to methods on the SSHServerSession object which is returned, along with other information such as environment variables, terminal type, size, and modes.

By default, all session requests are rejected.

Returns

One of the following:

  • An SSHServerSession object or a coroutine which returns an SSHServerSession

  • A tuple consisting of an SSHServerChannel and the above

  • A callable or coroutine handler function which takes AsyncSSH stream objects for stdin, stdout, and stderr as arguments

  • A tuple consisting of an SSHServerChannel and the above

  • False to refuse the request

Raises

ChannelOpenError if the session shouldn’t be accepted

validate_public_key(username, key)

Return whether key is an authorized client key for this user

Key based client authentication can be supported by passing authorized keys in the authorized_client_keys argument of create_server(), or by calling set_authorized_keys on the server connection from the begin_auth() method. However, for more flexibility in matching on the allowed set of keys, this method can be implemented by the application to do the matching itself. It should return True if the specified key is a valid client key for the user being authenticated.

This method may be called multiple times with different keys provided by the client. Applications should precompute as much as possible in the begin_auth() method so that this function can quickly return whether the key provided is in the list.

If blocking operations need to be performed to determine the validity of the key, this method may be defined as a coroutine.

By default, this method returns False for all client keys.

Note

This function only needs to report whether the public key provided is a valid client key for this user. If it is, AsyncSSH will verify that the client possesses the corresponding private key before allowing the authentication to succeed.

Parameters

  • username (str) – The user being authenticated

  • key (SSHKey public key) – The public key sent by the client

Returns

A bool indicating if the specified key is a valid client key for the user being authenticated

class angelos.lib.ssh.ssh.SessionHandle(user_id, session)

Bases: object

Handle for a SSH Session.

class angelos.lib.ssh.ssh.SessionManager

Bases: object

Session manager to be used with the IoC.

add_session(name, handle)

Add a new session to related server.

close_session(user_id)

Close a specific session.

length()
reg_server(name, server, idle=60)

register a server with the manager.

unreg_server(name)

Unregister server and close all related sessions.