Common procedures

Use these procedures when building any NanoSSH client example code or integrated application.

Note

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

Add TrustCore SDK code to your development environment

The first step to building TrustCore SDK code is to add it to the application’s development environment.

Example 1. Standard Edition

To add TrustCore SDK code to an application’s development environment:

If upgrading from an existing TrustCore SDK implementation, back up the existing mss directories and files. In particular, ensure that the existing mss/src/common/moptions.h file can be easily retrieved.
If the distribution package ZIP file has a .zzz extension, rename it to .zip.
Extract ZIP archive to any directory. Make sure to retain the original directory structure.
```
unzip trustcore-sdk-<version>.zip -d "$SDK_HOME"
```

Review the resulting directory tree. The following table lists a typical directory structure that is created under the mss installation directory:

Table 1. Directory Structure and Purposes

Directory	Purpose
/bin	Executable output from cmake project builds
/docs	Product and user’s guides
/make	Model makefiles
/obj	Default location for Makefile/compiler output
/src/asn1	ASN.1 (abstract syntax notation one) X509v3 certificate parser
/src/common	Code used by multiple TrustCore SDK components; for example, math, logging, error codes, and debugging
/src/crypto	Cryptography-related TrustCore SDK code, including authentication, asymmetric, symmetric, and HMAC code
/src/crypto/mocasymkeys/mbed	Asymmetric functions for interfacing with mbedTLS library. Requires Export edition
/src/crypto/mocasymkeys/oqs	Asymmetric functions for interfacing with Open Quantum Safe library
/src/crypto/mocasymkeys/tap	Asymmetric functions TAP code
/src/crypto_interface	Cryptography-related abstraction layer for authentication, asymmetric, symmetric, and HMAC code
/src/examples	TrustCore SDK sample code
/src/harness	Hardware acceleration harness code
/src/platform	Porting abstraction layer
/src/<product-name>	Product-specific source code; a separate directory for each Nano- solution or TrustCore SDK product
/projects/asn1	CMake project for building asn1 source files
/projects/common	CMake project for building common source files
/project/crypto	CMake project for building cryptography source code. This directory includes nanocap_oqs, nanocap_mbed, cryptointerface, and nanocrypto
/projects/initialize	CMake project for building initialization source files
/project/nanocap	CMake project for building CPA source files
/projects/nanocert	CMake project for building x509 certificate management source files
/projects/nanossh	CMake project for building NanoSSH client
/projects/nanotap2	CMake project for building TAP source files
/projects/nanotap2_common	CMake project for building TAP common source files
/projects/nanotap2_configparser	CMake project for building TAP configuration source files
/projects/smp_tpm2	CMake project for building TPM 2.0 SMP source files
/projects/tpm2	CMake projects for building TPM 2.0 interface source files

Become familiarized with the code by looking through the directory structure, examining the makefiles, and scanning the source code.

Example 2. Community Edition

Notice

Make sure you have Git installed and network access to the TrustCore SDK public repository.

Choose or create a working directory and set an environment variable for it, for example:
```
export SDK_HOME="$HOME/digicert"
```

Clone the TrustCore SDK Community Edition repository:

git clone https://github.com/digicert/trustcore "$SDK_HOME/trustcore"

Go to the cloned directory:
```
cd $SDK_HOME/trustcore
```
(Optional) Check out a specific release tag or branch:
```
git checkout <tag-or-branch>
```
Verify that the cloned directory contains the same high‑level folders listed in the Standard Edition layout (bin/, docs/, src/, projects/, etc.).
```
ls -1d */ | sort
```

Build NanoSSH client executable

Example 3. Standard Edition

Important

If using an IDE instead of command line makefiles, do not use the following procedure. Instead, use the IDE’s build mechanism:

Open the project folder in your IDE and enable or install the makefile when prompted.
Let the IDE import the build files and generate its internal project model.
Review and adjust compiler paths, include directories, and build targets as needed.

To build a NanoSSH client executable:

Change to the directory into which the TrustCore SDK code was extracted. The directory should contain the mss directory and subdirectories.
Run the appropriate command to build the desired product executable.
1. For NanoSSH client:
```
./scripts/nanossh/ssh_client/build_ssh_client_ncrypto.sh
```
2. For Suite B editions of NanoSSH client, add the --suiteb option:
```
./scripts/nanossh/ssh_client/build_ssh_client_ncrypto.sh --suiteb
```

Example 4. Community Edition

NanoSSH Community Edition uses first‑party CMake projects and exposes build‑time options through -D flags. Each example below assumes that your working directory is the root of the NanoSSH Community Edition source tree.

Example build commands

cmake -DBUILD_SAMPLES=ON -B build -S .
pushd build
make
popd

Running the above commands builds SSH SFTP client and SSH server examples using server public key authentication. Sample binaries are located in build/samples/bin/.

Build options

Refer to the table below for additional build flags (such as adding server certificate authentication) and client/server configuration commands, for example LD_LIBRARY_PATH to resolve runtime dependencies.

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"`	–	–

Initialize TrustCore SDK code

Applications should perform the common TrustCore SDK initialization and shutdown work, as shown in the src/examples/mocana_example.c sample module.

In particular, make the following function calls and perform the following procedures:

Table 3. TrustCore SDK function call procedures and purposes

Phase	Function	Purpose
Startup	`MOCANA_initMocana()`	Initialize common runtime (logging, RNG, memory pools).
	`MOCANA_initLog(cb)`	(Optional) Register a logging callback.
	—	Start component server threads (for example, NanoSec IKE).
	—	Implement a status-checking loop that runs and sleeps as long as an application running flag is true.
Shutdown	`MOCANA_freeMocana()`	Release all resources allocated during startup.

In this section: