ssh

SSH module

This module uses libssh2 to implement ssh, scp and sftp protocols to connect to the SSH server.

Features

• list files on remote server, both short and long lists are supported. Uses sftp protocol.
• mkdir, create directory on remote server. Uses sftp protocol.
• Download or Upload file to the remote ssh server. Uses SCP protocol.
• execute any command on remote ssh server, wait and collect the result output.

Security

Module supports both password and public key authentication.

In conventional password authentication, you prove you are who you claim to be by proving that you know the correct password. The only way to prove you know the password is to tell the server what you think the password is. This means that if the server has been hacked, or spoofed, an attacker can learn your password.
Public key authentication solves this problem. You generate a key pair, consisting of a public key (which everybody is allowed to know) and a private key (which you keep secret and do not give to anybody). The private key is able to generate signatures. A signature created using your private key cannot be forged by anybody who does not have that key; but anybody who has your public key can verify that a particular signature is genuine.

To use a public key authentication, you have to generate public/private key pair on your PC and store it on the MicroPython file system.

Methods

ssh.options(print, verbose, progress, timeout, maxfsize, hdrlen, bodylen, trace)

Get or set ssh options.
All arguments are optional. All, except ṗrint, arguments are *kw arguments and must be entered in arg=value format.

Arg	Description
print	Default: True; print the current options. False can be used when setting the option(s) from Python script
verbose	if True, collects the ssh operation results which can be examined after the operation is finished
progress	if True, prints the progress during the file upload/download
timeout	Default: 8 sek; set the timeout for ssh socket operations in seconds. Allowed range is 2 ~ 30 seconds
maxfsize	Default: 300000 Maximum download file size. If the requested file size is bigger, the whole file will be downloaded, but the file on filesystem will be truncated at that value.
hdrlen	Default: 512 or 1024 if psRAM is used The size of the header buffer. Header buffer is returned as the 2nd item in ssh operations result and contains the ssh operation messages
bodylen	Default: 1024 or 4096 if psRAM is used The size of the body buffer. Body buffer is returned as 3rd item in ssh operations result and contains the response from the ssh server
trace	Enable individual libssh2 trace messages. The trace options can be combined (added or or-er) The following constants can be used: ssh.TRACE_TRANS, ssh.TRACE_KEX, ssh.TRACE_AUTH ssh.TRACE_CONN, ssh.TRACE_SCP, ssh.TRACE_SFTP ssh.TRACE_ERROR, ssh.TRACE_PUBLICKEY ssh.TRACE_NONE, ssh.TRACE_ALL

>>> import ssh
>>> ssh.options()
SSH options(
  Verbose: False, Progress: 0, Timeout: 8 s, Max fsize: 300000, Header len: 1024, Body len: 4096, Trace: False (0x000)
)

ssh.list(url, user, password, key, port)

List the files on the remote server directory.
url, user and password are mandatory arguments, other arguments are optional and must be used as kw arguments, arg=value

url argument must be given in the format server_domain/dir_path or server_IP_address/dir_path

If the password authentication is used, password is the ssh server password for the specified user.
If the public key authentication is used, password is the key's password if used, otherwise None.

key, if used, is the path to the private key file on your MicroPython file system.
public key file with the same name and extension .pub must be available on the same location.

port is the ssh server's port. Defaults to 22 if not entered.

The method returns tuple of 3 items: (res_code, msgs, response)

>>> res = ssh.list('loboris.eu/home', 'usrname', 'password')
>>> res[0]
0
>>> print(res[1])
* DNS lookup succeeded. IP=82.196.4.208
* Connected
* SSH session created
* SSH session established
* Fingerprint (SHA256): [1880B86E21ECABD2C21DD039FA1C6FD01BEAE0C739CACB1DB32A8B51BAA1B553]
* Authentication by password succeed.

>>> print(res[2])
D	26	.
D	4096	..
D	1222	boris
D	24	ftpusers

>>> res = ssh.list('loboris.eu/home', 'usrname', None, key='id_rsa')
>>> res[0]
0
>>> print(res[1])
* DNS lookup succeeded. IP=82.196.4.208
* Connected
* SSH session created
* SSH session established
* Fingerprint (SHA256): [1880B86E21ECABD2C21DD039FA1C6FD01BEAE0C739CACB1DB32A8B51BAA1B553]
* Authentication by public key succeed.