NetBurner 3.5.0
PDF Version
 
SSH Programming Guide

SSH Overview

The Secure Shell Protocol (SSH) is a secure network protocol that has been around since 1995. It was designed to facilitate operating network services over an encrypted connection, and is still widely used today.

SSH has been a part of NetBurner's offerings for quite awhile now, starting with NNDK version 2.0. Up until recently, we utilized Dropbear to provide the SSH capability to our library. As of NNDK 3.3.6, however, we have migrated to wolfSSH. This change provides our library with several benefits. First, it provides better security with an updated list of ciphers compared to the version of Dropbear we were utilizing previously. It also allowed us to provide additional features, such as the capability to support running an SSH client on our devices, where we had been unable to do so before. Finally, because it shares the same underlying library with our SSL/TLS library, wolfCrypt, we were able to reduce the amount of code required to run both libraries simultaneously.

Supported Key Types, Sizes, and Formats

The SSH library currently supports both ECC and RSA keys, though we recommend ECC. The default key size for RSA is 2024, but support for a 4096 key can be enabled by defining ENABLE_RSA_4K in <nndk_install>\nbrtos\include\predef.h. ECC key sizes can range from 160 to 512.

Both ECC and RSA keys can be presented in either PEM or ASN1 formats.

Migrating from NNDK 3.3.5 and earlier to 3.3.6 or later

We've made every effort to make sure that the updates to the SSH library would be backward compatible. However, in some cases change was unavoidable, and in others, developers would be better served to update their applications to use newer versions of existing functions.

When building applications that use the SSH libraries in NBEclipse, the following include paths need to be added to projects:

${NNDK_ROOT}/libraries/include/ssh
${NNDK_ROOT}/libraries/include/crypto

To do this, first right click on your project in NBEclipse, and select the properties option at the bottom of the menu. The following window will be displayed.

From the left side menu, select "C/C++ Build" (1) followed by "Settings" (2). In the main window, you'll want to select the "Includes" (3) folder under both the "GNU C Compiler" and "GNU C++ Compiler". Once here, hit the icon with the green plus on it (4), and then add the paths so that they are listed above (5). Finally, hit "Apply", and then clean the project. It should find the required files during the build and complete successfully.

Removed and Updated Functions

The following functions have been removed from our API. They were specific to the Dropbear library and no longer make sense to have in our current API.

  • SshConvertDecodedOpenSSLKey This function converted a PEM formatted SSL key to the Dropbear format. The new API supports both PEM and ASN1 formatted keys, and we no longer support the Dropbear format.
  • SshSetchansessionrequest This function set a user callback routine for handling server side channel requests. These requests are handled internally by wolfSSH.
  • SshSetTaskPriority This function set the task priority for the SSH session. Where each SSH session had its own task previously, both SSH and SSL/TLS sessions are now managed by the CryptoServer object. This object runs a task of priority SECURITY_TASK_PRIO, which is defined in <nndk_install>\nbrtos\include\constants.h.

The following functions and function pointers have updated versions that we encourage developers to take advantage of.

  • sshUserAuthenticateFn An updated version of this function pointer, sshUserAuthenticateWithTypeFn, has been added to the API. Instead of just taking a pointer to the username and password as its parameters, it now additionally takes a parameter of AuthType that specifies if the authentication value passed in is a password or a key.
  • SshSetUserAuthenticate This function should be replaced with SshSetUserAuthenticateWithType(), and takes as it's parameter a function pointer of type sshUserAuthenticateWithTypeFn.
  • SshGetUserAuthenticate This function should be replaced with SshGetUserAuthenticateWithType(), and returns a function pointer of type sshUserAuthenticateWithTypeFn, if it has been set with a call to SshSetUserAuthenticateWithType().

Onboard Generated Keys

As is the case with our updated SSL/TLS library, SSH can now take advantage of onboard generated keys. This means that SSH keys can be automatically generated on the device if required. The mechanism for this is exactly the same, and in fact, the SSH key is the same key that is generated as part of generating an SSL/TLS certificate. To understand how to use the functionality, we encourage developers to look at the appropriate examples, found in <nndk_install>\examples\SSL\SslOnboardCertGeneration.

Auto-regeneration of this key can be enabled by defining ENABLE_AUTOCERT_REGEN, found in <nndk_install>\nbrtos\include\predef.h.

Order of Key Use

There are several methods in which a key could be installed on the device. In order of consideration during runtime, these are:

  • Set a function callback with SshSetUserGetKey() that will return the server key via the passed in parameters.
  • Using a compiled in key, and overriding the weak function GetPrivateKeyPEM().
  • Using an onboard generated key.

User Authorization

To assist with storing and managing user authentication data, we've provided a simple class, UserAuthManager. This class provided the methods required to store, retrieve, and compare user credentials for authentication and authorization purposes. Two callbacks signatures are provided, LoadAuthRecordsFn and SaveAuthRecordsFn, that can be used to load and save user authorization into the UserAuthManager object. This allows the developer to use any type of storage device or location to save the data.

Passwords and keys are hashed when added to the manager, so there is no possibility for leaking plain text data that could potentially compromise the security of the system. Our provided example, sshServerUserAuth, demonstrates this using the devices User Param space to save the data as a JSON blob.