2021-10-07 13:19:01 -05:00
|
|
|
WOLFSSH
|
2014-06-23 12:07:57 -05:00
|
|
|
=======
|
|
|
|
|
2016-03-31 16:12:18 -05:00
|
|
|
wolfSSL's Embeddable SSH Server
|
2021-08-03 09:03:26 -05:00
|
|
|
[wolfSSH Manual](https://www.wolfssl.com/docs/wolfssh-manual/)
|
2016-03-31 16:12:18 -05:00
|
|
|
|
2016-10-23 18:00:40 -05:00
|
|
|
dependencies
|
|
|
|
------------
|
|
|
|
|
2022-02-04 12:03:44 -06:00
|
|
|
[wolfSSH](https://www.wolfssl.com/wolfssh/) is dependent on
|
|
|
|
[wolfCrypt](https://www.wolfssl.com/download/), found as a part of
|
|
|
|
wolfSSL. The following is the simplest configuration of wolfSSL to
|
|
|
|
enable wolfSSH.
|
2016-10-23 18:00:40 -05:00
|
|
|
|
|
|
|
$ cd wolfssl
|
2022-05-19 16:32:46 -05:00
|
|
|
$ ./configure [OPTIONS] --enable-ssh
|
2016-10-23 18:00:40 -05:00
|
|
|
$ make check
|
|
|
|
$ sudo make install
|
|
|
|
|
2021-08-03 09:03:26 -05:00
|
|
|
On some systems the optional ldconfig command is needed after installing.
|
|
|
|
|
2016-10-23 18:00:40 -05:00
|
|
|
To use the key generation function in wolfSSH, wolfSSL will need to be
|
|
|
|
configured with keygen: `--enable-keygen`.
|
|
|
|
|
2022-08-27 01:41:50 -05:00
|
|
|
When using X.509 certificates for user authentication, wolfSSL must be
|
|
|
|
built with TLS enabled. wolfSSH uses wolfSSL's certificate manager system
|
2022-02-09 18:08:20 -06:00
|
|
|
for X.509, including OCSP lookups. To allow OCSP, add `--enable-ocsp` to the
|
|
|
|
wolfSSL configure.
|
|
|
|
|
2016-10-23 18:00:40 -05:00
|
|
|
If the bulk of wolfSSL code isn't desired, wolfSSL can be configured with
|
|
|
|
the crypto only option: `--enable-cryptonly`.
|
|
|
|
|
2022-02-04 12:03:44 -06:00
|
|
|
Additional build options for wolfSSL are located in
|
|
|
|
[chapter two](https://www.wolfssl.com/docs/wolfssl-manual/ch2/).
|
|
|
|
of the wolfSSH manual.
|
2016-10-23 18:00:40 -05:00
|
|
|
|
2016-03-31 16:12:18 -05:00
|
|
|
building
|
|
|
|
--------
|
|
|
|
|
2021-08-03 09:03:26 -05:00
|
|
|
From the wolfSSH source directory run:
|
2016-03-31 16:12:18 -05:00
|
|
|
|
|
|
|
$ ./autogen.sh
|
2022-02-04 12:03:44 -06:00
|
|
|
$ ./configure --with-wolfssl=[/usr/local]
|
2016-03-31 16:12:18 -05:00
|
|
|
$ make
|
|
|
|
$ make check
|
|
|
|
|
2022-02-04 12:03:44 -06:00
|
|
|
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.
|
2016-03-31 16:12:18 -05:00
|
|
|
|
2017-09-13 13:38:19 -05:00
|
|
|
For building under Windows with Visual Studio, see the file
|
|
|
|
"ide/winvs/README.md".
|
|
|
|
|
2022-02-04 12:03:44 -06:00
|
|
|
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 handle
|
|
|
|
16,384 bytes of data being sent and received. An example of setting a
|
|
|
|
window size for new channels would be as follows
|
|
|
|
`./configure CPPFLAGS=-DDEFAULT_WINDOW_SZ=16384`
|
2016-10-23 18:00:40 -05:00
|
|
|
|
2022-07-29 08:07:58 -05:00
|
|
|
For 32bit Linux platforms you can add support for files > 2GB by compling
|
|
|
|
with `CFLAGS=-D_FILE_OFFSET_BITS=64`.
|
|
|
|
|
2016-03-31 16:12:18 -05:00
|
|
|
examples
|
|
|
|
--------
|
|
|
|
|
2022-02-04 12:03:44 -06:00
|
|
|
The directory `examples` contains an echoserver that any client should
|
|
|
|
be able to connect to. From the terminal run:
|
2016-03-31 16:12:18 -05:00
|
|
|
|
2021-10-07 13:19:01 -05:00
|
|
|
$ ./examples/echoserver/echoserver -f
|
2016-03-31 16:12:18 -05:00
|
|
|
|
2021-10-07 13:19:01 -05:00
|
|
|
The option `-f` enables echo-only mode. From another terminal run:
|
2016-03-31 16:12:18 -05:00
|
|
|
|
2022-02-04 12:03:44 -06:00
|
|
|
$ ssh jill@localhost -p 22222
|
2016-03-31 16:12:18 -05:00
|
|
|
|
2022-02-04 12:03:44 -06:00
|
|
|
When prompted for a password, enter "upthehill". The server will send a
|
|
|
|
canned banner to the client:
|
2016-03-31 16:12:18 -05:00
|
|
|
|
2017-07-14 14:24:38 -05:00
|
|
|
wolfSSH Example Echo Server
|
2016-03-31 16:12:18 -05:00
|
|
|
|
2022-02-04 12:03:44 -06:00
|
|
|
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.
|
2016-06-16 17:50:11 -05:00
|
|
|
|
2021-10-07 13:19:01 -05:00
|
|
|
The following control characters will trigger special actions in the
|
|
|
|
echoserver:
|
|
|
|
|
|
|
|
- CTRL-C: Terminate the connection.
|
|
|
|
- CTRL-E: Print out some session statistics.
|
|
|
|
- CTRL-F: Trigger a new key exchange.
|
|
|
|
|
2016-10-23 18:00:40 -05:00
|
|
|
|
2016-06-16 17:50:11 -05:00
|
|
|
testing notes
|
|
|
|
-------------
|
|
|
|
|
2022-02-04 12:03:44 -06:00
|
|
|
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.
|
2016-06-23 12:46:32 -05:00
|
|
|
|
2017-09-12 13:26:54 -05:00
|
|
|
$ chmod 0600 ./keys/gretel-key-rsa.pem ./keys/hansel-key-rsa.pem \
|
|
|
|
./keys/gretel-key-ecc.pem ./keys/hansel-key-ecc.pem
|
2016-06-23 12:46:32 -05:00
|
|
|
|
2022-02-04 12:03:44 -06:00
|
|
|
Authentication against the example echoserver can be done with a
|
|
|
|
password or public key. To use a password the command line:
|
2016-06-16 17:50:11 -05:00
|
|
|
|
2022-02-04 12:03:44 -06:00
|
|
|
$ ssh -p 22222 USER@localhost
|
2016-06-16 17:50:11 -05:00
|
|
|
|
2019-11-07 17:42:14 -06:00
|
|
|
Where the *USER* and password pairs are:
|
2016-06-16 17:50:11 -05:00
|
|
|
|
|
|
|
jill:upthehill
|
|
|
|
jack:fetchapail
|
|
|
|
|
|
|
|
To use public key authentication use the command line:
|
|
|
|
|
2022-02-04 12:03:44 -06:00
|
|
|
$ ssh -i ./keys/USER-key-TYPE.pem -p 22222 USER@localhost
|
2016-06-16 17:50:11 -05:00
|
|
|
|
2022-02-04 12:03:44 -06:00
|
|
|
Where the *USER* can be `gretel` or `hansel`, and *TYPE* is `rsa` or
|
|
|
|
`ecc`.
|
2016-07-06 13:12:07 -05:00
|
|
|
|
2022-02-04 12:03:44 -06:00
|
|
|
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.
|
2020-08-21 16:48:49 -05:00
|
|
|
|
2016-07-06 13:12:07 -05:00
|
|
|
|
2022-02-04 12:03:44 -06:00
|
|
|
EXAMPLE TOOLS
|
|
|
|
=============
|
2021-10-07 13:19:01 -05:00
|
|
|
|
2022-02-04 12:03:44 -06:00
|
|
|
wolfSSH comes packaged with a few example tools for testing purposes
|
|
|
|
and to demonstrate interoperability with other SSH implementations.
|
2021-10-07 13:19:01 -05:00
|
|
|
|
|
|
|
|
|
|
|
echoserver
|
|
|
|
----------
|
|
|
|
|
|
|
|
The echoserver is the workhorse of wolfSSH. It originally only allowed one
|
|
|
|
to authenticate one of the canned account and would repeat the characters
|
2022-02-04 12:03:44 -06:00
|
|
|
typed into it. When enabling [shell support](#shell-support), it can
|
2021-10-07 13:19:01 -05:00
|
|
|
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
|
|
|
|
|
|
|
|
|
|
|
|
client
|
|
|
|
------
|
|
|
|
|
|
|
|
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 psuedo terminal
|
|
|
|
-c <command> executes remote command and pipe stdin/stdout
|
|
|
|
-a Attempt to use SSH-AGENT
|
|
|
|
|
|
|
|
|
|
|
|
portfwd
|
|
|
|
-------
|
|
|
|
|
|
|
|
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)
|
|
|
|
|
|
|
|
|
|
|
|
scpclient
|
|
|
|
---------
|
|
|
|
|
|
|
|
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
|
|
|
|
|
|
|
|
|
|
|
|
sftpclient
|
|
|
|
----------
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
-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
|
|
|
|
|
|
|
|
|
|
|
|
server
|
|
|
|
------
|
|
|
|
|
|
|
|
This tool is a place holder.
|
|
|
|
|
|
|
|
|
|
|
|
SCP
|
|
|
|
===
|
2018-05-31 14:42:50 -05:00
|
|
|
|
|
|
|
wolfSSH includes server-side support for scp, which includes support for both
|
|
|
|
copying files 'to' the server, and copying files 'from' the server. Both
|
|
|
|
single file and recursive directory copy are supported with the default
|
|
|
|
send and receive callbacks.
|
|
|
|
|
|
|
|
To compile wolfSSH with scp support, use the `--enable-scp` build option
|
|
|
|
or define `WOLFSSL_SCP`:
|
|
|
|
|
|
|
|
$ ./configure --enable-scp
|
|
|
|
$ make
|
|
|
|
|
|
|
|
For full API usage and implementation details, please see the wolfSSH User
|
|
|
|
Manual.
|
|
|
|
|
|
|
|
The wolfSSL example server has been set up to accept a single scp request,
|
|
|
|
and is compiled by default when compiling the wolfSSH library. To start the
|
|
|
|
example server, run:
|
|
|
|
|
|
|
|
$ ./examples/server/server
|
|
|
|
|
|
|
|
Standard scp commands can be used on the client side. The following are a
|
|
|
|
few examples, where `scp` 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 in
|
|
|
|
verbose 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>
|
|
|
|
|
2018-09-13 14:24:11 -05:00
|
|
|
|
2021-10-07 13:19:01 -05:00
|
|
|
PORT FORWARDING
|
|
|
|
===============
|
2018-09-13 14:24:11 -05:00
|
|
|
|
2021-10-07 13:19:01 -05:00
|
|
|
wolfSSH provides support for port forwarding. This allows the user
|
2018-09-13 14:24:11 -05:00
|
|
|
to set up an encrypted tunnel to another server, where the SSH client listens
|
|
|
|
on a socket and forwards connections on that socket to another socket on
|
|
|
|
the server.
|
|
|
|
|
|
|
|
To compile wolfSSH with port forwarding support, use the `--enable-fwd` build
|
|
|
|
option or define `WOLFSSH_FWD`:
|
|
|
|
|
|
|
|
$ ./configure --enable-fwd
|
|
|
|
$ make
|
|
|
|
|
|
|
|
For full API usage and implementation details, please see the wolfSSH User
|
|
|
|
Manual.
|
|
|
|
|
2018-12-14 15:40:38 -06:00
|
|
|
The portfwd example tool will create a "direct-tcpip" style channel. These
|
2018-09-13 14:24:11 -05:00
|
|
|
directions assume you have OpenSSH's server running in the background with
|
|
|
|
port forwarding enabled. This example forwards the port for the wolfSSL
|
2018-09-18 16:39:38 -05:00
|
|
|
client to the server as the application. It assumes that all programs are run
|
2018-09-13 14:24:11 -05:00
|
|
|
on the same machine in different terminals.
|
|
|
|
|
|
|
|
src/wolfssl$ ./examples/server/server
|
2018-12-14 15:40:38 -06:00
|
|
|
src/wolfssh$ ./examples/portfwd/portfwd -p 22 -u <username> \
|
2018-09-18 16:39:38 -05:00
|
|
|
-f 12345 -t 11111
|
2018-09-13 14:24:11 -05:00
|
|
|
src/wolfssl$ ./examples/client/client -p 12345
|
|
|
|
|
|
|
|
By default, the wolfSSL server listens on port 11111. The client is set to
|
2018-12-14 15:40:38 -06:00
|
|
|
try to connect to port 12345. The portfwd logs in as user "username", opens
|
2018-09-13 14:24:11 -05:00
|
|
|
a listener on port 12345 and connects to the server on port 11111. Packets
|
|
|
|
are routed back and forth between the client and server. "Hello, wolfSSL!"
|
|
|
|
|
2018-12-14 15:40:38 -06:00
|
|
|
The source for portfwd provides an example on how to set up and use the
|
2018-09-13 14:24:11 -05:00
|
|
|
port forwarding support in wolfSSH.
|
2018-11-13 11:04:47 -06:00
|
|
|
|
2021-10-07 13:19:01 -05:00
|
|
|
The echoserver will handle local and remote port forwarding. To connect with
|
|
|
|
the ssh tool, using one of the following command lines. You can run either of
|
|
|
|
the ssh command lines from anywhere:
|
2018-11-13 11:04:47 -06:00
|
|
|
|
2021-10-07 13:19:01 -05:00
|
|
|
src/wolfssl$ ./examples/server/server
|
|
|
|
src/wolfssh$ ./examples/echoserver/echoserver
|
|
|
|
anywhere 1$ ssh -p 22222 -L 12345:localhost:11111 jill@localhost
|
|
|
|
anywhere 2$ ssh -p 22222 -R 12345:localhost:11111 jill@localhost
|
|
|
|
src/wolfssl$ ./examples/client/client -p 12345
|
|
|
|
|
|
|
|
This will allow port forwarding between the wolfSSL client and server like in
|
|
|
|
the previous example.
|
2018-11-13 11:04:47 -06:00
|
|
|
|
2021-10-07 13:19:01 -05:00
|
|
|
|
|
|
|
SFTP
|
|
|
|
====
|
2018-11-13 11:04:47 -06:00
|
|
|
|
|
|
|
wolfSSH provides server and client side support for SFTP version 3. This
|
|
|
|
allows the user to set up an encrypted connection for managing file systems.
|
|
|
|
|
|
|
|
To compile wolfSSH with SFTP support, use the `--enable-sftp` build option or
|
|
|
|
define `WOLFSSH_SFTP`:
|
|
|
|
|
|
|
|
$ ./configure --enable-sftp
|
|
|
|
$ make
|
|
|
|
|
|
|
|
For full API usage and implementation details, please see the wolfSSH User
|
|
|
|
Manual.
|
|
|
|
|
2018-12-17 11:29:30 -06:00
|
|
|
The SFTP client created is located in the directory examples/sftpclient/ and the
|
2018-11-13 11:04:47 -06:00
|
|
|
server is ran using the same echoserver as with wolfSSH.
|
|
|
|
|
2018-12-17 11:29:30 -06:00
|
|
|
src/wolfssh$ ./examples/sftpclient/wolfsftp
|
2018-11-13 11:04:47 -06:00
|
|
|
|
|
|
|
A full list of supported commands can be seen with typeing "help" after a
|
|
|
|
connection.
|
|
|
|
|
|
|
|
|
2019-04-22 12:18:28 -05:00
|
|
|
wolfSSH sftp> help
|
|
|
|
|
|
|
|
Commands :
|
|
|
|
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
|
2018-11-13 11:04:47 -06:00
|
|
|
|
|
|
|
An example of connecting to another system would be
|
|
|
|
|
2018-12-17 11:29:30 -06:00
|
|
|
src/wolfssh$ ./examples/sftpclient/wolfsftp -p 22 -u user -h 192.168.1.111
|
2020-07-08 15:53:53 -05:00
|
|
|
|
|
|
|
|
2021-10-07 13:19:01 -05:00
|
|
|
SHELL SUPPORT
|
|
|
|
=============
|
2021-08-03 09:03:26 -05:00
|
|
|
|
2020-07-08 15:53:53 -05:00
|
|
|
wolfSSH's example echoserver can now fork a shell for the user trying to log
|
|
|
|
in. This currently has only been tested on Linux and macOS. The file
|
|
|
|
echoserver.c must be modified to have the user's credentials in the user
|
|
|
|
authentication callback, or the user authentication callback needs to be
|
|
|
|
changed to verify the provided password.
|
|
|
|
|
|
|
|
To compile wolfSSH with shell support, use the `--enable-shell` build option
|
|
|
|
or define `WOLFSSH_SHELL`:
|
|
|
|
|
|
|
|
$ ./configure --enable-shell
|
|
|
|
$ make
|
|
|
|
|
|
|
|
By default, the echoserver will try to start a shell. To use the echo testing
|
|
|
|
behavior, give the echoserver the command line option `-f`.
|
|
|
|
|
|
|
|
$ ./examples/echoserver/echoserver -f
|
2022-03-24 13:17:35 -05:00
|
|
|
|
2022-02-09 18:08:20 -06:00
|
|
|
|
2022-03-24 13:17:35 -05:00
|
|
|
POST-QUANTUM
|
|
|
|
============
|
|
|
|
|
2022-08-05 11:59:43 -05:00
|
|
|
wolfSSH now supports the post-quantum algorithm Kyber. It uses the NIST
|
2022-03-24 13:17:35 -05:00
|
|
|
submission's Level 1 parameter set implemented by liboqs via an integration
|
2022-08-05 11:59:43 -05:00
|
|
|
with wolfSSH. It is hybridized with ECDHE over the P-256 ECC curve.
|
2022-03-24 13:17:35 -05:00
|
|
|
|
|
|
|
In order be able to use liboqs, you must have it built and installed on your
|
|
|
|
system. We support the 0.7.0 release of liboqs. You can download it from the
|
|
|
|
following link:
|
|
|
|
|
|
|
|
https://github.com/open-quantum-safe/liboqs/archive/refs/tags/0.7.0.tar.gz
|
|
|
|
|
|
|
|
Once unpacked, this would be sufficient:
|
|
|
|
|
|
|
|
$ cd liboqs-0.7.0
|
|
|
|
$ mkdir build
|
|
|
|
$ cd build
|
|
|
|
$ cmake -DOQS_USE_OPENSSL=0 ..
|
|
|
|
$ make all
|
|
|
|
$ sudo make install
|
|
|
|
|
|
|
|
|
2022-08-05 11:59:43 -05:00
|
|
|
In order to enable support for Kyber Level1 hybridized with ECDHE over the P-256
|
|
|
|
ECC curve in wolfSSH, use the `--with-liboqs` build option during configuration:
|
2022-03-24 13:17:35 -05:00
|
|
|
|
|
|
|
$ ./configure --with-liboqs
|
|
|
|
|
2022-08-05 11:59:43 -05:00
|
|
|
The wolfSSH client and server will automatically negotiate using Kyber Level1
|
|
|
|
hybridized with ECDHE over the P-256 ECC curve if this feature is enabled.
|
2022-03-24 13:17:35 -05:00
|
|
|
|
|
|
|
$ ./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, you
|
|
|
|
can build and execute the fork while the echoserver is running. Download the
|
|
|
|
release 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
|
2022-09-07 12:31:17 -05:00
|
|
|
$ ./ssh -o"KexAlgorithms +ecdh-nistp256-kyber-512-sha256" \
|
2022-03-24 13:17:35 -05:00
|
|
|
-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 echoed
|
|
|
|
back. Use CTRL-C to terminate the connection.
|
2022-02-09 18:08:20 -06:00
|
|
|
|
|
|
|
|
|
|
|
CERTIFICATE SUPPORT
|
|
|
|
===================
|
|
|
|
|
|
|
|
wolfSSH can accept X.509 certificates in place of just public keys when
|
2022-08-27 01:41:50 -05:00
|
|
|
authenticating a user.
|
2022-02-09 18:08:20 -06:00
|
|
|
|
|
|
|
To compile wolfSSH with X.509 support, use the `--enable-certs` build option
|
|
|
|
or define `WOLFSSH_CERTS`:
|
|
|
|
|
|
|
|
$ ./configure --enable-certs
|
|
|
|
$ make
|
|
|
|
|
|
|
|
To provide a CA root certificate to validate a user's certificate, give the
|
|
|
|
echoserver the command line option `-a`.
|
|
|
|
|
2022-08-30 11:38:01 -05:00
|
|
|
$ ./examples/echoserver/echoserver -a ./keys/ca-cert-ecc.pem
|
2022-02-09 18:08:20 -06:00
|
|
|
|
|
|
|
The echoserver and client have a fake user named "john" whose certificate
|
|
|
|
will be used for authentication.
|
2022-08-27 01:41:50 -05:00
|
|
|
|
|
|
|
An example echoserver / client connection using the example certificate
|
|
|
|
john-cert.der would be:
|
|
|
|
|
2022-08-30 11:38:01 -05:00
|
|
|
$ ./examples/echoserver/echoserver -a ./keys/ca-cert-ecc.pem -K john:./keys/john-cert.der
|
2022-08-27 01:41:50 -05:00
|
|
|
|
|
|
|
$ ./examples/client/client -u john -J ./keys/john-cert.der -i ./keys/john-key.der
|
|
|
|
|