SFTPServer Class

Properties   Methods   Events   Configuration Settings   Errors  

The SFTPServer class is used to create a SFTP Server.

Syntax

class ipworksssh.SFTPServer

Remarks

The SFTPServer class provides a simple way to create a SFTP server. Any SFTP client will be able to connect and transfer files to and from the server.

Getting Started

To begin, first provide a valid certificate with private key in the ssh_cert property.

Optionally set the root_directory property to a valid local path. If this property is set the class will serve files from this location and when clients connect they will see this as their initial directory. If this property is not set then the class will fire events allowing customized responses for each operation.

To start the server set listening to true.

Client Authentication

Client authentication is handled through the on_ssh_user_auth_request event. Inside this event, the Accept parameter determines whether authentication is accepted; this parameter should be set to True if a successful authentication is detected and False otherwise.

When a client connects, the AuthMethod parameter indicates the method of authentication the client wishes to use. Connecting clients will initially attempt authentication with an AuthMethod of "none". This is done with the expectation that the request will fail and the server will provide a list of support authentication methods. The client then selects an available method and re-authenticates. If AuthMethod is "none", Accept should be set to False.

For password authentication, the User parameter will hold the client's username and the AuthParam parameter will hold the password provided by the client. An external list of known usernames and passwords should be maintained to check these values against.

For publickey authentication, the User parameter will hold the client's username and the AuthParam parameter will hold the key provided by the client. This key should be compared to and external list of known keys and usernames.

For keyboard-interactive authentication, the on_ssh_user_auth_request event will fire multiple times; once for each prompt and response sent by the client. The index of the response is specified as a suffix in the AuthMethod parameter (e.g. keyboard-interactive-1, keyboard-interactive-2, etc), and AuthParam will contain the client's response to the prompt. Finally, on_ssh_user_auth_request will fire one last time with AuthMethod set to "keyboard-interactive" and AuthParam set to an empty string. The Accept parameter must be set to True each time the event fires in order for the authentication process to succeed.

Directory Listing

When a client requests a directory listing, the on_dir_list event fires with the Path parameter set to the directory to enumerate. If the directory listing is allowed, the appropriate set of files should be passed to the set_file_list method. The StatusCode parameter should be set according to the status of the operation, and the valid status codes can be found in the documentation for the on_dir_list event.

Handling Events

Event handlers are the primary method of customizing the class's functionality. When a client attempts to connect, open a file, authenticate to the server, etc, the corresponding SFTPServer event will fire to allow for custom handling of the client's request.

The following events are fired both before and after the requested operation is executed:

• on_dir_create
• on_dir_list
• on_dir_remove
• on_file_open
• on_file_remove
• on_file_rename
• on_file_write
• on_set_attributes

Each of these events has a BeforeExec event parameter that is True when the event is fired before execution of the operation, and False after execution of the operation. Handling the event before execution provides an opportunity to use custom logic to determine whether the operation should be denied, diverted, or otherwise modified. Handling the event after execution provides an opportunity to report success or any errors related to the operation to the client.

The following events are fired only after the requested operation is executed:

• on_file_close
• on_file_read
• on_get_attributes
• on_resolve_path

Any logic to deny opening a file for read or write should be done in the on_file_open event handler.

Note: Server components are designed to process events as they occur. To ensure events are processed in a timely manner do_events should be called in a loop after the server is started.