Merge pull request #80 from ejohnstown/wolfssh-update

dgarske · web-flow · commit a6ab7499844e · 2022-12-28T18:30:26.000-08:00
wolfSSH Update
diff --git a/wolfSSH/src/chapter01.md b/wolfSSH/src/chapter01.md
@@ -10,36 +10,33 @@ SSH is a layered set of protocols that provide multiplexed streams of data betwe
 
 ##  Why Choose wolfSSH?
 
-The wolfSSH library is a lightweight SSHv2 server library written in ANSI C and targeted for embedded, RTOS, and resource-constrained environments - primarily because of its small size, speed, and feature set. It is commonly used in standard operating environments as well because of its royalty-free pricing and excellent cross platform support. wolfSSH supports the industry standard SSH v2 and offers progressive ciphers such as Poly1305, ChaCha20, NTRU, and SHA-3. wolfSSH is powered by the wolfCrypt library. A version of the wolfCrypt cryptography library has been FIPS 140-2 validated (Certificate #2425). For additional information, visit the wolfCrypt FIPS FAQ or contact fips@wolfssl.com
+The wolfSSH library is a lightweight SSHv2 server library written in ANSI C and targeted for embedded, RTOS, and resource-constrained environments - primarily because of its small size, speed, and feature set. It is commonly used in standard operating environments as well because of its royalty-free pricing and excellent cross platform support. wolfSSH supports the industry standard SSH v2. wolfSSH is powered by the wolfCrypt library. A version of the wolfCrypt cryptography library has been FIPS 140-2 validated (Certificate #3389), and is a module in process for FIPS 140-3. For additional information, visit the wolfCrypt FIPS FAQ or contact fips@wolfssl.com.
 
 ### Features
 
 
-- SSH v2.0 (server)
+- SSH v2.0 (server and client)
 
 - Minimum footprint size of 33kB
 
 - Runtime memory usage between 1.4 and 2kB, not including a configurable receive buffer
 
-- Multiple Hashing Functions: SHA-1, SHA-2 (SHA-256, SHA-384, SHA-512), BLAKE2b, Poly
+- Multiple hashing functions: SHA-1, SHA-2 (SHA-256, SHA-384, SHA-512)
 
-- Block, Stream, and Authenticated Ciphers: AES (CBC, CTR, GCM, CCM), Camellia, ChaCha
+- Block and authenticated ciphers: AES-CBC, AES-CTR, AES-GCM
 
-- Public Key Options: RSA, DH, EDH, NTRU
+- Key exchange options: DHE and ECDHE (with curves NISTP256, NISTP384, NISTP521)
 
-- ECC Support (ECDH and ECDSA with curves: NISTP256, NISTP384, NISTP
+- Public key authentication options: RSA and ECDSA (with curves NISTP256, NISTP384, NISTP521)
 
-- Curve25519 and Ed
-
-- Client authentication support (RSA key, password)
+- User authentication support (password and public key authentication)
 
 - Simple API
 
-- PEM and DER certificate support
-
-- Hardware Cryptography Support: Intel AES-NI support, Intel AVX1/2, RDRAND
+- PEM and DER X.509 certificate support
 
-- RDSEED, Cavium NITROX support, STM32F2/F4 hardware crypto support
+- Hardware Cryptography Support: Intel AES-NI support, Intel AVX1/2, RDRAND, RDSEED, Cavium NITROX support, STM32F2/F4 hardware crypto support, Freescale CAU / mmCAU / SEC, Microchip PIC32MZ
 
-- Freescale CAU / mmCAU / SEC, Microchip PIC32MZ
+- Post quantum hybrid key exchange with Hybrid ECDH-P256 Kyber-Level1
 
+- Support for SFTP, SCP, SSH-AGENT, local and remote port forwarding
diff --git a/wolfSSH/src/chapter02.md b/wolfSSH/src/chapter02.md
@@ -2,35 +2,40 @@
 
 wolfSSH is written with portability in mind and should generally be easy to build on most systems. If you have difficulty building, please don’t hesitate to seek support through our support forums, https://www.wolfssl.com/forums, or contact us directly at support@wolfssl.com.
 
-This section explains how to build wolfSSH on *nix-like and Windows environments, and provides guidance for building in a non-standard environment. You will find a getting started guide and example in section 3.
+This section explains how to build wolfSSH on Linux, un\*x-like (BSD, macOS) and Windows environments, and provides guidance for building in a non-standard environment. You will find a getting started guide and example in section 3.
 
-When using the autoconf/automake system to build, wolfSSH uses a single Makefile to build all parts and examples of the library, which is both simpler and faster than using Makefiles recursively.
+When using the autotools system to build, wolfSSH uses a single Makefile to build all parts and examples of the library, which is both simpler and faster than using Makefiles recursively.
 
 ##  Getting the Source Code
 
-The most recent, up to date version can be downloaded from the GitHub website here: https://github.com/wolfSSL/wolfSSH
+The most recent, up to date version can be downloaded from the GitHub website here: [https://github.com/wolfSSL/wolfssh](https://github.com/wolfSSL/wolfssh).
 
 Either click the “Download ZIP” button or use the following command in your terminal:
 ```
 $ git clone https://github.com/wolfSSL/wolfssh.git
 ```
 ##  wolfSSH Dependencies
 
-Since wolfSSH is dependent on wolfCrypt, a configuration of wolfSSL is necessary. wolfSSL can be downloaded here: https://github.com/wolfSSL/wolfssl. The simplest configuration of wolfSSL required for wolfSSH is the default build that can be built from the root directory of wolfSSL with the following commands:
+Since wolfSSH is dependent on wolfCrypt, a configuration of wolfSSL is necessary. wolfSSL can be downloaded here: [https://github.com/wolfSSL/wolfssl](https://github.com/wolfSSL/wolfssl). The simplest configuration of wolfSSL required for wolfSSH is the default build that can be built from the root directory of wolfSSL with the following commands:
 
 ```
 $ ./autogen.sh (only if you cloned from GitHub)
-$ ./configure --enable-ssh
+$ ./configure --enable-wolfssh
 $ make check
 $ sudo make install
 ```
-To use the key generation function in wolfSSH, wolfSSL will need to be configured with keygen:` --enable-keygen`.
-
-If the bulk of wolfSSL code isn't desired, wolfSSL can be configured with the crypto only option: `--enable-cryptonly`.
+To use the key generation function in wolfSSH, wolfSSL will need to be configured with keygen:
+```
+--enable-keygen
+```
+If the bulk of wolfSSL code isn't desired, wolfSSL can be configured with the crypto only option:
+```
+--enable-cryptonly
+```
 
-##   Building on *nix
+##   Building with autotools
 
-When building on Linux, *BSD, OS X, Solaris, or other *nix-like environments, use the autoconf system. To build wolfSSH run the following commands:
+When building on Linux, BSD, macOS, Solaris, or other un\*x-like environments, use the autotools system. To build wolfSSH run the following commands:
 ```
 $ ./autogen.sh (only if you cloned from GitHub)
 $ ./configure
@@ -68,7 +73,7 @@ $ make src/libwolfssh.la
 ```
 ##  Building on Windows
 
-The visual studio project file can be found at: https://github.com/wolfSSL/wolfssh/blob/master/ide/winvs/wolfssh.sln
+The Visual Studio project file can be found in the directory *ide\\winvs*.
 
 The solution file, 'wolfssh.sln', facilitates building wolfSSH and its example and test programs. The solution provides both Debug and Release builds of Static and Dynamic 32- or 64-bit libraries. The file user_settings.h should be used in the wolfSSL build to configure it.
 
diff --git a/wolfSSH/src/chapter03.md b/wolfSSH/src/chapter03.md
@@ -29,18 +29,18 @@ $ chmod 0600 ./keys/gretel-key-rsa.pem ./keys/hansel-key-rsa.pem \
 
 Authentication against the example echoserver can be done with a password or public key. To use a password the command line:
 ```
-$ ssh_client -p 22222 USER@localhost
+$ ssh -p 22222 USER@localhost
 ```
 
-Where the USER and password pairs are:
+Where the _USER_ and password pairs are:
 ```
 jill:upthehill
 jack:fetchapail
 ```
 
 To use public key authentication use the command line:
 ```
-$ ssh_client -i ./keys/USER-key-TYPE.pem -p 22222 USER@localhost
+$ 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.
@@ -58,7 +58,7 @@ The echoserver is the workhorse of wolfSSH. It originally only allowed one to au
 
 The option `-f` enables echo-only mode. From another terminal run:
 ```
-    $ ssh_client jill@localhost -p 22222
+    $ ssh jill@localhost -p 22222
 ```
 
 When prompted for a password, enter "upthehill". The server will send a canned
@@ -148,7 +148,7 @@ The scpclient tool accepts the following command line options:
     -S <from>:<to> copy from server to local
 ```
 
-# wolfSSH sftpclient
+### wolfSSH sftpclient
 
 The sftpclient, wolfsftp, establishes a connection to an SSH server and
 allows directory navigation, getting and putting files, making and removing
@@ -218,6 +218,55 @@ 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>
 
+## SFTP
+
+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.
+
+The SFTP client created is located in the directory examples/sftpclient/ and the
+server is ran using the same echoserver as with wolfSSH.
+
+```
+    src/wolfssh$ ./examples/sftpclient/wolfsftp
+```
+
+A full list of supported commands can be seen with typeing "help" after a
+connection.
+
+```
+    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
+```
+An example of connecting to another system would be
+
+```
+    src/wolfssh$ ./examples/sftpclient/wolfsftp -p 22 -u user -h 192.168.1.111
+```
+
 ##  Shell Support
 
 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.
@@ -232,3 +281,110 @@ By default, the echoserver will try to start a shell. To use the echo testing be
 ```
 $ ./examples/echoserver/echoserver -f
 ```
+
+## Post-Quantum
+
+wolfSSH now supports the post-quantum algorithm Kyber. It uses the NIST
+submission's Level 1 parameter set implemented by liboqs via an integration
+with wolfSSH. It is hybridized with ECDHE over the P-256 ECC curve.
+
+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
+```
+
+
+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:
+
+```
+    $ ./configure --with-liboqs
+```
+
+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.
+
+```
+    $ ./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
+    $ ./ssh -o"KexAlgorithms +ecdh-nistp256-kyber-512-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 echoed
+back. Use CTRL-C to terminate the connection.
+
+
+## Certificate Support
+
+wolfSSH can accept X.509 certificates in place of just public keys when
+authenticating a user.
+
+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`.
+
+```
+    $ ./examples/echoserver/echoserver -a ./keys/ca-cert-ecc.pem
+```
+
+The echoserver and client have a fake user named "john" whose certificate
+will be used for authentication.
+
+An example echoserver/client connection using the example certificate
+john-cert.der would be:
+
+```
+    $ ./examples/echoserver/echoserver -a ./keys/ca-cert-ecc.pem -K john:./keys/john-cert.der
+
+    $ ./examples/client/client -u john -J ./keys/john-cert.der -i ./keys/john-key.der
+```
diff --git a/wolfSSH/src/chapter10.md b/wolfSSH/src/chapter10.md
@@ -2,7 +2,7 @@
 
 ##  Open Source
 
-wolfSSL (formerly CyaSSL), yaSSL, wolfCrypt, yaSSH and TaoCrypt software are free software downloads and may be modified to the needs of the user as long as the user adheres to version two of the GPL License. The GPLv2 license can be found on the gnu.org website (http://www.gnu.org/licenses/old-licenses/gpl-2.0.html).
+wolfSSL, yaSSL, wolfCrypt, yaSSH and TaoCrypt software are free software downloads and may be modified to the needs of the user as long as the user adheres to version two of the GPL License. The GPLv2 license can be found on the gnu.org website: [http://www.gnu.org/licenses/old-licenses/gpl-2.0.html](http://www.gnu.org/licenses/old-licenses/gpl-2.0.html).
 
 wolfSSH software is a free software download and may be modified to the needs of the user as long as the user adheres to version three of the GPL license. The GPLv3 license can be found on the gnu.org website (https://www.gnu.org/licenses/gpl.html).
 
diff --git a/wolfSSH/src/chapter11.md b/wolfSSH/src/chapter11.md
@@ -2,10 +2,10 @@
 
 ##  How to Get Support
 
-For general product support, wolfSSL (formerly CyaSSL) maintains an online forum for the wolfSSL product family. Please post to the forums or contact wolfSSL directly with any questions.
+For general product support, wolfSSL maintains an online forum for the wolfSSL product family. Please post to the forums or contact wolfSSL directly with any questions.
 
-**wolfSSL (yaSSL) Forums:** https://www.wolfssl.com/forums
-**Email Support:** support@wolfssl.com
+- wolfSSL Forums: [https://www.wolfssl.com/forums](https://www.wolfssl.com/forums)
+- Email Support: support@wolfssl.com
 
 For information regarding wolfSSL products, questions regarding licensing, or general comments, please contact wolfSSL by emailing **info@wolfssl.com**.
 
diff --git a/wolfSSH/src/chapter12.md b/wolfSSH/src/chapter12.md
@@ -4,9 +4,9 @@
 
 We regularly post update information on Twitter. For additional release information, you can keep track of our projects on GitHub, follow us on Facebook, or follow our daily blog.
 
-wolfSSH on GitHub https://www.github.com/wolfssl/wolfssh
-wolfSSL on Twitter [http://twitter.com/wolfSSL](http://twitter.com/wolfSSL)
-wolfSSL on Facebook [http://www.facebook.com/wolfSSL](http://www.facebook.com/wolfSSL)
-wolfSSL on Reddit https://www.reddit.com/r/wolfssl/
-Daily Blog https://wolfssl.com/wolfSSL/Blog/Blog.html
+- wolfSSH on GitHub [https://www.github.com/wolfssl/wolfssh](https://www.github.com/wolfssl/wolfssh)
+- wolfSSL on Twitter [https://twitter.com/wolfSSL](https://twitter.com/wolfSSL)
+- wolfSSL on Facebook [https://www.facebook.com/wolfSSL](https://www.facebook.com/wolfSSL)
+- wolfSSL on Reddit [https://www.reddit.com/r/wolfssl/](https://www.reddit.com/r/wolfssl/)
+- Daily Blog [https://wolfssl.com/wolfSSL/Blog/Blog.html](https://wolfssl.com/wolfSSL/Blog/Blog.html)
 
