SSH Examples

Secure Shell Protocol version 2

Secure Shell (SSH) version 2 is a protocol for secure remote login and other services over an insecure network. It is described in RFC memos 4250 Protocol Assigned Numbers, 4251 Protocol Architecture, 4252 Authentication Protocol, 4253 Transport Layer Protocol, and 4254 Connection Protocol.

Creating a session and establishing a connection

The first step in establishing a new SSH connection is to create a session.

  Dim session As New SSH.Session()

A new session is not yet connected to anything. A connection is established by providing the hostname or IP address and the port number to the Session.Connect method.

  Dim session As New SSH.Session()
  If Not session.Connect("ssh.example.com", 22) Then MsgBox("Connection failed!")

Checking the server's fingerprint

If the connection was successful then you are ready to proceed to the known host fingerprint verification phase. This phase is optional but strongly recommended (code continues from above).

  ' locate the user's known_hosts file (or supply your own)
  Dim f As FolderItem = SpecialFolder.UserHome.Child(".ssh")
  If f.Exists Then f = f.Child("known_hosts")
  If f.Exists Then
    Dim known As New SSH.KnownHosts(session)
    Call known.Load(f)
    
    If Not known.Lookup(session) Then ' session is the connected SSH.Session you want to check
      Select Case known.LastError
      Case SSH.ERR_HOSTKEY_NOTFOUND
        If MsgBox("Add this host's fingerprint?", 4 + 48, "Fingerprint not known!") <> 6 Then Return
        
      Case SSH.ERR_HOSTKEY_MISMATCH
        If MsgBox("Accept the changed fingerprint?", 4 + 48, "Fingerprint has changed!") <> 6 Then Return
        
      Else
        Call MsgBox("Unable to verify fingerprint.", 16, "Unknown error")
        Return
        
      End Select
      
      known.AddHost(session)
      known.Save(f)
    End If
  End If
  
  ' proceed with the session by sending the credentials

Authenticating to the server

Now that the server's fingerprint has been checked you can begin the authentication phase. Authentication can be by one of several methods: password, public key, or agent-mediated.

The simplest (and least secure) is password authentication.

  If not session.SendCredentials("myUsername", "mySeekritPassword") Then MsgBox("Username/password rejected!")

A more secure authentication method is using a public key. In this method the user proves their identity by proving they posess the private half of a digital signature keypair. The private key (and associated public key) may be provided as files or from memory.

  If Not session.SendCredentials("myUsername", pubKey, privKey, "privKeyPassword") Then MsgBox("Username/key rejected!")

A modified version of the public key method is the agent-mediated method. In this method, a key management service running on the local system (the "agent") controls access to the private half of the user's key and authenticates to servers on behalf of other applications on the system. In this method the client (your app) never even sees the user's keys.

Dim agent As New SSH.Agent(session)
  If Not agent.Connect() Then MsgBox("Can't contact agent!")
  If Not agent.Refresh() Then MsgBox("Can't get the key list!")
  Dim c As Integer = agent.Count - 1
  For i As Integer = 0 To c
    If session.SendCredentials("myUsername", agent, i) Then ' try each key in sequence
      MsgBox("Logged in successfully!")
      Exit For
    End If
  Next
  agent.Disconnect()

SSH session established

You have now created a new SSH session and successfully authenticated to a server, and hopefully you checked its fingerprint to be sure it's the server you are expecting. Using the session object you can create other objects, such as Channels, SFTPSessions, TCPTunnels, etc. that will all efficiently share the single connection owned and secured by the session.