Skip to main content

Using SSH

The %Net.SSH package provides support for SSH (Secure ShellOpens in a new tab) communications. This topic briefly introduces the classes in this package.

Caution:

OpenSSL 3.0 introduces a new concept of providers, which packages groups of algorithm implementations. One provider is the Legacy provider. Neither OpenSSL nor InterSystems IRIS® data platform loads the Legacy provider by default.

InterSystems recommends that you do not use the Legacy provider’s algorithms; a complete list of these algorithms can be found in the OpenSSL documentationOpens in a new tab. InterSystems cannot guarantee that any legacy algorithm is compatible with InterSystems IRIS.

Creating an SSH Session

%Net.SSH.SessionOpens in a new tab represents an SSH session. To use this class:

  1. Create an instance of the class.

  2. Use the Connect() instance method to connect to a server.

  3. Use either AuthenticateWithKeyPair(), AuthenticateWithUsername(), or AuthenticateWithKeyboardInteractive() to authenticate yourself to the server. For details, see the class reference for %Net.SSH.SessionOpens in a new tab.

  4. Use additional methods of %Net.SSH.SessionOpens in a new tab to perform SCP (Secure Copy) operations of single files to and from the remote system, execute remote commands, tunnel TCP traffic, or perform SFTP operations. See the class reference for %Net.SSH.SessionOpens in a new tab.

    For example, use OpenSFTP to use the session for SFTP operations. This method returns, by reference, an instance of %Net.SSH.SFTPOpens in a new tab that you can use for SFTP operations. See the example in the next section.

Important:
  • For information on the supported platforms where you can use these classes, see the class reference for %Net.SSH.SessionOpens in a new tab and %Net.SSH.SFTPOpens in a new tab.

  • SSH connections that use OpenSSL 3.0 do not support Blowfish or CAST as the cipher algorithm. If you attempt to establish such a connection, the attempt will fail.

OpenSSH and PEM-Encoded Keys

To authenticate, you use a public/private key pair and passphrase (for the private key). The public keys must be in OpenSSH format, and the private keys must be PEM-encoded. This section provides some basic information to help you determine whether you have the right keys.

OpenSSH format looks like this example (except that the format does not include the artificial line breaks shown here):

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCfi2Vq+u0rtt2OC84pyrkq1k7WkrS+s76u3a
+2gdD43KQ2Z3vSUUfksymJjp11JBZEpOtBVIAy221UKdc7j7Qk6sUjZaK8LIy+bzDVwMyFWgVv
Qge7EjdWjrJLBRCDXYML6y1Y25XexThkTWSGyXzGNdr+wfIHYn/mIt0hfvrusauvT/9Wz8K2MG
Aj4BL7UQZpFJrlXzGmewe6++6cZDQQYi0aztwLK798oc9j0LsccdMpqWrjqoU1uANFhYIuUu/T4
7TEhT+e6M+KFYK5TR998eJTO25IjdN2Tgw0feXhQFF/nngbol0bA4auSPaZQsgokKK+E+Q/8UtBd
etEofuV user@hostname 

PEM encoded private keys have a header at the top of the file which looks like this:

--{}{}BEGIN RSA PRIVATE KEY{}{}-- 

The file ends with a similar footer:

--{}{}END RSA PRIVATE KEY{}{}-- 

Example: Listing Files via SFTP

The following method shows how you can write a list of the files on a server, via SFTP:

Method SFTPDir(ftpserver, username, password) As %Status
{
    set ssh = ##class(%Net.SSH.Session).%New()
    set status = ssh.Connect(ftpserver)
    set status = ssh.AuthenticateWithUsername(username,password)
    //open an SFTP session and get that returned by reference
    set status = ssh.OpenSFTP(.sftp)
    //get a list of files
    set status = sftp.Dir(".",.files)
    set i=$ORDER(files(""))
    while i'="" {
        write $listget(files(i),1),!
        set i=$ORDER(files(i))
    }
    quit $$$OK
}

Example: Authenticate with Keyboard Interactive

The following Terminal session demonstrates how to use AuthenticateWithKeyboardInteractive():

%SYS>set host="192.168.2.100"
%SYS>set lambda="(u,i,p,f,c)  quit $listbuild(c(""password""))"
%SYS>set context("password")="fountain"
%SYS>set sess=##class(%Net.SSH.Session).%New()
%SYS>s status=sess.Connect(host)
%SYS>set status=sess.AuthenticateWithKeyboardInteractive("root",lambda,.context)

Example: Execute a Remote Command

The following examples demonstrate how to use Execute():

 // %Net.SSH.Session.Execute
 // Specify the initial SSH connection information
 Set host="192.168.2.37"
 Set username = "SSHUser"
 Set password = "SSHPassword"
 // Set up the initial SSH connection
 // localhost <--SSH--> 192.168.2.37
 Set sshSession = ##class(%Net.SSH.Session).%New()
 Set statusConnection = sshSession.Connect(host) 
 Set statusConnection = sshSession.AuthenticateWithUsername(username,password)
 // Specify the command to execute on the remote host
 Set command = "uname -a"
 // Execute the command over the SSH connection
 // tDevice is a pass-by-reference value to store the raw data passing through the connection
 Set statusConnection = sshSession.Execute(command,.tDevice)

Example: Port Forward

The following examples demonstrate how to use ForwardPort()

 // %Net.SSH.Session.ForwardPort
 // Specify the initial SSH connection information
 Set host="192.168.2.37" 
 Set username = "SSHUser"
 Set password = "SSHPassword"
 // Set up the initial SSH connection
 // localhost <--SSH--> 192.168.2.37
 Set sshSession = ##class(%Net.SSH.Session).%New()
 Set statusConnection = sshSession.Connect(host) 
 Set statusConnection = sshSession.AuthenticateWithUsername(username,password)
 // Specify the remote port forward information
 Set remotehost = "192.168.2.100"
 Set remoteport = 80
 // Forward traffic via the SSH connection to a remote host:port 
 // localhost <--SSH--> 192.168.2.37 --SSHPortFwd--> 192.168.2.100:80
 // tDevice is a pass-by-reference value to store the raw data passing through the connection
 Set statusConnection = sshSession.ForwardPort(remotehost,remoteport,.tDevice)
FeedbackOpens in a new tab