Repository files navigation

wolfSSL's Embeddable SSH ServerwolfSSH Manual

wolfSSH is dependent onwolfCrypt, found as a part ofwolfSSL. The following is the simplest configuration of wolfSSL toenable wolfSSH.

$ cd wolfssl$ ./configure [OPTIONS] --enable-ssh$ make check$ sudo make install

On some systems the optional ldconfig command is needed after installing.

To use the key generation function in wolfSSH, wolfSSL will need to beconfigured with keygen:--enable-keygen.

When using X.509 certificates for user authentication, wolfSSL must bebuilt with TLS enabled. wolfSSH uses wolfSSL's certificate manager systemfor X.509, including OCSP lookups. To allow OCSP, add--enable-ocsp to thewolfSSL configure.

If the bulk of wolfSSL code isn't desired, wolfSSL can be configured withthe crypto only option:--enable-cryptonly.

Additional build options for wolfSSL are located inchapter two.of the wolfSSH manual.

From the wolfSSH source directory run:

$ ./autogen.sh$ ./configure --with-wolfssl=[/usr/local]$ make$ make check

Theautogen.sh script only has to be run the first time after cloningthe repository. If you have already run it or are using code from asource archive, you should skip it.

For building under Windows with Visual Studio, see the file"ide/winvs/README.md".

NOTE: On resource constrained devices theDEFAULT_WINDOW_SZ may needto be set to a lower size. It can also be increased in desktop use casesto help with large file transfers. By default channels are set to receiveup to 128kB of data before sending a channel window adjust message. Anexample of setting a window size for new channels would be as follows./configure CPPFLAGS="-DDEFAULT_WINDOW_SZ=16384"

For 32bit Linux platforms you can add support for files > 2GB by complingwithCFLAGS=-D_FILE_OFFSET_BITS=64.

The directoryexamples contains an echoserver that any client shouldbe able to connect to. From the terminal run:

$ ./examples/echoserver/echoserver -f

The option-f enables echo-only mode. From another terminal run:

$ ssh jill@localhost -p 22222

When prompted for a password, enter "upthehill". The server will send acanned banner to the client:

wolfSSH Example Echo Server

Characters typed into the client will be echoed to the screen by theserver. If the characters are echoed twice, the client has local echoenabled. The echoserver isn't being a proper terminal so the CR/LFtranslation will not work as expected.

The following control characters will trigger special actions in theechoserver:

• CTRL-C: Terminate the connection.
• CTRL-E: Print out some session statistics.
• CTRL-F: Trigger a new key exchange.

After cloning the repository, be sure to make the testing private keysread-only for the user, otherwisessh will tell you to do it.

$ chmod 0600 ./keys/gretel-key-rsa.pem ./keys/hansel-key-rsa.pem \             ./keys/gretel-key-ecc.pem ./keys/hansel-key-ecc.pem

Authentication against the example echoserver can be done with apassword or public key. To use a password the command line:

$ ssh -p 22222 USER@localhost

Where theUSER and password pairs are:

jill:upthehilljack:fetchapail

To use public key authentication use the command line:

$ ssh -i ./keys/USER-key-TYPE.pem -p 22222 USER@localhost

Where theUSER can begretel orhansel, andTYPE isrsa orecc.

Keep in mind, the echoserver has several fake accounts in itswsUserAuth() callback function. (jack, jill, hansel, and gretel) Whenthe shell support is enabled, those fake accounts will not work. Theydon't exist in the system'spasswd file. The users will authenticate,but the server will err out because they don't exist in the system. Youcan add your own username to the password or public key list in theechoserver. That account will be logged into a shell started by theechoserver with the privileges of the user running echoserver.

wolfSSH comes packaged with a few example tools for testing purposesand to demonstrate interoperability with other SSH implementations.

The echoserver is the workhorse of wolfSSH. It originally only allowed oneto authenticate one of the canned account and would repeat the characterstyped into it. When enablingshell support, it canspawn a user shell. It will need an actual user name on the machine and anupdated user authentication callback function to validate the credentials.The echoserver can also handle SCP and SFTP connections.

The echoserver tool accepts the following command line options:

-1             exit after a single (one) connection-e             expect ECC public key from client-E             use ECC private key-f             echo input-p <num>       port to accept on, default 22222-N             use non-blocking sockets-d <string>    set the home directory for SFTP connections-j <file>      load in a public key to accept from peer

The client establishes a connection to an SSH server. In its simplest mode,it sends the string "Hello, wolfSSH!" to the server, prints the response,and then exits. With the pseudo terminal option, the client will be a realclient.

The client tool accepts the following command line options:

-h <host>      host to connect to, default 127.0.0.1-p <num>       port to connect on, default 22222-u <username>  username to authenticate as (REQUIRED)-P <password>  password for username, prompted if omitted-e             use sample ecc key for user-i <filename>  filename for the user's private key-j <filename>  filename for the user's public key-x             exit after successful connection without doing               read/write-N             use non-blocking sockets-t             use psuedo terminal-c <command>   executes remote command and pipe stdin/stdout-a             Attempt to use SSH-AGENT

The portfwd tool establishes a connection to an SSH server and sets up alistener for local port forwarding or requests a listener for remote portforwarding. After a connection, the tool terminates.

The portfwd tool accepts the following command line options:

-h <host>      host to connect to, default 127.0.0.1-p <num>       port to connect on, default 22222-u <username>  username to authenticate as (REQUIRED)-P <password>  password for username, prompted if omitted-F <host>      host to forward from, default 0.0.0.0-f <num>       host port to forward from (REQUIRED)-T <host>      host to forward to, default to host-t <num>       port to forward to (REQUIRED)

The scpclient, wolfscp, establishes a connection to an SSH server and copiesthe specified files from or to the local machine.

The scpclient tool accepts the following command line options:

-H <host>      host to connect to, default 127.0.0.1-p <num>       port to connect on, default 22222-u <username>  username to authenticate as (REQUIRED)-P <password>  password for username, prompted if omitted-L <from>:<to> copy from local to server-S <from>:<to> copy from server to local

The sftpclient, wolfsftp, establishes a connection to an SSH server andallows directory navigation, getting and putting files, making and removingdirectories, etc.

The sftpclient tool accepts the following command line options:

-h <host>      host to connect to, default 127.0.0.1-p <num>       port to connect on, default 22222-u <username>  username to authenticate as (REQUIRED)-P <password>  password for username, prompted if omitted-d <path>      set the default local path-N             use non blocking sockets-e             use ECC user authentication-l <filename>  local filename-r <filename>  remote filename-g             put local filename as remote filename-G             get remote filename as local filename

wolfSSH includes server-side support for scp, which includes support for bothcopying files 'to' the server, and copying files 'from' the server. Bothsingle file and recursive directory copy are supported with the defaultsend and receive callbacks.

To compile wolfSSH with scp support, use the--enable-scp build optionor defineWOLFSSH_SCP:

$ ./configure --enable-scp$ make

For full API usage and implementation details, please see the wolfSSH UserManual.

The wolfSSH example server has been set up to accept a single scp request,and is compiled by default when compiling the wolfSSH library. To start theexample server, run:

$ ./examples/server/server

Standard scp commands can be used on the client side. The following are afew examples, wherescp represents the ssh client you are using.

To copy a single file TO the server, using the default example user "jill":

$ scp -P 22222 <local_file> jill@127.0.0.1:<remote_path>

To copy the same single file TO the server, but with timestamp and inverbose mode:

$ scp -v -p -P 22222 <local_file> jill@127.0.0.1:<remote_path>

To recursively copy a directory TO the server:

$ scp -P 22222 -r <local_dir> jill@127.0.0.1:<remote_dir>

To copy a single file FROM the server to the local client:

$ scp -P 22222 jill@127.0.0.1:<remote_file> <local_path>

To recursively copy a directory FROM the server to the local client:

$ scp -P 22222 -r jill@127.0.0.1:<remote_dir> <local_path>

wolfSSH provides support for port forwarding. This allows the userto set up an encrypted tunnel to another server, where the SSH client listenson a socket and forwards connections on that socket to another socket onthe server.

To compile wolfSSH with port forwarding support, use the--enable-fwd buildoption or defineWOLFSSH_FWD:

$ ./configure --enable-fwd$ make

For full API usage and implementation details, please see the wolfSSH UserManual.

The portfwd example tool will create a "direct-tcpip" style channel. Thesedirections assume you have OpenSSH's server running in the background withport forwarding enabled. This example forwards the port for the wolfSSLclient to the server as the application. It assumes that all programs are runon the same machine in different terminals.

src/wolfssl$ ./examples/server/serversrc/wolfssh$ ./examples/portfwd/portfwd -p 22 -u <username> \             -f 12345 -t 11111src/wolfssl$ ./examples/client/client -p 12345

By default, the wolfSSL server listens on port 11111. The client is set totry to connect to port 12345. The portfwd logs in as user "username", opensa listener on port 12345 and connects to the server on port 11111. Packetsare routed back and forth between the client and server. "Hello, wolfSSL!"

The source for portfwd provides an example on how to set up and use theport forwarding support in wolfSSH.

The echoserver will handle local and remote port forwarding. To connect withthe ssh tool, using one of the following command lines. You can run either ofthe ssh command lines from anywhere:

src/wolfssl$ ./examples/server/serversrc/wolfssh$ ./examples/echoserver/echoserveranywhere 1$ ssh -p 22222 -L 12345:localhost:11111 jill@localhostanywhere 2$ ssh -p 22222 -R 12345:localhost:11111 jill@localhostsrc/wolfssl$ ./examples/client/client -p 12345

This will allow port forwarding between the wolfSSL client and server like inthe previous example.

wolfSSH provides server and client side support for SFTP version 3. Thisallows the user to set up an encrypted connection for managing file systems.

To compile wolfSSH with SFTP support, use the--enable-sftp build option ordefineWOLFSSH_SFTP:

$ ./configure --enable-sftp$ make

For full API usage and implementation details, please see the wolfSSH UserManual.

The SFTP client created is located in the directory examples/sftpclient/ andthe example echoserver acts as a SFTP server.

src/wolfssh$ ./examples/sftpclient/wolfsftp

A full list of supported commands can be seen with typing "help" after aconnection.

wolfSSH sftp> helpCommands :    cd  <string>                      change directory    chmod <mode> <path>               change mode    get <remote file> <local file>    pulls file(s) from server    ls                                list current directory    mkdir <dir name>                  creates new directory on server    put <local file> <remote file>    push file(s) to server    pwd                               list current path    quit                              exit    rename <old> <new>                renames remote file    reget <remote file> <local file>  resume pulling file    reput <remote file> <local file>  resume pushing file    <crtl + c>                        interrupt get/put cmd

An example of connecting to another system would be

src/wolfssh$ ./examples/sftpclient/wolfsftp -p 22 -u user -h 192.168.1.111

wolfSSH's example echoserver can now fork a shell for the user trying to login. This currently has only been tested on Linux and macOS. The fileechoserver.c must be modified to have the user's credentials in the userauthentication callback, or the user authentication callback needs to bechanged to verify the provided password.

To compile wolfSSH with shell support, use the--enable-shell build optionor defineWOLFSSH_SHELL:

$ ./configure --enable-shell$ make

To try out this functionality, you can use the example echoserver and client.In a terminal do the following to launch the server:

$ ./examples/echoserver/echoserver -P <user>:junk

And in another terminal do the following to launch the example client:

$ ./examples/client/client -t -u <user> -P junk

Note that<user> must be the user name of the current user that is logged in.

By default, the echoserver will try to start a shell. To use the echo testingbehavior, give the echoserver the command line option-f.

$ ./examples/echoserver/echoserver -f

To use the shell feature with wolfsshd add--enable-sshd to your configurecommand and use the following command:

$ sudo ./apps/wolfsshd/wolfsshd -D -h keys/gretel-key-ecc.pem -p 11111

If it complains about a badsshd_config file, simply copy it to another fileand remove the offending line that it complains about and use the-f commandline parameter to point to the new file.

You can then connect to thewolfsshd server with ssh:

$ ssh <user>@localhost -p 11111

Note that<user> must be the user name of the current user that is logged in.

wolfSSH now supports Curve25519 for key exchange. To enable this support simplycompile wolfSSL with support for wolfssh and Curve25519.

$ cd wolfssl$ ./configure --enable-wolfssh --enable-curve25519

After building and installing wolfSSL, you can simply configure with no options.

$ cd wolfssh$ ./configure

The wolfSSH client and server will automatically negotiate using Curve25519.

$ ./examples/echoserver/echoserver -f$ ./examples/client/client -u jill -P upthehill

wolfSSH now supports the post-quantum algorithm ML-KEM (formerly known asKyber). It uses the ML-KEM-768 parameter set and is hybridized with ECDHE overthe P-256 ECC curve.

In order to use this key exchange you must build and install wolfSSL on yoursystem. Here is an example of an effective configuration:

$ ./configure --enable-wolfssh --enable-mlkem

After that, simply configure and build wolfssh as usual:

$ ./configure$ make all

The wolfSSH client and server will automatically negotiate using ML-KEM-768hybridized with ECDHE over the P-256 ECC curve.

$ ./examples/echoserver/echoserver -f$ ./examples/client/client -u jill -P upthehill

On the client side, you will see the following output:

Server said: Hello, wolfSSH!

If you want to see inter-operability with OpenQauntumSafe's fork of OpenSSH, youcan build and execute the fork while the echoserver is running. Download therelease from here:

https://github.com/open-quantum-safe/openssh/archive/refs/tags/OQS-OpenSSH-snapshot-2021-08.tar.gz

The following is sufficient for build and execution:

$ tar xmvf openssh-OQS-OpenSSH-snapshot-2021-08.tar.gz$ cd openssh-OQS-OpenSSH-snapshot-2021-08/$ ./configure --with-liboqs-dir=/usr/local$ make all$ ./ssh -o"KexAlgorithms=mlkem768nistp256-sha256" \  -o"PubkeyAcceptedAlgorithms +ssh-rsa" \  -o"HostkeyAlgorithms +ssh-rsa" \  jill@localhost -p 22222

NOTE: when prompted, enter the password which is "upthehill".

You can type a line of text and when you press enter, the line will be echoedback. Use CTRL-C to terminate the connection.

wolfSSH can accept X.509 certificates in place of just public keys whenauthenticating a user.

To compile wolfSSH with X.509 support, use the--enable-certs build optionor defineWOLFSSH_CERTS:

$ ./configure --enable-certs CPPFLAGS=-DWOLFSSH_NO_FPKI$ make

For this example, we are disabling the FPKI checking as the includedcertificate for "fred" does not have the required FPKI extensions. If theflag WOLFSSH_NO_FPKI is removed, you can see the certificate get rejected.

To provide a CA root certificate to validate a user's certificate, give theechoserver the command line option-a.

$ ./examples/echoserver/echoserver -a ./keys/ca-cert-ecc.pem

The echoserver and client have a fake user named "fred" whose certificatewill be used for authentication.

An example echoserver / client connection using the example certificatefred-cert.der would be:

$ ./examples/echoserver/echoserver -a ./keys/ca-cert-ecc.pem -K fred:./keys/fred-cert.der$ ./examples/client/client -u fred -J ./keys/fred-cert.der -i ./keys/fred-key.der

wolfSSH comes with a server daemon and a command line shell tool. Check outthe apps directory for more information.