Customize a NanoSSH client implementation

Every NanoSSH Client must include at least one enabled authentication method. See the following sections:

This section describes the features that may be added to the NanoSSH Client. For each feature’s section, there is a description of the feature, background information to help with the decision of how to use the feature, and information about which flags, callback functions, and API methods are needed to implement the feature.

The quickest path to an up-and-running NanoSSH application is to first turn on basic NanoSSH example code, build it, and then verify communications. Then the example code may be customized or integrated application by adding features one at a time (by defining the appropriate flags). That is, do not define many unrelated flags at once, but use a staged approach:

The steps below describe the tasks required to implement a TrustCore SDK NanoSSH Client shell.

DigiCert TrustCore SDK code includes extensive debugging messages to help with integration efforts. DigiCert may also ask for debugging to be enabled if support is contacted with any technical questions.

The debug log messages may be sent to stdout, a telnet console, or a customized platform-specific interface.

Applicability

Debugging may be enabled for any NanoSSH Client example code or customized implementation.

Flags

To enable debug messages, define the appropriate flags in Table 8 below (depending on where to send the debug output) and rebuild the executable(s). Table 8: Debug Flags

Callback Functions

No callback functions necessary to use the TrustCore SDK debug messages.

API Methods

No API calls required to receive TrustCore SDK debug messages on stdout or a telnet port; simply define the appropriate debug flags, rebuild the executable, and run it. If the TrustCore SDK memory leak debugger has been enabled by defining the __ENABLE_MOCANA_DEBUG_MEMORY__ flag, the application code should call dbg_dump() whenever a dump of the accumulated memory debug messages (calls to malloc and free) needs to be viewed.

NanoSSH Client supports public key and password authentication, so which should be used? Although public keys and passwords are both transmitted over a secure channel, it is better to use public keys to eliminate the problems inherent in password-based systems (that is, systems that rely on user names and passwords for access authorization) for the following reasons:

Applicability

Public key or password authentication may be enabled for any NanoSSH Client implementation.

Flags

No flags are required to choose between public key and password authentication.

Callback Functions

To select the desired authentication method (public key or password), customize the sshClientSettings->funcPtrRetrieveUserAuthRequestInfo callback function in the code. For the client application to query the server for supported algorithms (by sending Signature = FALSE), define sshClientSettings->funcPtrRetrieveUserAuthRequestInfoEx handler instead to allow the application to control the authentication request by explicitly setting SendSignature to TRUE or FALSE. The funcPtrRetrieveUserAuthRequestInfoEx overrides the funcPtrRetrieveUserAuthRequestInfo callback. These callback(s) function is invoked when an SSH server (NanoSSH or any other SSH server) requests that the NanoSSH Client authenticate itself. Callback registration happens at session creation and initialization by assigning a custom callback function, which may have any name, to this callback pointer.

The following example shows a typical implementation.

static int
SSHC_EXAMPLE_userAuthRequestInfoUpcall(int connectionInstance,
                                       unsigned char **ppUserName,
                                       unsigned int *pUserNameLength,
                                       unsigned int *pMethod)
{
    /* MY credentials for logging on to a remote server */
    int status = 0;
    MOC_UNUSED(connectionInstance);

    /* return username, can use different usernames for each logon attempt */
    *ppUserName = (unsigned char*)sshc_exampleUserName;
    *pUserNameLength = (sizeof(sshc_exampleUserName) - 1);

    /* return authentication method type, possible to use different authentication method for each logon attempt */
    *pMethod = MOCANA_SSH_AUTH_PASSWORD; /* or MOCANA_SSH_AUTH_PUBLIC_KEY */

    return status;
}

main
{
    /* other initialization */
     SSHC_sshClientSettings()->funcPtrRetrieveUserAuthRequestInfo =           SSHC_EXAMPLE_userAuthRequestInfoUpcall;

    /* main functionality */

    SSHC_shutdown();
    return;
}

API Methods

No API methods are required to choose between public key and password authentication.

Using password authentication in a NanoSSH Client implementation is a simple process:

Applicability

Password authentication may be used for any NanoSSH Client implementation.

Flags

No flags are required to use password authentication.

Callback Functions

The sshClientSettings->funcPtrRetrieveUserPassword callback is invoked when an SSH server (NanoSSH or any other SSH server) requests authentication; it should return the user’s password and its length. Callback registration happens at session creation and initialization by assigning a custom callback function, which may have any name, to this callback pointer.

The following example shows a typical implementation.

static int
SSHC_EXAMPLE_userPasswordUpcall(int connectionInstance,
                                unsigned char *pUserName, unsigned int userNameLength,
                                unsigned char **ppUserPassword, unsigned int *pUserPasswordLength)
{
    /* MY credentials for logging on to a remote server */
    MOC_UNUSED(connectionInstance);
    MOC_UNUSED(pUserName);
    MOC_UNUSED(userNameLength);

    /* return password for simple username/password authentication */
    *ppUserPassword = (unsigned char*)sshc_examplePassword;
    *pUserPasswordLength = strlen(sshc_examplePassword);

    return 0;
}

main
{
    /* other initialization */
    SSHC_sshClientSettings()->funcPtrRetrieveUserPassword = SSHC_EXAMPLE_userPasswordUpcall;

    /* main functionality */

    SSHC_shutdown();
    return;
}

API Methods

No API methods are required to use password authentication.

To disable password authentication in a NanoSSH Client application, a different authentication method (public key or certificates) must be enabled:

Applicability

Password authentication is not required for any NanoSSH Client implementation.

Flags

No flag definitions are required to disable password authentication.

Callback Functions

To disable password authentication, the pMethod parameter of the sshClientSettings->funcPtrRetrieveUserAuthRequestInfo callback function must be set to anything other than MOCANA_SSH_AUTH_PASSWORD. When password authentication is disabled, it does not matter whether the sshClientSettings->funcPtrRetrieveUserPassword callback function is registered because it is not used.

API Methods

No API methods are required to disable password authentication.

Before enabling public key authentication, decide which key encryption methods are to be allowed. TrustCore SDK NanoSSH supports DSA, RSA, ECDSA, and EDDSA public keys, so which one should be used?

If the application must be FIPS certified or requires Suite B support, use ECDSA; otherwise, choose between RSA and DSA. RSA is significantly faster than DSA, typically by a factor of three. So if using the NanoSSH Client or another client known to support RSA, use it; otherwise, use DSA or ECDSA. If there are no external requirements, all the key encryption methods may be enabled for maximum interoperability.

Note: Per the SSH protocol definition, RSA support is optional; therefore, some clients require DSA to be used To add public key authentication:

Applicability

Public key authentication and any key encryption method may be used in any NanoSSH Client implementation.

Flags

To enable a key encryption method, define the appropriate compilation flags:

If more than one encryption method is enabled for NanoSSH Client and also offered by the SSH server (NanoSSH or any other SSH server), the first match in the internal NanoSSH Client structure, mHostKeySuites, is the one that is chosen.

Callback Functions

To add public key authentication, customize and register the following callback functions:

Callback registration happens at session creation and initialization by assigning a custom callback function, which may have any name, to this callback pointer.

The following examples show typical implementations for the required callbacks.

code listing (funcPtrServerPubKeyAuth)

static int
 SSHC_EXAMPLE_serverPubKeyAuthUpcall(int connectionInstance,
                                    const unsigned char *pPubKey, unsigned int pubKeyLength)
{
    ubyte*  pStoredHostPublicKey = NULL;
    ubyte4  storedHostPublicKeyLength;
    sbyte4  result = 0;
    MOC_UNUSED(connectionInstance);
    ubyte*  pSerializedKey = NULL;
    ubyte4  serializedKeyLength = 0;
    ubyte*  pEncodedKey = NULL;
    ubyte4  encodedKeyLength = 0;
    AsymmetricKey asymKey = { 0 };
    AsymmetricKey asymKey2 = { 0 };

    /* The SSH Client will only call this function, if the server's */
    /* public key matched the signature provided.  We need to now */
    /* verify that the public key is an acceptable public key (i.e. on record) */

    /* we would want to extract the server's IP address from connectionInstance */
    /* then use that to look up the appropriate host key stored file */

    /* make sure the server provided

 pubkey matches a public key on file */
    if (0 == MOCANA_readFile(AUTH_KEYFILE_NAME, &pStoredHostPublicKey, &storedHostPublicKeyLength))
    {
        if (OK > SSHC_parseServerAuthKeyFile(pStoredHostPublicKey,
            storedHostPublicKeyLength, &asymKey))
            goto exit;
    }
    else
    {

    /* if necessary, do additional checks here */

    /* finally, if we do not recognize this IP address we should store the ip address in a file */
    /* a simple scheme filename convention: /keys/host/sshc/ip_<ip.ad.dr.ess>.pubkey */

    result = 1; /* we made it to the end! */

exit:
    if (NULL != pStoredHostPublicKey)
        MOCANA_freeReadFile(&pStoredHostPublicKey);

    return result;
}

main
{
    /* other initialization */
     SSHC_sshClientSettings()->funcPtrServerPubKeyAuth =           SSHC_EXAMPLE_serverPubKeyAuthUpcall;

    /* main functionality */

    SSHC_shutdown();
    return;
}

code listing (funcPtrRetrieveNakedAuthKeys)

static int
 SSHC_EXAMPLE_retrieveAuthKeys(int connectionInstance,
                              unsigned char **ppRetKeyBlob, unsigned int *pRetKeyBlobLength)
{
    int     status;
    MOC_UNUSED(connectionInstance);

    *ppRetKeyBlob = NULL;
    *pRetKeyBlobLength = 0;

    if (0 > (status = MOCANA_readFile(KEYBLOB_AUTH_KEY_FILE_NAME, ppRetKeyBlob, pRetKeyBlobLength)))
        status = ERR_SSH_MISSING_KEY_FILE;

    return status;

} /* SSHC_EXAMPLE_retrieveAuthKeys */

main
{
    /* other initialization */
     SSHC_sshClientSettings()->funcPtrRetrieveNakedAuthKeys =           SSHC_EXAMPLE_retrieveAuthKeys;

    /* main functionality */

    SSHC_shutdown();
    return;
}

code listing (funcPtrReleaseNakedAuthKeys)

static sbyte4
 SSHC_EXAMPLE_releaseAuthKeys(sbyte4 connectionInstance, ubyte **ppFreeKeyBlob)
{
    MOC_UNUSED(connectionInstance);

    MOCANA_freeReadFile(ppFreeKeyBlob);

    return 0;
}

main
{
    /* other initialization */
     SSHC_sshClientSettings()->funcPtrReleaseNakedAuthKeys =           SSHC_EXAMPLE_releaseAuthKeys;

    /* main functionality */

    SSHC_shutdown();
    return;
}

API Methods

No API methods are required to use public key authentication.

Growing numbers of systems are forsaking transmission of public keys and passwords for authentication and are choosing to use certificates instead. Although the certificates themselves contain the same public keys that could be sent directly, using certificates is more secure because:

To use certificates:

Applicability

Any implementation may use certificates in place of public keys or passwords for authentication.

Flags

To enable certificate support for NanoSSH Client, define the following flags:

In addition, RSA, DSA, or ECC may be enabled as required using the following flags:

Also ensure that the following flags are not defined:

Callback Functions

To use certificates, customize and register the following callback functions:

Optionally, the following callback function may also be customized and registered:

For detailed information about these callback functions and their parameters, refer to the TrustCore SDK NanoSSH API Reference.

API Methods

No API methods are required to use certificates.

The “none” authentication method may be configured, although it is strongly discouraged because it lets anyone successfully log in without authentication, thereby circumventing normal security strategies; however, there might be times when using no authentication may be useful, such as in a testing environment during the build process.

To configure the “none” authentication method:

Testing the “none” Authentication

One method of testing the “none” authentication method is to configure an SSH server (NanoSSH or any other SSH server) for “none,” build the NanoSSH Client example code (first defining the necessary flags functions, and callbacks, as described above), and then connect the SSH server and client for communications.

Applicability

Any implementation may use the “none” authentication method.

Flags

To enable the “none” authentication method for NanoSSH Client, define the following flags:

Callback Functions

No callback functions are required to use the “none” authentication method.

API Methods

No API methods are required to use the “none” authentication method.

To use the NanoSSH Client, no configuration is required except as explained in the applicable use case example description (see Use Case Examples). Likewise, see the applicable feature section in this section, Customizing a NanoSSH Client Implementation for detailed configuration instructions, including how to define flags and customizing and registering callback functions.

If desired, the NanoSSH Client may be further configured by defining optional flags (see Flags), customizing any of the NanoSSH Client callback functions (see Callback Functions), and assigning custom values to the NanoSSH sshClientSettings fields (see Table 9 below).

Table 9: Configurable sshClientSettings Fields

Flags

The following list of flags in alphabetical order, that may be defined to configure a NanoSSH Client. For detailed flag definition requirements, be sure to see the applicable feature section in this section.

Applicability

When configuring NanoSSH Client by assigning custom values to the sshClientSettings fields, defining flags, and customizing callback functions, it is important to understand which configuration items correspond to the application’s intended use cases and features. For example, if the __ENABLE_MOCANA_GCM__ flag is defined but do not need Suite B support, the code’s footprint has been created for no gain in functionality.

Callback Functions

As described in this section, the key approach to configuring a NanoSSH Client is to customize and register the appropriate callback functions.

API Methods

The NanoSSH Client API methods are used to implement desired functionality and features; there are no methods that are strictly for configuration.

Shell support is automatically included in any NanoSSH Client application. For information about building the NanoSSH Client shell example code, see Using NanoSSH Client for Shell (Remote) Access.

Applicability

The NanoSSH Client may be used any time secure communications are needed between two network devices, such as when logging into a remote machine to execute commands.

Flags

No flag definitions are required to enable shell support; however, flag definitions are required to enable the chosen authentication method. For detailed information, see the applicable sections in this section.

Callback Functions

No callback functions are required to enable NanoSSH Client shell support; however, callback functions need to be customized and registered for the chosen authentication method. For detailed information, see the applicable sections in this section.

API Methods

The following API methods are specific to NanoSSH Client shell support:

To enable NanoSSH Client SFTP operations, simply add a flag definition as described below. For information about building the NanoSSH Client sftp example code, see Using NanoSSH Client for Secure File Transfer.

Applicability

NanoSSH Client SFTP applications are appropriate anytime secure writing (PUT) and retrieval (GET) of files to/from a remote machine are needed, such as to retrieve an updated image file from a server and to write a log file to the server.

Flags

To enable NanoSSH Client SFTP operations, define the following flag:

Additionally, flag definitions are required to enable the chosen authentication method. For detailed information, see the applicable sections in this section.

Callback Functions

There are no callback functions that are specific to NanoSSH Client SFTP; however, callback functions need to be customized and registered for the chosen authentication method. For detailed information, see the applicable sections in this section.

API Methods

The following functions are used to implement NanoSSH FTP clients; for detailed function information, refer to the TrustCore SDK NanoSSH API Reference:

NanoSSH Client supports both single and multiple local port forwarding. This feature enables an application client to make a secure virtual connection, over any network or the Internet using TCP/IP, to application servers via the NanoSSH Client. For information about building the NanoSSH port forwarding example code, see Using NanoSSH Client for Port Forwarding.

Applicability

Port forwarding may be added to any NanoSSH Client implementation.

Flags

To enable NanoSSH Client port forwarding operations, define the following flag:

Additionally, flag definitions are required to enable the chosen authentication method. For detailed information, see the applicable sections in this section.

Callback Functions: Port Forwarding

To add port forwarding, customize and register the following callback functions:

In addition to the port forwarding-specific callbacks, callback functions need to be customized and registered for the chosen authentication method. For detailed information, see the applicable sections in this section.

API Methods

The following API methods are specific to NanoSSH Client port forwarding operations:

For information about the order in which to call NanoSSH Client methods to implement port forwarding, see Client Port Forwarding Integration Flowchart.

To add reverse port forwarding, customize and register the following reverse port forwarding callback functions:

Additionally, the standard port forwarding functions must be customized and registered; see Callback Functions: Port Forwarding.

API Methods

The following API methods are specific to NanoSSH Client reverse port forwarding operations:

NanoSSH Client may use the strongest cipher suite available or the desired cipher settings may be specified. The following factors should be considered:

For details about the supported ciphers and their pros and cons, see Table 10.

Applicability

Any cipher may be enabled for any NanoSSH Client implementation.

Flags

Table 10 lists the available ciphers and the TrustCore SDK compilation flag definition required to enable the cipher, along with the ciphers’ pros and cons.

This section describes how to configure support for X509 Certificates for server and client certificate-based authentication:

The OCSP_CLIENT_getCertStatus API may be used to verify the certificate revocation status. The __ENABLE_MOCANA_OCSP_CERT_VERIFY__ flag is required for the application to use the API:

#ifdef __ENABLE_MOCANA_OCSP_CERT_VERIFY__
MOC_EXTERN MSTATUS
OCSP_CLIENT_getCertStatus(ubyte *pCertificate, ubyte4 certLen, certChainPtr pCertChain,
const ubyte *pAnchorCert, ubyte4 anchorCertLen) ;
#endif /* __ENABLE_MOCANA_OCSP_CERT_VERIFY__ */

sbyte4(*funcPtrCertStatus) (sbyte4 connectionInstance, const ubyte *pUser, ubyte4 userLength,
sbyte4 cert_status, ubyte *pCertificate, ubyte4 certLen,
certChainPtr pCertChain, const ubyte *pAnchorCert, ubyte4 anchorCertLen);

With client certificate-based authentication, NanoSSH Server receives and validates the client certificates against the trust chain, and performs the time validity. Applications may define and register a post certificate validation callback with NanoSSH Server. The callback provides the application with verification status, along with the certificate(s) received for the application to perform extended validation on the certificate or override the status. The following example code provides a simple implementation that uses the callback to verify certificate status using OCSP.

static sbyte4 SSH_EXAMPLE_certstatus(sbyte4 connectionInstance, const ubyte *pUser,
 ubyte4 userLength, sbyte4 cert_status, ubyte *pCertificate,
 ubyte4 certLen, certChainPtr pCertChain,
 const ubyte *pAnchorCert, ubyte4 anchorCertLen)
{
    MSTATUS status = OK;
    DEBUG_PRINTNL(DEBUG_SSH_EXAMPLE, (sbyte *)"SSH_EXAMPLE_certstatus:");
    /* if no client cert validation is needed, return OK from here */
    if (cert_status != OK) {
        status = cert_status ;
        goto exit ;
    }
#if ((defined(__ENABLE_MOCANA_SSH_OCSP_SUPPORT__)) &&
       (defined(__ENABLE_MOCANA_OCSP_CLIENT__)) && \
       (defined(__ENABLE_MOCANA_OCSP_CERT_VERIFY__)))
    status = OCSP_CLIENT_getCertStatus(ocsp_ResponderUrl, pCertificate, certLen, pCertChain,
       pAnchorCert, anchorCertLen  ) ;
#endif
exit:
    return status ;
}
SSH_EXAMPLE_main()
{
SSH_sshSettings()->funcPtrCertStatus = SSH_EXAMPLE_certstatus ;
    …
}

NanoSSH supports draft-igoe-secsh-suiteb-00, Suite B Cryptographic Suites for Secure Shell. Suite B cryptography is a set of cryptographic algorithms and protocols, specified by NIST, that are approved by the NSA for protecting classified and unclassified National Security Systems (NSS).

The TrustCore SDK API functions that are related to NSA Suite B cryptography are available only if the Suite B edition of the TrustCore SDK product Platform has been purchased.

Applicability

Suite B cryptographic ciphers may be added to any NanoSSH Client example code or customized implementation.

Flags

To enable Suite B cipher support in NanoSSH Client, use the –suiteb argument when running the build script.

If using GCM, the __ENABLE_MOCANA_GCM__ flag must be defined. If none of the corresponding GCM message sizes are defined, the cryptographic code uses the default flag, __ENABLE_MOCANA_GCM_265B__. Optionally, any flag may be defined, but only one of the __ENABLE_MOCANA_GCM_*__ message size flags are used.

Callback Functions

No callback functions are required to enable Suite B support.

API Methods

No API methods are required to enable Suite B support.

For best security, it is important to periodically refresh the authentication keys. RFC 4253, The Secure Shell (SSH) Transport Layer Protocol, section 9, states that “It is RECOMMENDED that the keys be changed after each gigabyte of transmitted data or after each hour of connection time, whichever comes sooner; however, because the re-exchange is a public key operation, it requires a fair amount of processing power and should not be performed too often.”

Applicability

Rekeying is applicable to any NanoSSH Client implementation that uses public key authentication or certificates.

Flags

No flag definitions are required to enable rekeying.

Callback Functions

No callback functions are required to initiate rekeying.

API Methods

To initiate rekeying, call the following API method:

To rekey based on the amount of data transmitted, call SSHC_initiateReKey only when indicated by the results from the following API method:

The TrustCore SDK memory footprint may be reduced by defining compilation flags to disable products or features that are not in use, which removes the corresponding code from the resultant executable.

For example, if the only TrustCore SDK products being used are NanoSSH Client and NanoSSH Server, do not define the flags for NanoSSL (client and server) or NanoSec. Similarly, unneeded features may also be disabled, such as support for certificate parsing, key generation, or ciphers that the system does not recognize.

Applicability

Footprint reduction techniques may be applied for any NanoSSH Client example code or customized implementation.

Flags

Table 11 below lists a typical set of flags that when defined substantially reduce the NanoSSH Client memory footprint. These flags can be added to projects/nanossh/mocana_suiteb_flags.txt or projects/nanossh/ssh_client/mocana_flags.txt.

Table 11: Typical Footprint Reduction Flags

Callback Functions

No callback functions are required to reduce the NanoSSH Client footprint.

API Methods

No API methods are required to reduce the NanoSSH Client footprint.

LINK TO FIPS INFO

To integrate a NanoSSH application with a licensed TrustCore SDK NanoCrypto FIPS binary cryptographic module, a staged approach is recommended:

If the operating system is Linux, refer to the Using TrustCore SDK NanoCrypto FIPS Binaries for Linux guide for instructions.

A variety of NanoSSH Client statistics may be gathered:

Applicability

Statistics may be gathered in any NanoSSH Client application.

Flags

No flags are required to gather NanoSSH Client statistics.

Callback Functions

No callback functions are required to gather NanoSSH Client statistics.

API Methods

To gather the statistics described above, call the following API methods:

In NanoSSH Client shell implementations, the client terminal text windows’ dimensions may be resized from their defaults (80 x 24). This function is necessary when using NanoSSH Client as an interactive shell. For automated SSH Client applications, this function is unnecessary.

Applicability

Client terminal text window sizing is applicable to NanoSSH Client shell implementations.

Flags

No flags are required to resize the client terminal text window.

Callback Functions

No callback functions are required to resize the client terminal text window.

API Methods

To resize the client terminal text window, call the SSHC_setTerminalTextWindowSize API method.