Build NanoSSH server example code

NanoSSH server implementation tasks

The following are the basic tasks for building any of the NanoSSH server example code implementations.

Add the NanoSSH server software to the application development environment. Ensure to include the example code that most closely matches that of the intended application.
If there is no pre-configured TrustCore SDK port for the operating system, edit the appropriate abstraction files to port the code to the operating system.
Specify which features (such as debugging and examples) to be included in the TrustCore SDK executable by setting the appropriate compilation flags. Initially, define only the minimal set of flags to limit functionality to basic communications. After confirming that a basic example application is executable (see step 5), this step may be repeated to add more features one at a time.
Create the object files and the executable.
Verify that the NanoSSH server example code is executable on the operating system.
Repeat steps 3 to 5 as needed to add features one at a time.

Note

Steps differ between NanoSSH Standard Edition (commercial) and Community Edition (open-source). Follow the steps for the edition you are using.

Quick build server sample code

A sample version of a NanoSSH server may be quickly built to demonstrate its features using the provided makefile.ssh.

Example 1. Standard Edition

To generate the NanoSSH server quick build, run the following command:

./scripts/nanossh/ssh_server/build_ssh_server_ncrypto.sh <flags>

Table 1. Quick-build flags for NanoSSH server standard edition

Flag	Description
`--debug`	Enable debug logs.
`--gdb`	Enable debug symbols.
`--suiteb`	Enable NIST Suite B algorithms.
`--cert`	Enable certificate support in the stack.
`--server_cert_auth`	Server authenticates with a certificate (requires `--cert`).
`--cert_ocsp=true`	Enable OCSP stapling when the server uses a certificate.
`--ocsp_config_timeout`	Enable OCSP timeout configuration.
`--client_cert_auth`	Require clients to authenticate with a certificate (requires `--cert`).
`--client_auth`	Allow clients to authenticate with a public key.
`--oqs`	Build with the Open Quantum Safe (OQS) library.
`--oqs-path`	Path to the directory containing the OQS library.
`--hw-accel`	Enable hardware-acceleration support.
`--no-pubkey-name`	Support blobs without a public-key name (for older NanoSSH implementations).
`--port_forwarding`	Enable port-forwarding support.
`--fips`	Build with FIPS enabled (requires TrustCore SDK FIPS binary).

Example 2. Community Edition

Run the commands below from the root of the community edition repository:

# Configure and build all server-side samples
cmake -DBUILD_SAMPLES=ON <options> -B build -S .
cd build
make

Options

Table 2. TrustCore SDK NanoSSH CMake scenarios, flags, and commands

Scenario	CMake flags	Server command	Client command
Public‑key authentication	`-DBUILD_SAMPLES=ON`	`export LD_LIBRARY_PATH=lib/:crypto_lib/linux-x86_64/:$LD_LIBRARY_PATH` `./samples/bin/ssh_server -port 8818`	`export LD_LIBRARY_PATH=lib/:crypto_lib/linux-x86_64/:$LD_LIBRARY_PATH` `./samples/bin/ssh_client -ip 127.0.0.1 -port 8818 -username admin -password secure`
Disable SSH server library	`-DDISABLE_SSH_SERVER`	–	`export LD_LIBRARY_PATH=lib/:crypto_lib/linux-x86_64/:$LD_LIBRARY_PATH` `./samples/bin/ssh_client -ip 127.0.0.1 -port 8818 -username admin -password secure`
Disable SSH client library	`-DDISABLE_SSH_CLIENT`	`export LD_LIBRARY_PATH=lib/:crypto_lib/linux-x86_64/:$LD_LIBRARY_PATH` `./samples/bin/ssh_server -port 8818`	–
Server certificate authentication	`-DENABLE_SSH_SERVER_CERT_AUTH=ON`	`export LD_LIBRARY_PATH=lib/:crypto_lib/linux-x86_64/:$LD_LIBRARY_PATH` `./samples/bin/ssh_server -ssh_server_cert $SSH_SERVER_CERT -ssh_server_blob $SSH_SERVER_KEYBLOB`	`export LD_LIBRARY_PATH=lib/:crypto_lib/linux-x86_64/:$LD_LIBRARY_PATH` `./samples/bin/ssh_client -ssh_ca_cert $SSH_SERVER_CA_CERT`
Client certificate authentication	`-DENABLE_SSH_CLIENT_CERT_AUTH=ON`	`export LD_LIBRARY_PATH=lib/:crypto_lib/linux-x86_64/:$LD_LIBRARY_PATH` `./samples/bin/ssh_server -ssh_ca_cert $SSH_CLIENT_CA_CERT`	`export LD_LIBRARY_PATH=lib/:crypto_lib/linux-x86_64/:$LD_LIBRARY_PATH` `./samples/bin/ssh_client -ssh_client_cert $SSH_CLIENT_CERT -ssh_client_blob $SSH_CLIENT_KEYBLOB`
Mutual certificate authentication	`-DENABLE_SSH_SERVER_CERT_AUTH=ON -DENABLE_SSH_CLIENT_CERT_AUTH=ON`	`export LD_LIBRARY_PATH=lib/:crypto_lib/linux-x86_64/:$LD_LIBRARY_PATH` `./samples/bin/ssh_server -ssh_server_cert $SSH_SERVER_CERT -ssh_server_blob $SSH_SERVER_KEYBLOB -ssh_ca_cert $SSH_CLIENT_CA_CERT`	`export LD_LIBRARY_PATH=lib/:crypto_lib/linux-x86_64/:$LD_LIBRARY_PATH` `./samples/bins/ssh_client -ssh_client_cert $SSH_CLIENT_CERT -ssh_client_blob $SSH_CLIENT_KEYBLOB -ssh_ca_cert $SSH_SERVER_CA_CERT`
Shell example (client shell)	`-DENABLE_SSH_CLIENT_SHELL_EXAMPLE=ON`	`export LD_LIBRARY_PATH=lib/:crypto_lib/linux-x86_64/:$LD_LIBRARY_PATH` `./samples/bin/ssh_server -port 8818`	`export LD_LIBRARY_PATH=lib/:crypto_lib/linux-x86_64/:$LD_LIBRARY_PATH` `./samples/bin/ssh_client -ip 127.0.0.1 -port 8818 -username admin -password secure`
Asynchronous API example	`-DENABLE_SSH_ASYNC_API_SUPPORT=ON`	`export LD_LIBRARY_PATH=lib/:crypto_lib/linux-x86_64/:$LD_LIBRARY_PATH` `./samples/bin/ssh_server -port 8818`	`export LD_LIBRARY_PATH=lib/:crypto_lib/linux-x86_64/:$LD_LIBRARY_PATH` `./samples/bin/ssh_client -ip 127.0.0.1 -port 8818 -username admin -password secure`
Secure path restriction	`-DSECURE_PATH="/path/to/directory"`	–	–

Run NanoSSH server quick build

To run the NanoSSH server quick build, run the following command:

./bin/ssh_server <options>

Options

?: Displays the help.
-port <port>: Sets the listening port.
-ssh_server_cert <cert>: Sets the server certificate path.
-ssh_server_blob <key>: Sets the server blob path.
-ssh_ca_cert <ca_cert>: Sets the CA certificate.
-ocsp_responder_url <url>: Sets the OCSP Responder URL.
-ocsp_timeout <timeout>: Sets the OCSP wait timeout (in milliseconds).

Example code

To help with integration of NanoSSH server into devices, a suite of example code is included in the source distribution (in the src/examples directory).

The example code should be used “as-is” to validate SSH client-server communication. After verifying that the TrustCore SDK code works as expected on the intended system, the example code may be customized or used as a model for other implementations:

Customizing an Asynchronous NanoSSH server Implementation
Customizing a Synchronous NanoSSH server Implementation
Customizing a NanoSSH SFTP server Implementation

The following table shows which example files correspond to which NanoSSH product, as well as which flags to define to fully enable the example file’s code.

Table 3. Example Files and Configuration

File	Flags(s)	Sync server	Asynch server	SFTP server
sftp_example.c	Configures NanoSSH callbacks for SSH File Transfer Protocol (FTP) communication.			x
sftp_example_filesys.c	Provides an example SFTP file system descriptor.			x
sftp_example_wince.c	SFTP server for Windows CE.			x
ssh_example.c	Simple, synchronous SSH server with shell login.	x
ssh_example_async1.c	Simple, asynchronous SSH server with shell login.		x
ssh_example_async.c	Asynchronous SSH server with optional port forwarding.		x
ssh_example_pf.c	Synchronous SSH server with port forwarding.	x
ssh_linux_pty.c	Based on ssh_pipe.c; this Linux example demonstrates one way to communicate to an upper layer CLI, where the upper layer is the Bash shell.	x	x
ssh_pipe.c	Synchronous SSH server implemented as a proxy using pipes.	x	x
ssh_sock.c	Communicate to an upper-layer CLI.	x	x

Verify Communication between the client Shell and the NanoSSH server

After building the NanoSSH code, verify that it is executable in the operating environment. Assuming that NanoSSH client and NanoSSH server (and the example code) have been enabled, the loopback interface may be used to confirm that the client and server are able to communicate within the operating environment.

To verify communication between the client shell and NanoSSH server:

If necessary, open a command shell on the NanoSSH server (e.g., Cygwin).
Change to the mss directory.
Start NanoSSH server (messages are displayed as processes and methods start up and run):
```
bin/sshs.exe
```
Open a second shell (the client), and enter the following command to request a connection for the admin user:
```
ssh admin@127.0.0.1
```
When prompted for the corresponding password, enter secure.
When prompted to enter a new password, type one (e.g., new).
When prompted to confirm the new password, enter it again. The client echoes “Password changed” and “Password successfully changed”.
In the client window, press any keys. If they are echoed to the client window (that is, if you can see what you’re typing), asynchronous client-server communication is successful.
Perform a graceful shutdown by entering the following command in the client window:
```
Bye!
```

The client and server session end, and both command shells are closed.

In this section: