Skip to main content

NanoSSH client overview

NanoSSH Client is used to securely connect to remote servers, which may be running NanoSSH Server or any other SSH server.

Typical uses for NanoSSH client

  • SSH client shell: Provides a secured communication channel between two networked devices; typically used to log into a remote machine and execute commands. For the architectural implementation, see Figure 2. To build an example implementation, see Using NanoSSH Client for Shell (Remote) Access.

  • SSH client SFTP: Enables secure retrieval (GET) and writing (PUT) of files from/to a remote machine; for example, to retrieve an updated image file from a server and to write a log file to the server. For the architectural implementation, see Figure 4. To build an example implementation, see Using NanoSSH Client for Secure File Transfer.

  • SSH client port forwarding: Encrypts and decrypts TCP/IP traffic; often used so that proprietary applications operating on distributed machines may securely communicate. For the architectural implementation, see Figure 5. To build an example implementation, see Using NanoSSH Client for Port Forwarding.

This section provides information about the following topics:

  • Features (below)

  • RFC Support

  • Code Architecture

  • APIs

  • Building NanoSSH Client Example Code

Features

TrustCore SDK NanoSSH Client provides the following features:

  • Small memory footprint

  • Speeds integration and testing of complex cryptographic functions for your product

  • SSHv2 compliant

  • TCP/IP-neutral

  • Certificate support, per IETF draft 3, http://tools.ietf.org/html/draft-ietf-secsh-x509-03

  • Re-keying at will, based on a specified number of packets or a certain amount of time

  • Support for TPM-generated keys

  • OS- and platform-agnostic for easy portability

  • Threadless architecture, synchronous and asynchronous

  • Guaranteed GPL-free code that protects your intellectual property

RFC Support

NanoSSH supports the following RFC standards:

  • SSH File Transfer Protocol, v2, v3 and v4

  • RFC 4250: The Secure Shell (SSH) Protocol Assigned Numbers

  • RFC 4251: The Secure Shell (SSH) Protocol Architecture

  • RFC 4252: The Secure Shell (SSH) Authentication Protocol

  • RFC 4253: The Secure Shell (SSH) Transport Layer Protocol

  • RFC 4254: The Secure Shell (SSH) Connection Protocol (partially supported)

  • RFC 4344: The Secure Shell (SSH) Transport Layer Encryption Modes

  • RFC 4335: The Secure Shell (SSH) Session Channel Break Extension

  • RFC 4419: Diffie-Hellman Group Exchange for the Secure Shell (SSH) Transport Layer Protocol

  • RFC 4432: RSA Key Exchange for the Secure Shell (SSH) Transport Layer Protocol. For detailed information refer to section 7 of the RFC draft-ietf-secsh-filexfer-03.txt, SSH File Transfer Protocol (http://tools.ietf.org/html/draft-ietf-secsh-filexfer-03).

  • RFC 6187: X.509v3 Certificates for Secure Shell Authentication

  • RFC 6239: Suite B cryptographic suites for SSH

  • Draft-green-secsh-ecc-07: Elliptic-Curve Algorithm Integration in the Secure Shell Transport Layer

  • Draft-igoe-secsh-aes-gcm-02: AES Galois Counter Mode for the Secure Shell Transport Layer Protocol

  • Draft-josefsson-ssh-chacha20-poly1305-openssh-00 - ChaCha20 Poly1305 for the Secure Shell Transport Layer Protocol

  • Draft-ietf-curdle-ssh-ed25519-02 - Ed25519 for Secure Shell Transport Layer Protocol

Code architecture

The following diagram displays how NanoSSH Client code uses a layered code hierarchy.

Figure 1.
nanossh-client-guide-figures_nanossh-client-code-hierarchy.png

NanoSSH client code hierarchy


APIs

TrustCore SDK NanoSSH Client is implemented by the following ANSI C APIs:

  • Common code base: Functions common to all TrustCore SDK components; defined in src/common/mocana.h.

  • SSH client: Functions to implement synchronous communication between a NanoSSH Client and an SSH server; defined in src/ssh/client/sshc.h.

  • SSH SFTP client: Functions to implement NanoSSH SFTP Clients; defined in src/ssh/client/sshc.h.

Building NanoSSH client example code

To assist with the integration of a NanoSSH Client into devices, a suite of example code is included in the source distribution in the src/examples directory that corresponds to the following typical use cases, which are described in the NanoSSH Client Overview:

  • SSH client shell: Using the sshc_shell_example.c file, and follow the procedures in Building the Shell Access Example Code.

  • SFTP client: Using the sshc_example.c file, and follow the procedures in Building the SFTP Example Code.

  • SSH client port forwarding: Using the sshc_pf_example.c file, and follow the procedures in Building the Port Forwarding Example Code.

  • SSH client reverse port forwarding: Using the sshc_rpf_example.c file, and follow the procedures in Building the Reverse Port Forwarding Example Code.

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 a system (see Use Case Examples), the example code may be customized or used as a model for other implementations; see Customizing a NanoSSH Client Implementation.

Sample code has also been provided to quickly build a NanoSSH Client to demonstrate its features using example nanossh cmake project and build nanossh scripts.

Generate NanoSSH client quick build

Run the following command:

./scripts/nanossh/ssh_client/build_ssh_client_ncrypto.sh <arguments>

Options

  • <arguments>: Specifies which features to enable:

    • --debug: Enables debug logs.

    • --gdb: Enable debug symbols.

    • --suiteb: Enable NIST Suite B algorithms.

    • --cert: Enables certificate support in stack.

    • --server_cert_auth: Enables the server to use certificate for authenticating itself. Also enable cert=true if using this flag.

    • --cert_ocsp: Enables OCSP stapling when server is using certificate.

    • --ocsp_config_timeout: Enables OCSP timeout configuration.

    • --client_cert_auth: Enable the client to use a certificate to authenticate itself. Also enable cert=true if using this flag.

    • --client_auth: Enables the client to authenticate itself using the public key.

    • --fips: Build with FIPS enabled. Requires TrustCore SDK FIPS binary.

    • --hw-accel: Build with Hardware Accelerator.

    • --port-forwarding: Build with Port Forwarding enabled.

    • --remote-port-forwarding: Build with Remote Port Forwarding enabled.

    • --oqs: Build with Open Quantum Safe library.

    • --oqs-path: Path to directory containing Open Quantum Safe library.

Command examples

  • Without certificates

    ./scripts/nanossh/ssh_client/build_ssh_client_ncrypto.sh

  • With server certificate

    ./scripts/nanossh/ssh_client/build_ssh_client_ncrypto.sh --cert --server_cert_auth

  • With server certificate and OCSP stapling

    ./scripts/nanossh/ssh_client/build_ssh_client_ncrypto.sh --cert_ocsp

  • With server certificate and client certificate

    ./scripts/nanossh/ssh_client/build_ssh_client_ncrypto.sh --cert --server_cert_auth --client_cert_auth

  • With server certificate, client certificate, and OCSP stapling

    ./scripts/nanossh/ssh_client/build_ssh_client_ncrypto.sh --cert --server_cert_auth --client_cert_auth --cert_ocsp

  • With EC key support (Suite B)

    ./scripts/nanossh/ssh_client/build_ssh_client_ncrypto.sh --suiteb

Run NanoSSH client quick build

Run the following command:

./bin/ssh_client <options>

Options

  • ?: Displays the help.

  • -ip <ipaddr>: Sets the remote IP address.

  • -username <username>: Sets the username for the remote host.

  • -password <password>: Sets the password for the remote host.

  • -port <port>: Sets the port number for the remote host.

  • -ssh_ca_cert <ca_cert>: Sets the CA certificate path (used for authenticating cert provided by the server).

  • -ssh_client_cert <cert>: Sets the certificate path (used by client to authenticate itself).

  • -ssh_client_blob <key>: Sets the corresponding private key BLOB file path.

Note

When using a certificate and key, ensure the corresponding cipher algorithms are enabled.

Command examples

  • Without certificates

    ./ssh_client -port <port no> -ip <server IP address>

  • With server certificate

    ./ssh_client -port <port no> -ip <server IP address> -ssh_ca_cert <CAcert in .der/.pem format>

  • With server certificate and OCSP stapling

    ./ssh_client --port <port no> -ip <server IP address> -ssh_ca_cert <CAcert in .der/.pem format>

  • With server certificate and client certificate

    ./ssh_client -port <port no> -ip <server IP address> -ssh_client_cert <certificate in .der/.pem format> -ssh_client_blob <keyblob in .der/.pem/.dat format -ssh_ca_cert <CAcert in .der/.pem format>

  • With EC key support (Suite B)

    ./ssh_client_sb -port <port no> -ip <server IP address>
In this section: