SSH Examples

Secure Shell 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 session.CheckHost(known, False) Then
      If session.LastError = SSH.ERR_HOSTKEY_NOTFOUND Then
        Call MsgBox("Fingerprint not known!", 16, "Unknown server")
        Return
        
      ElseIf session.LastError = SSH.ERR_HOSTKEY_MISMATCH Then
        Call MsgBox("Fingerprint has changed!", 16, "Security breach")
        Return
        
      ElseIf session.LastError <> 0 Then
        Call MsgBox("Unable to verify fingerprint.", 16, "Unknown error")
        Return
        
      End If
    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 method is "public key" authentication. In this method the user proves their identity by proving they possess the private half of a digital signature keypair. The private key (and associated public key) may be provided as files or from memory.

  ' pubKey and privKey could be FolderItems or MemoryBlocks
  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 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. You can use the session object to create other objects, such as Channels, SFTPSessions, TCPTunnels, etc. which will all efficiently share the single connection owned and secured by the session.

See also

• SSH.Connect convenience method