Common procedures
5 minute read
Use these procedures when building any NanoSSH client example code or integrated application.
Note
Steps differ between Commercial and Open Source models. Follow the steps for the model 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.
Commercial Model
To add TrustCore SDK code to an application’s development environment:
- If upgrading from an existing TrustCore SDK implementation, back up the existing
mssdirectories and files. In particular, ensure that the existingmss/src/common/moptions.hfile 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:
| 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-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.
Open Source Model
Note
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
Commercial Model
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
makefilewhen 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
mssdirectory and subdirectories. - Run the appropriate command to build the desired product executable.
- For client: ./scripts/nanossh/ssh_client/build_ssh_client_ncrypto.sh
- For Suite B editions of client, add the –suiteb option: ./scripts/nanossh/ssh_client/build_ssh_client_ncrypto.sh –suiteb
Open Source Model
NanoSSH Open Source Model 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.
| 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:
| 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. |
Was this page helpful?
Provide feedback