Core Server Security Functions

Functions
MOC_EXTERN MSTATUS	SSH_AUTH_allocStructures (sshContext *pContextSSH)
	Initialize SSH authentication structure. More...
MOC_EXTERN MSTATUS	SSH_AUTH_deallocStructures (sshContext *pContextSSH)
	Release SSH authentication structure. More...
MOC_EXTERN MSTATUS	SSH_AUTH_doProtocol (sshContext *pContextSSH, ubyte *pNewMesg, ubyte4 newMesgLen)
	Does the Authentication Protocol for SSH. More...
MOC_EXTERN sbyte4	SSH_compareAuthKeys (const ubyte *pPubKey, ubyte4 pubKeyLength, const ubyte *pFileKey, ubyte4 fileKeyLength, sbyte4 *pRetIsMatch)
	Authenticate a client by public key authentication. More...
MOC_EXTERN sbyte4	SSH_convertOldKeyBlobToNew (ubyte *pOldDsaPublicKeyBlob, ubyte4 oldDsaPublicKeyBlobLength, ubyte *pOldDsaPrivateKeyBlob, ubyte4 oldDsaPrivateKeyBlobLength, ubyte **ppRetNewKeyBlob, ubyte4 *pRetNewKeyBlobLength)
	Convert a key blob from NanoSSH version 1.41 and earlier formats to version 2.02 format. More...
MOC_EXTERN sbyte4	SSH_getInstanceFromSocket (TCP_SOCKET socket)
	Get a socket's connection instance. More...
MOC_EXTERN sbyte4	SSH_getNextConnectionInstance (sbyte4 connectionInstance)
	Get the next connection instance from the active NanoSSH connection instance table. More...
MOC_EXTERN sbyte4	SSH_getSessionCryptoInfo (sbyte4 connectionInstance, sbyte **ppInCipherName, sbyte **ppInMacName, sbyte **ppOutCipherName, sbyte **ppOutMacName)
	Get a NanoSSH session's cipher names. More...
MOC_EXTERN sbyte4	SSH_getSocketId (sbyte4 connectionInstance, TCP_SOCKET *pRetSocket)
	Get a connection's socket identifier. More...
MOC_EXTERN sbyte4	SSH_initiateReKey (sbyte4 connectionInstance, ubyte4 msAllowToComply)
	Initiate an SSH re-key operation. More...
MOC_EXTERN sbyte4	SSH_numBytesTransmitted (sbyte4 connectionInstance, ubyte8 *pRetNumBytes)
	Get the number of bytes sent and received through a given connectionInstance. More...
MOC_EXTERN sbyte4	SSH_setUserPortForwardingPermissions (sbyte4 connectionInstance, ubyte4 memberGroups)
	Set a connection's port forwarding access permission. More...
MOC_EXTERN sbyte4	SSH_useThisCipherList (sbyte4 connectionInstance, ubyte *pCipherList)
	Set a server's cipher list. More...
MOC_EXTERN sbyte4	SSH_useThisHmacList (sbyte4 connectionInstance, ubyte *pHmacList)
	Set a server's HMAC list. More...
MOC_EXTERN sbyte4	SSH_verifyPublicKeyFile (sbyte *pKeyFileData, ubyte4 fileSize)
	Verify that an RSA or DSS/DSA or ECC or EDDSA public key file format is valid. More...

Detailed Description

Function Documentation

SSH_AUTH_allocStructures()

MOC_EXTERN MSTATUS SSH_AUTH_allocStructures

(

sshContext *

pContextSSH

)

This function initializes authDescr structure in sshContext. It initializes keyInitAuthContext with NULL values, and allocates pAuthFailueBuffer with default values.

Since

4.2

Version

4.2 and later

To enable this function, at least one of the following flags must be defined:

• __ENABLE_MOCANA_SSH_SERVER__

Parameters

pContextSSH

SSH context whose authDescr field authContext will be populated.

ssh_auth.h

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

Remarks

To initialize a SSH context, use SSH_CONTEXT_allocStructures, which itself calls this function.

ssh_auth.h

SSH_AUTH_deallocStructures()

MOC_EXTERN MSTATUS SSH_AUTH_deallocStructures

(

sshContext *

pContextSSH

)

Free data in authDescr structure of sshContext.

Since

4.2

Version

4.2 and later

To enable this function, at least one of the following flags must be defined:

• __ENABLE_MOCANA_SSH_SERVER__

Parameters

pContextSSH

SSH context containing authDescr to release.

ssh_auth.h

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

Remarks

This function should not be called directly, instead call SSH_CONTEXT_deallocStructures.

ssh_auth.h

SSH_AUTH_doProtocol()

MOC_EXTERN MSTATUS SSH_AUTH_doProtocol	(	sshContext *	pContextSSH,
		ubyte *	pNewMesg,
		ubyte4	newMesgLen
	)

Does the Authentication Protocol for SSH. Defined in RFC 4252. Receives service request and processes authentication message from client.

Since

4.2

Version

4.2 and later

To enable this function, at least one of the following flags must be defined:

• __ENABLE_MOCANA_SSH_SERVER__

Parameters

pContextSSH	SSH context for authentication request
pNewMesg	SSH binary packet containing message
newMesgLen	Length in bytes of pNewMesg

ssh_auth.h

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

ssh_auth.h

SSH_compareAuthKeys()

MOC_EXTERN sbyte4 SSH_compareAuthKeys	(	const ubyte *	pPubKey,
		ubyte4	pubKeyLength,
		const ubyte *	pFileKey,
		ubyte4	fileKeyLength,
		sbyte4 *	pRetIsMatch
	)

This function (which should be called from the public key authentication callback method sshSettings::funcPtrPubKeyAuth) authenticates a client by public key authentication.

The key file may be any host key generated by any SSH-compliant client.

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_SSH_SERVER__
• __ENABLE_MOCANA_SSH_ASYNC_SERVER_API__

Parameters

pPubKey	Pointer to public key provided by the client.
pubKeyLength	Number of bytes in public key (pPubKey).
pFileKey	Pointer to the key on file to which the client's key will be compared.
fileKeyLength	Number of bytes in the key on file (pFileKey).
pRetIsMatch	On return, pointer to TRUE if the client's public key matches the key on file; otherwise pointer to FALSE.

ssh.h

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

Remarks

This function is applicable to synchronous and asynchronous servers.

ssh.h

SSH_convertOldKeyBlobToNew()

MOC_EXTERN sbyte4 SSH_convertOldKeyBlobToNew	(	ubyte *	pOldDsaPublicKeyBlob,
		ubyte4	oldDsaPublicKeyBlobLength,
		ubyte *	pOldDsaPrivateKeyBlob,
		ubyte4	oldDsaPrivateKeyBlobLength,
		ubyte **	ppRetNewKeyBlob,
		ubyte4 *	pRetNewKeyBlobLength
	)

This function converts a key blob from NanoSSH version 1.41 and earlier formats to version 2.02 format. The 2.02 format adds RSA and ECC keys, providing greater flexibility and making development easier.

Since

2.02

Version

2.02 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_SSH_SERVER__
• __ENABLE_MOCANA_SSH_ASYNC_SERVER_API__

Additionally, the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_SSH_OLD_DSA_CONVERSION__
• __ENABLE_MOCANA_DSA__

ssh.h

Note

The public key is always the longer of the public/private key pair, and the private key is typically 24 or 25 bytes. Inadvertently swapping them in this function call causes an error to be returned.

Parameters

pOldDsaPublicKeyBlob	Pointer to original (pre-2.02 format) public key blob.
oldDsaPublicKeyBlobLength	Number of bytes in original public key blob (pOldDsaPublicKeyBlob).
pOldDsaPrivateKeyBlob	Pointer to original (pre-2.02 format) private key blob.
oldDsaPrivateKeyBlobLength	Number of bytes in original private key blob (pOldDsaPrivateKeyBlob).
ppRetNewKeyBlob	On return, pointer to new 2.02-formatted key blob, which contains both public and private keys.
pRetNewKeyBlobLength	On return, pointer to number of bytes in new key blob (ppRetNewKeyBlob).

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

{
    ubyte*  pPubKeyBlob = NULL;
    ubyte4  pubKeyBlobLength;
    ubyte*  pPrivKeyBlob = NULL;
    ubyte4  privKeyBlobLength;
    ubyte*  pKeyBlob;
    ubyte4  keyBlobLength;

    // read old dsa key blob, filenames may be different
    status = MOCANA_readFile("sshkeys.pub", &pPubKeyBlob, &pubKeyBlobLength);
    status = MOCANA_readFile("sshkeys.prv", &pPrivKeyBlob, &privKeyBlobLength);

    // convert to new format
    status = SSH_convertOldKeyBlobToNew(pPubKeyBlob, pubKeyBlobLength, pPrivKeyBlob, privKeyBlobLength, &pKeyBlob, &keyBlobLength);

    // save new key blob
    status = MOCANA_writeFile("ssh_dss.key", pKeyBlob, keyBlobLength);

    // it may be a good idea to delete the old key blob at this time

    MOCANA_freeReadFile(&pPubKeyBlob);
    MOCANA_freeReadFile(&pPrivKeyBlob);
    CA_MGMT_freeNakedKey(&pKeyBlob);
}

ssh.h

SSH_getInstanceFromSocket()

MOC_EXTERN sbyte4 SSH_getInstanceFromSocket

(

TCP_SOCKET

socket

)

This function retrieves a socket's connection instance.

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_SSH_SERVER__
• __ENABLE_MOCANA_SSH_ASYNC_SERVER_API__

Parameters

socket

TCP/IP socket whose connection instance you want.

ssh.h

Returns

Socket instance identifier if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

Remarks

This function is applicable to synchronous and asynchronous servers.

ssh.h

SSH_getNextConnectionInstance()

MOC_EXTERN sbyte4 SSH_getNextConnectionInstance

(

sbyte4

connectionInstance

)

This function traverses the active NanoSSH connection instance table, and returns the }next} connection instance. Your application can use this connection instance in a call to SSH_getSessionCryptoInfo().

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_SSH_SERVER__
• __ENABLE_MOCANA_SSH_ASYNC_SERVER_API__

Parameters

connectionInstance

Connection instance returned from SSH_acceptConnection() or SSH_ASYNC_acceptConnection().

ssh.h

Returns

A pointer to the }next} connection instance; 0 if there are no more active connections.

Remarks

This function is applicable to synchronous and asynchronous servers.

ssh.h

SSH_getSessionCryptoInfo()

MOC_EXTERN sbyte4 SSH_getSessionCryptoInfo	(	sbyte4	connectionInstance,
		sbyte **	ppInCipherName,
		sbyte **	ppInMacName,
		sbyte **	ppOutCipherName,
		sbyte **	ppOutMacName
	)

This function retrieves the cipher names (strings) used for the specified NanoSSH session (connection instance).

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_SSH_SERVER__
• __ENABLE_MOCANA_SSH_ASYNC_SERVER_API__

Parameters

connectionInstance	Connection instance returned from SSH_acceptConnection(), SSH_ASYNC_acceptConnection(), or SSH_getNextConnectionInstance.()
ppInCipherName	On return, pointer to string containing the inbound cipher name (for example, "AES-256-CBC" or "BLOWFISH-CBC").
ppInMacName	On return, pointer to string containing the inbound MAC name (for example, "HMAC-MD5-96" or "HMAC-SHA1").
ppOutCipherName	On return, pointer to string containing the outbound cipher name (for example, "3DES-CBC").
ppOutMacName	On return, pointer to string containing the outbound MAC name (for example, "HMAC-SHA1-96" or "HMAC-MD5").

ssh.h

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

static void
exampleUsage(void)
{
  sbyte4 temp = 0;

  while ((temp = SSH_getNextConnectionInstance(temp)) &&
         (0 != temp))
  {
    ubyte *pInCipher;

    if (0 <= SSH_getSessionCryptInfo(temp, &pInCipher, 0, 0, 0))
      printf("session %d, using %s cipher\n", temp, pInCipher);
  }
}

Remarks

This function is applicable to synchronous and asynchronous servers.

ssh.h

SSH_getSocketId()

MOC_EXTERN sbyte4 SSH_getSocketId	(	sbyte4	connectionInstance,
		TCP_SOCKET *	pRetSocket
	)

This function retrieves a connection instance's socket identifier.

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_SSH_SERVER__
• __ENABLE_MOCANA_SSH_ASYNC_SERVER_API__

Parameters

connectionInstance	Connection instance returned from SSH_acceptConnection() or SSH_ASYNC_acceptConnection().
pRetSocket	On return, pointer to the socket corresponding to the connection instance.

ssh.h

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

Remarks

This function is applicable to synchronous and asynchronous servers.

ssh.h

SSH_initiateReKey()

MOC_EXTERN sbyte4 SSH_initiateReKey	(	sbyte4	connectionInstance,
		ubyte4	msAllowToComply
	)

This function initiates an SSH re-key operation. NanoSSH automatically processes re-key requests from SSH clients.

Since

4.2

Version

4.2 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_SSH_SERVER__
• __ENABLE_MOCANA_SSH_ASYNC_SERVER_API__

Parameters

connectionInstance	Connection instance returned from SSH_acceptConnection() or SSH_ASYNC_acceptConnection().
msAllowToComply	Number of milliseconds to wait for an SSH client to respond before closing the session. Zero (0) indicates that the request is not being strictly enforced.

ssh.h

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

Remarks

This function is applicable to synchronous and asynchronous servers.

Many SSH implementations do not support re-keying.

ssh.h

SSH_numBytesTransmitted()

MOC_EXTERN sbyte4 SSH_numBytesTransmitted	(	sbyte4	connectionInstance,
		ubyte8 *	pRetNumBytes
	)

This function returns (through the pRetNumBytes parameter) the number of bytes sent and received through a given connectionInstance. Typical usage for this function is to determine when it's appropriate to initiate a re-key exchange operation.

Since

4.2

Version

4.2 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_SSH_SERVER__
• __ENABLE_MOCANA_SSH_ASYNC_SERVER_API__

Parameters

connectionInstance	Connection instance returned from SSH_acceptConnection() or SSH_ASYNC_acceptConnection().
pRetNumBytes	On return, the number of bytes received and transmitted.

ssh.h

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

Remarks

This function is applicable to synchronous and asynchronous servers.

ssh.h

SSH_setUserPortForwardingPermissions()

MOC_EXTERN sbyte4 SSH_setUserPortForwardingPermissions	(	sbyte4	connectionInstance,
		ubyte4	memberGroups
	)

This function sets a connection's port forwarding access permission to the specified combination of the following bit flag constants:

• MOCANA_SSH_ALLOW_DIRECT_TCPIP
• MOCANA_SSH_ALLOW_FORWARDED_TCPIP
• MOCANA_SSH_ALLOW_PRIVILEGED_DIRECT_TCPIP

Since

1.41

Version

1.41 and later

To enable this function, the following flag must be defined in moptions.h:

• __ENABLE_MOCANA_SSH_PORT_FORWARDING__

Additionally, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_SSH_SERVER__
• __ENABLE_MOCANA_SSH_ASYNC_SERVER_API__

Parameters

connectionInstance	Connection instance returned from SSH_acceptConnection() or SSH_ASYNC_acceptConnection().
memberGroups	Combination of bit flag constant(s) specifying the desired port forwarding access permission.

ssh.h

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

Remarks

This function is applicable to synchronous and asynchronous servers.

ssh.h

SSH_useThisCipherList()

MOC_EXTERN sbyte4 SSH_useThisCipherList	(	sbyte4	connectionInstance,
		ubyte *	pCipherList
	)

This function dynamically updates cipher support selection.

Since

2.02

Version

2.02 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_SSH_SERVER__
• __ENABLE_MOCANA_SSH_ASYNC_SERVER_API__

Parameters

connectionInstance	Connection instance returned from SSH_acceptConnection() or SSH_ASYNC_acceptConnection().
pCipherList	Pointer to a C string (NULL-terminated) cipher list to advertise. (See ssh_trans.c for the list of available ciphers.)

ssh.h

Note

This function is applicable only when the connection state is CONNECT_NEGOTIATE.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

if (OK > (ci = SSH_acceptConnection(socketClient)))
{
    DEBUG_PRINTNL(DEBUG_SSH_EXAMPLE, "SSH_EXAMPLE_startServer: Too many open connections.");
    TCP_CLOSE_SOCKET(socketClient);
    continue;
}

SSH_useThisCipherList(ci, "3des-cbc");

if (OK > (status = RTOS_createThread(SSH_EXAMPLE_simpleDemo, (void*)ci, SSH_SESSION, &tid)))
{
    DEBUG_PRINTNL(DEBUG_SSH_EXAMPLE, "SSH_EXAMPLE_startServer: Too many open connections.");
    TCP_CLOSE_SOCKET(socketClient);
    goto exit;
}

ssh.h

SSH_useThisHmacList()

MOC_EXTERN sbyte4 SSH_useThisHmacList	(	sbyte4	connectionInstance,
		ubyte *	pHmacList
	)

This function dynamically updates HMAC support selelction.

Since

2.02

Version

2.02 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_SSH_SERVER__
• __ENABLE_MOCANA_SSH_ASYNC_SERVER_API__

Parameters

connectionInstance	Connection instance returned from SSH_acceptConnection() or SSH_ASYNC_acceptConnection().
pHmacList	Pointer to a C string (NULL-terminated) HMAC list to advertise. (See ssh_trans.c for the list of available HMACs.)

ssh.h

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

if (OK > (ci = SSH_acceptConnection(socketClient)))
{
    DEBUG_PRINTNL(DEBUG_SSH_EXAMPLE, "SSH_EXAMPLE_startServer: Too many open connections.");
    TCP_CLOSE_SOCKET(socketClient);
    continue;
}

SSH_useThisHmacList(ci, "hmac-md5-96,hmac-md5");

if (OK > (status = RTOS_createThread(SSH_EXAMPLE_simpleDemo, (void*)ci, SSH_SESSION, &tid)))
{
    DEBUG_PRINTNL(DEBUG_SSH_EXAMPLE, "SSH_EXAMPLE_startServer: Too many open connections.");
    TCP_CLOSE_SOCKET(socketClient);
    goto exit;
}

ssh.h

SSH_verifyPublicKeyFile()

MOC_EXTERN sbyte4 SSH_verifyPublicKeyFile	(	sbyte *	pKeyFileData,
		ubyte4	fileSize
	)

This function verifies that the specified SSH RSA or DSS/DSA or ECC or EDDSA public key file format is valid, thereby proving a client's identity. You should call this function to verify every key file that is uploaded to the NanoSSH server or your device.

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_SSH_SERVER__
• __ENABLE_MOCANA_SSH_ASYNC_SERVER_API__

Parameters

pKeyFileData	Pointer to authentication key to be verified.
fileSize	Number of bytes in the public key (pKeyFileData).

ssh.h

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

ubyte*  pStoredPublicKey = NULL;
ubyte4  storedPublicKeyLength;
sbyte4  result;

    // a pub key on file
    if (0 > MOCANA_readFile(AUTH_KEYFILE_NAME,
                            &pStoredPublicKey,
                            &storedPublicKeyLength))
    {
        goto exit;
    }

    // verify key here
    result = SSH_verifyPublicKeyFile(pStoredPublicKey,
                                storedPublicKeyLength)

// if result == zero (0), the key is valid, otherwise contains error code for reason key is not valid

exit:
// do something here

Remarks

This function is applicable to synchronous and asynchronous servers.

ssh.h