Skip to content

Connecting & Authentication

Creating a client

Three equivalent ways:

      ⍝ positional: Host [Port [Username [Password]]]
      c←⎕NEW SSHClient ('host.example' 2222 'alice' 'secret')
      c←⎕NEW SSHClient (⊂'host.example')      ⍝ host only, port 22

      ⍝ namespace of field settings
      ns←⎕NS ''
      ns.(Host Port Username)←'host.example' 2222 'alice'
      ns.KeyFile←'/home/alice/.ssh/id_rsa'
      c←⎕NEW SSHClient ns

      ⍝ the shared helper (returns an error namespace instead of
      ⍝ signalling if construction fails)
      c←SSHClient.New 'host.example' 2222 'alice'

Fields can also be set after construction; nothing is used until Connect.

What Connect does

c.Connect performs the whole SSH-2 establishment in one call:

  1. opens the TCP connection (Conga)
  2. exchanges identification banners (RFC 4253 §4.2)
  3. negotiates algorithms and runs the Diffie–Hellman group14 key exchange
  4. verifies the server's host-key signature, then checks the key against known_hosts (details)
  5. switches the transport to AES-128-CTR + HMAC-SHA-256
  6. requests the ssh-userauth service and authenticates

It returns a result namespace: rc 0 means encrypted, authenticated, and ready. On any failure the TCP connection is torn down and the instance is left clean, so a later Connect on the same instance starts fresh.

Authentication methods

Connect picks the method from the fields, in this order:

Priority Condition Method
1 Password non-empty password authentication
2 KeyFile non-empty RSA public-key authentication
3 ~/.ssh/id_rsa exists public-key with the discovered key

The home directory is $HOME on Linux/macOS and %USERPROFILE% on Windows.

Key files must be OpenSSH-format (openssh-key-v1), unencrypted, RSA:

ssh-keygen -t rsa -b 2048 -N '' -f mykey

Passphrase-protected keys and other key types (ed25519, ECDSA) are rejected with a clear message — see Algorithms & Limitations.

Lifecycle

      r←c.Connect      ⍝ rc 0 → session up
      ⍝ ... any number of Exec / SFTP calls ...
      r←c.Close        ⍝ polite SSH disconnect + TCP close
      r←c.Connect      ⍝ the same instance can connect again
  • Close is always safe: closing a never-connected or already-closed client returns rc 0 with msg 'Already disconnected'.
  • After Close, operations return rc ¯1 with msg 'Not connected – call Connect first'.
  • Reconnecting performs a full new handshake with fresh keys.

The one-shot Do

SSHClient.Do is a shared method that creates, connects, execs, and closes in one call, returning the Exec result:

      SSHClient.Do 'host.example' 'echo hi'                    ⍝ (Host Cmd)
      SSHClient.Do 'host.example' 'alice' 'secret' 'echo hi'   ⍝ (Host User Pass Cmd)

      ns←⎕NS ''                        ⍝ namespace: any field + Cmd
      ns.(Host Port Username Password)←'host.example' 2222 'alice' 'secret'
      ns.Cmd←'echo hi'
      SSHClient.Do ns

The positional forms always use port 22; use the namespace form for any other port or for key-based auth. Invalid argument shapes are reported in msg, never signalled.