Small, portable embeddable SSHv2 client and server library in C with SCP, SFTP, port forwarding, and post-quantum key exchange for embedded and IoT systems.
wolfSSL's Embeddable SSH Server wolfSSH Manual
wolfSSH is dependent on wolfCrypt, found as a part of wolfSSL. The following is the simplest configuration of wolfSSL to enable 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 be
configured with keygen: --enable-keygen.
When using X.509 certificates for user authentication, wolfSSL must be
built with TLS enabled. wolfSSH uses wolfSSL's certificate manager system
for X.509, including OCSP lookups. To allow OCSP, add --enable-ocsp to the
wolfSSL configure.
If the bulk of wolfSSL code isn't desired, wolfSSL can be configured with
the crypto only option: --enable-cryptonly.
Additional build options for wolfSSL are located in chapter two. of the wolfSSH manual.
From the wolfSSH source directory run:
$ ./autogen.sh (if cloned from GitHub)
$ ./configure --with-wolfssl=[/usr/local]
$ make
$ make check
The autogen.sh script only has to be run the first time after cloning
the repository. If you have already run it or are using code from a
source archive, you should skip it.
For building under Windows with Visual Studio, see the file "ide/winvs/README.md".
NOTE: On resource constrained devices the DEFAULT_WINDOW_SZ may need
to be set to a lower size. It can also be increased in desktop use cases
to help with large file transfers. By default channels are set to receive
up to 128kB of data before sending a channel window adjust message. An
example 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 compiling
with CFLAGS=-D_FILE_OFFSET_BITS=64.
The directory examples contains an echoserver that any client should
be 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 a canned banner to the client:
wolfSSH Example Echo Server
Characters typed into the client will be echoed to the screen by the server. If the characters are echoed twice, the client has local echo enabled. The echoserver isn't being a proper terminal so the CR/LF translation will not work as expected.
The following control characters will trigger special actions in the echoserver:
After cloning the repository, be sure to make the testing private keys
read-only for the user, otherwise ssh 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 a password or public key. To use a password the command line:
$ ssh -p 22222 USER@localhost
Where the USER and password pairs are:
jill:upthehill
jack:fetchapail
To use public key authentication use the command line:
$ ssh -i ./keys/USER-key-TYPE.pem -p 22222 USER@localhost
Where the USER can be gretel or hansel, and TYPE is rsa or
ecc.
Keep in mind, the echoserver has several fake accounts in its
wsUserAuth() callback function. (jack, jill, hansel, and gretel) When
the shell support is enabled, those fake accounts will not work. They
don't exist in the system's passwd file. The users will authenticate,
but the server will err out because they don't exist in the system. You
can add your own username to the password or public key list in the
echoserver. That account will be logged into a shell started by the
echoserver with the privileges of the user running echoserver.
wolfSSH comes packaged with a few example tools for testing purposes and to demonstrate interoperability with other SSH implementations.
The echoserver is the workhorse of wolfSSH. It originally only allowed one to authenticate one of the canned account and would repeat the characters typed into it. When enabling shell support, it can spawn a user shell. It will need an actual user name on the machine and an updated 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 real client.
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 pseudo 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 a listener for local port forwarding or requests a listener for remote port forwarding. 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 copies the 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 and allows directory navigation, getting and putting files, making and removing directories, etc.
The sftpclient tool accepts the following command line options: