euporie.hub.app

Run euporie as a multi-client SSH server.

Functions

`add_setting`(name, args, *kwargs)	Register a new config item.
`available_apps`()	Return a list of loadable euporie apps.

Classes

`ConfigurableApp`()	An application with configuration.
`EuporieSSHServer`(app_cls)	Launch euporie hub, which serves a euporie app over SSH.
`HubApp`()	Hub App.
`PromptToolkitSSHSession`(interact, *, enable_cpr)
`UPath`(*args[, protocol])

class euporie.hub.app.EuporieSSHServer(app_cls: type[BaseApp])

Bases: SSHServer

Launch euporie hub, which serves a euporie app over SSH.

Launch euporie hub, a multi-client SSH server running euporie, which allows multiple users to connect and run instances of a euporie app.

auth_completed() → None

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: str) → bool | Awaitable[bool]: Perform authentication in the SSH server.

change_password(username: str, old_password: str, new_password: str) → bool | Awaitable[bool]

Handle a request to change a user’s password

This method is called when a user makes a request to change their password. It should first validate that the old password provided is correct and then attempt to change the user’s password to the new value.

If the old password provided is valid and the change to the new password is successful, this method should return True. If the old password is not valid or password changes are not supported, it should return False. It may also raise PasswordChangeRequired to request that the client try again if the new password is not acceptable for some reason.

If blocking operations need to be performed to determine the validity of the old password or to change to the new password, this method may be defined as a coroutine.

By default, this method returns False, rejecting all password changes.

Parameters:

username (str) – The user whose password should be changed
old_password (str) – The user’s current password
new_password (str) – The new password being requested

Returns:

A bool indicating if the password change is successful or not

Raises:

PasswordChangeRequired if the new password is not acceptable and the client should be asked to provide another

connection_lost(exc: Exception | None) → None

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: SSHServerConnection) → None

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

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: str, lang: str, always_display: bool) → None

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

get_kbdint_challenge(username: str, lang: str, submethods: str) → bool | Tuple[str, str, str, Sequence[Tuple[str, bool]]] | Awaitable[bool | Tuple[str, str, str, Sequence[Tuple[str, bool]]]]

Return a keyboard-interactive auth challenge

This method should return True if authentication should succeed without any challenge, False if authentication should fail without any challenge, or an auth challenge consisting of a challenge name, instructions, a language tag, and a list of tuples containing prompt strings and booleans indicating whether input should be echoed when a value is entered for that prompt.

If blocking operations need to be performed to determine the challenge to issue, this method may be defined as a coroutine.

Parameters:

username (str) – The user being authenticated
lang (str) – The language requested by the client for the challenge
submethods (str) – A comma-separated list of the types of challenges the client can support, or the empty string if the server should choose

Returns:

An authentication challenge as described above

host_based_auth_supported() → bool

Return whether or not host-based authentication is supported

This method should return True if client host-based authentication is supported. Applications wishing to support it must have this method return True and implement validate_host_public_key() and/or validate_host_ca_key() to return whether or not the key provided by the client is valid for the client host being authenticated.

By default, it returns False indicating the client host based authentication is not supported.

Returns:: A bool indicating if host-based authentication is supported or not

kbdint_auth_supported() → bool

Return whether or not keyboard-interactive authentication is supported

This method should return True if keyboard-interactive authentication is supported. Applications wishing to support it must have this method return True and implement get_kbdint_challenge() and validate_kbdint_response() to generate the apporiate challenges and validate the responses for the user being authenticated.

By default, this method returns NotImplemented tying this authentication to password authentication. If the application implements password authentication and this method is not overridden, keyboard-interactive authentication will be supported by prompting for a password and passing that to the password authentication callbacks.

Returns:: A bool indicating if keyboard-interactive authentication is supported or not

password_auth_supported() → bool

Return whether or not password authentication is supported

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

By default, this method returns False indicating that password authentication is not supported.

Returns:: A bool indicating if password authentication is supported or not

public_key_auth_supported() → bool

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: str, listen_port: int) → bool | SSHListener | Awaitable[bool | SSHListener]

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() → PromptToolkitSSHSession: Return an SSH session.

Handle a direct UNIX domain socket connection request

This method is called when a direct UNIX domain socket connection request is received by the server. Applications wishing to accept such connections must override this method.

To allow standard path forwarding of data on the connection to the requested destination path, 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 SSHUNIXSession object which can be used to process the data received on the channel or a tuple consisting of of an SSHUNIXChannel object created with create_unix_channel() and an SSHUNIXSession, 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 SSHUNIXSession object can be returned instead of the session iself. This can be either returned directly or as a part of a tuple with an SSHUNIXChannel object.

By default, all connection requests are rejected.

Parameters:

dest_path (str) – The path the client wishes to connect to

Returns:

One of the following:

An SSHUNIXSession object or a coroutine which returns an SSHUNIXSession
A tuple consisting of an SSHUNIXChannel 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 SSHUNIXChannel and the above
True to request standard path forwarding
False to refuse the connection

Raises:

ChannelOpenError if the connection shouldn’t be accepted

unix_server_requested(listen_path: str) → bool | SSHListener | Awaitable[bool | SSHListener]

Handle a request to listen on a UNIX domain socket

This method is called when a client makes a request to listen on a path for incoming UNIX domain socket connections. Applications wishing to allow UNIX domain socket forwarding must override this method.

To set up standard path forwarding of connections received on this path, 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_unix_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_path (str) – The path the server should listen on

Returns:

One of the following:

An SSHListener object or a coroutine which returns an SSHListener or False if the listener can’t be opened
True to set up standard path forwarding
False to reject the request

validate_ca_key(username: str, key: SSHKey) → bool | Awaitable[bool]

Return whether key is an authorized CA key for this user

Certificate based client authentication can be supported by passing authorized CA 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 certificate authority 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 CA keys.

Note

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

Parameters:

username (str) – The user being authenticated
key (SSHKey public key) – The public key which signed the certificate sent by the client

Returns:

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

validate_gss_principal(username: str, user_principal: str, host_principal: str) → bool | Awaitable[bool]

Return whether a GSS principal is valid for this user

This method should return True if the specified user principal is valid for the user being authenticated. It can be overridden by applications wishing to perform their own authentication.

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

By default, this method will return True only when the name in the user principal exactly matches the username and the domain of the user principal matches the domain of the host principal.

Parameters:

username (str) – The user being authenticated
user_principal (str) – The user principal sent by the client
host_principal (str) – The host principal sent by the server

Returns:

A bool indicating if the specified user principal is valid for the user being authenticated

validate_host_based_user(username: str, client_host: str, client_username: str) → bool | Awaitable[bool]

Return whether remote host and user is authorized for this user

This method should return True if the specified client host and user is valid for the user being authenticated. It can be overridden by applications wishing to enforce restrictions on which remote users are allowed to authenticate as particular local users.

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

By default, this method will return True when the client username matches the name of the user being authenticated.

Parameters:

username (str) – The user being authenticated
client_host (str) – The hostname of the client host making the request
client_username (str) – The username of the user on the client host

Returns:

A bool indicating if the specified client host and user is valid for the user being authenticated

validate_host_ca_key(client_host: str, client_addr: str, client_port: int, key: SSHKey) → bool

Return whether key is an authorized CA key for this client host

Certificate based client host authentication can be supported by passing authorized host CA keys in the known_client_hosts argument of create_server(). 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 certificate authority key for the client host 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.

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

Note

This function only needs to report whether the public key provided is a valid CA key for this client host. If it is, AsyncSSH will verify that the certificate is valid, that the client host is one of the valid principals for the certificate, and that the client possesses the private key corresponding to the public key in the certificate before allowing the authentication to succeed.

Parameters:

client_host (str) – The hostname of the client host
client_addr (str) – The IP address of the client host
client_port (int) – The port number on the client host
key (SSHKey public key) – The public key which signed the certificate sent by the client

Returns:

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

validate_host_public_key(client_host: str, client_addr: str, client_port: int, key: SSHKey) → bool

Return whether key is an authorized host key for this client host

Host key based client authentication can be supported by passing authorized host keys in the known_client_hosts argument of create_server(). 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 host key for the client host 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.

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

Note

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

Parameters:

client_host (str) – The hostname of the client host
client_addr (str) – The IP address of the client host
client_port (int) – The port number on the client host
key (SSHKey public key) – The host public key sent by the client

Returns:

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

validate_kbdint_response(username: str, responses: Sequence[str]) → bool | Tuple[str, str, str, Sequence[Tuple[str, bool]]] | Awaitable[bool | Tuple[str, str, str, Sequence[Tuple[str, bool]]]]

Return whether the keyboard-interactive response is valid for this user

This method should validate the keyboard-interactive responses provided and return True if authentication should succeed with no further challenge, False if authentication should fail, or an additional auth challenge in the same format returned by get_kbdint_challenge(). Any series of challenges can be returned this way. To print a message in the middle of a sequence of challenges without prompting for additional data, a challenge can be returned with an empty list of prompts. After the client acknowledges this message, this function will be called again with an empty list of responses to continue the authentication.

If blocking operations need to be performed to determine the validity of the response or the next challenge to issue, this method may be defined as a coroutine.

Parameters:

username (str) – The user being authenticated
responses (list of str) – A list of responses to the last challenge

Returns:

True, False, or the next challenge

validate_password(username: str, password: str) → bool | Awaitable[bool]

Return whether password is valid for this user

This method should return True if the specified password is a valid password for the user being authenticated. It must be overridden by applications wishing to support password authentication.

If the password provided is valid but expired, this method may raise PasswordChangeRequired to request that the client provide a new password before authentication is allowed to complete. In this case, the application must override change_password() to handle the password change request.

This method may be called multiple times with different passwords provided by the client. Applications may wish to limit the number of attempts which are allowed. This can be done by having password_auth_supported() begin returning False after the maximum number of attempts is exceeded.

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

By default, this method returns False for all passwords.

Parameters:

username (str) – The user being authenticated
password (str) – The password sent by the client

Returns:

A bool indicating if the specified password is valid for the user being authenticated

Raises:

PasswordChangeRequired if the password provided is expired and needs to be changed

validate_public_key(username: str, key: SSHKey) → bool | Awaitable[bool]

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 euporie.hub.app.HubApp

Bases: ConfigurableApp

Hub App.

An app which runs as a multi-user SSH server.

This app never actually gets run, but is used to run another app in an SSH server.

config: Config = <euporie.core.config.Config object>

classmethod launch() → None: Launch the HubApp SSH server.

classmethod load_settings() → None: Load all known settings for this class.

name: str | None = 'hub'