ponyssh

A production-grade SSH-2 client/server library for Pony.

Status

ponyssh is alpha-level software that will change frequently. Expect breaking changes. That said, you should feel comfortable experimenting with it in your projects.

Installation

• Install corral
• corral add github.com/contact-red/ponyssh.git --version 0.1.0
• corral fetch to fetch your dependencies
• use "ssh_server" (and/or use "ssh_client") to include the package you need:
  • use "ssh_client" — create outbound client sessions
  • use "ssh_server" — accept inbound connections
  • use "ssh_transport" — session, notify interfaces, algorithm preferences
  • use "ssh_connection" — channel multiplexing and PTY support
  • use "ssh_auth" — authentication message types
  • use "ssh_crypto" — cipher, MAC, and key primitives
  • use "ssh_error" — error union types
• corral run -- ponyc -D openssl_3.0.x to compile your application

Dependencies

ponyssh links against OpenSSL 3.0.x at compile time and selects the backend with the openssl_3.0.x compile-time define. You need the OpenSSL development files installed in your build environment.

Installing on APT based Linux distributions

sudo apt-get install -y libssl-dev

Installing on RPM based Linux distributions

sudo dnf install openssl-devel

Installing on macOS with Homebrew

brew update
brew install openssl@3

Usage

A minimal echo server. See examples/echo-server for the complete, runnable version.

use "lori"
use "ssh_transport"
use "ssh_server"

actor Main
  new create(env: Env) =>
    let pem: Array[U8] val = MyHostKey()  // your host key, PEM-encoded

    // SshServerConfig validates the host key, so its constructor is partial.
    // Algorithm preferences default to the implemented set; to customise them
    // pass `SshAlgorithmPreferences` with named arguments and override only the
    // categories you need.
    let config =
      try
        SshServerConfig(pem, "0.0.0.0", "2222")?
      else
        env.out.print("invalid host key; aborting")
        return
      end

    let auth = TCPListenAuth(env.root)
    SshListener(auth, config, MyServerNotify(env))

Your MyServerNotify implements SshServerNotify. Authentication and authorization deny by default: implement validate_password / validate_publickey to accept credentials, and override the channel/shell callbacks to grant access (they reject unless overridden).

A minimal client:

use "lori"
use "ssh_transport"
use "ssh_auth"
use "ssh_client"

actor Main
  new create(env: Env) =>
    let config = SshClientConfig("example.com", "22", "alice",
      recover val [as SshAuthMethod val: SshPasswordAuth("hunter2")] end)
    let auth = TCPConnectAuth(env.root)
    SshConnector.connect(auth, config, MyClientNotify(env))

MyClientNotify implements SshClientNotify. It must approve the server host key in ssh_verify_host_key (call session.accept_host_key() or session.reject_host_key()) and acts on the session once ssh_ready fires.

API Documentation

https://ponyssh.contact.red/