Core Server Connection Management Functions

Functions
MOC_EXTERN sbyte4	SSH_ackPortFwdReceivedMessageBytes (sbyte4 connectionInstance, enum sshSessionTypes sessionEvent, ubyte4 numBytesAck, ubyte4 channel)
	Send an acknowledgement that data was received by the server. More...
MOC_EXTERN sbyte4	SSH_assignCertificateStore (sbyte4 connectionInstance, certStorePtr pCertStore)
	Associate host keys with a connection. More...
MOC_EXTERN sbyte4	SSH_getCookie (sbyte4 connectionInstance, sbyte4 *pCookie)
	Get a connection context's custom information. More...
MOC_EXTERN sbyte4	SSH_releaseTables (void)
	Release NanoSSH server's internal memory tables. More...
MOC_EXTERN sbyte4	SSH_sendPortForwardClose (sbyte4 connectionInstance, sbyte4 channel)
	Send an SSH CLOSE message to an SSH client whose local port forwarding socket is inactive. More...
MOC_EXTERN sbyte4	SSH_sendPortForwardMessage (sbyte4 connectionInstance, sbyte4 channel, sbyte *pBuffer, sbyte4 bufferSize, sbyte4 *pBytesSent)
	Send a message to a client over a secure SSH connection. More...
MOC_EXTERN sbyte4	SSH_setCookie (sbyte4 connectionInstance, sbyte4 cookie)
	Store custom information (a cookie) about the context connection. More...
MOC_EXTERN sbyte4	SSH_shutdown (void)
	Disconnect all clients and shut down the NanoSSH server stack. More...

Detailed Description

Function Documentation

SSH_ackPortFwdReceivedMessageBytes()

MOC_EXTERN sbyte4 SSH_ackPortFwdReceivedMessageBytes	(	sbyte4	connectionInstance,
		enum sshSessionTypes	sessionEvent,
		ubyte4	numBytesAck,
		ubyte4	channel
	)

This function sends an acknowledgement that data was received by the server on the specified connection. Your application must explicitly call this function; there is no automatic acknowledgement. This function is similar to SSH_ASYNC_ackReceivedMessageBytes(), but is applicable only for port forwarding, where it must be used.

Since

3.06

Version

4.0 and later

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

• __ENABLE_MOCANA_SSH_PORT_FORWARDING__

Parameters

connectionInstance	Connection instance returned from SSH_acceptConnection() or SSH_ASYNC_acceptConnection().
sessionEvent	Type of message for which data was received (an sshSessionTypes enumerated value, defined in ssh.h).
numBytesAck	Number of bytes received.
channel	Channel number from the SSH client side; used for local multiport forwarding.

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_assignCertificateStore()

MOC_EXTERN sbyte4 SSH_assignCertificateStore	(	sbyte4	connectionInstance,
		certStorePtr	pCertStore
	)

This function associates host keys with a specific connection. Based on the certificate store contents, the NanoSSH server can determine the authentication type to negotiate with the client. This function should only be called after SSH_acceptConnection() and before SSH_negotiateConnection().

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__

ssh.h

For an example of how to call this function, refer to ssh_example.c in the sample code (examples directory).

Parameters

connectionInstance	Connection instance returned from SSH_acceptConnection() or SSH_ASYNC_acceptConnection().
pCertStore	Pointer to host keys.

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.h

SSH_getCookie()

MOC_EXTERN sbyte4 SSH_getCookie	(	sbyte4	connectionInstance,
		sbyte4 *	pCookie
	)

This function retrieves custom information stored in the connection instance's context. Your application should call this function after calls to SSH_setCookie() or to make custom SSH upcalls (callbacks).

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().
pCookie	On return, pointer to cookie containing custom information.

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.

See also

SSH_setCookie()

mySessionInfo *myCookie = NULL;

SSH_getCookie(connectionInstance, (int *)(&myCookie));

Remarks

This function is applicable to synchronous and asynchronous servers.

ssh.h

SSH_releaseTables()

MOC_EXTERN sbyte4 SSH_releaseTables

(

void

)

This function releases the NanoSSH server's internal memory tables. It should be called only after a call to SSH_shutdown(). To resume communication with a device after calling this function, you must create a new connection and register encryption keys.

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__

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.

sbyte4 status = 0;

status = SSH_releaseTables():

Remarks

This function is applicable to synchronous and asynchronous servers.

ssh.h

SSH_sendPortForwardClose()

MOC_EXTERN sbyte4 SSH_sendPortForwardClose	(	sbyte4	connectionInstance,
		sbyte4	channel
	)

This function sends an SSH CLOSE message to an SSH client whose local port forwarding socket is inactive. (The port may be inactive due to an error or due to the forwarded server deliberately dropping the connection.)

Note

This function should be called only for clients whose local port forwarding socket is inactive. Results are undefined if the local port forwarding socket is active.

Since

3.06

Version

3.06 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().
channel	Port forwarding channel through which to send the message (for example, SSH_PF_DATA).

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_sendPortForwardMessage()

MOC_EXTERN sbyte4 SSH_sendPortForwardMessage	(	sbyte4	connectionInstance,
		sbyte4	channel,
		sbyte *	pBuffer,
		sbyte4	bufferSize,
		sbyte4 *	pBytesSent
	)

This function sends a message (typically unencrypted text) to a client over a secure SSH connection unless deadlock prevention is enabled by the ENABLE_MOCANA_SSH_SENDER_RECV flag and the SSH transport window size indicates insufficient client acknowledgement of previously sent data.

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().
channel	Port forwarding channel through which to send the message (for example, SSH_PF_DATA).
pBuffer	Pointer to the data buffer to send.
bufferSize	Number of bytes in data buffer to send (pBuffer).
pBytesSent	On return, pointer to number of bytes successfully sent.

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.

// received data from pfSock, move bytes from server side to client side
if ((pCookieStructure->pfSockActive) &&
    (0 != FD_ISSET(pCookieStructure->pfSock, pSocketList)))
{
    // read bytes from pfSock
    if (0 > TCP_READ_AVL(pCookieStructure->pfSock, pInBuffer, MAX_SESSION_WINDOW_SIZE, &numBytesReceived, 1))
    {
        goto exit;
    }

    // forward data to socket
    if (0 < numBytesReceived)
    {
        if (0 > (SSH_sendPortForwardMessage(connInstance, SSH_PF_DATA, pInBuffer, numBytesReceived, &bytesSent)))
            goto exit;
    }
}

Remarks

This function is applicable to synchronous and asynchronous servers.

ssh.h

SSH_setCookie()

MOC_EXTERN sbyte4 SSH_setCookie	(	sbyte4	connectionInstance,
		sbyte4	cookie
	)

This function stores custom information about the context connection. Your application should call this function after calling SSH_acceptConnection().

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().
cookie	Custom data (the cookie).

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.

See also

SSH_setCookie()

mySessionInfo *mySession = malloc(sizeof(mySessionInfo));

// setup my session info
SSH_setCookie(connectionInstance, (int)(mySession));

Remarks

This function is applicable to synchronous and asynchronous servers.

ssh.h

SSH_shutdown()

MOC_EXTERN sbyte4 SSH_shutdown

(

void

)

This function disconnects all clients and shuts down the NanoSSH server stack.

In rare instances, for example changing the port number to which an embedded device listens, you many need to completely stop the NanoSSH server and all its resources. However, in most circumstances this is unnecessary because the NanoSSH server is threadless.

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__

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.

sbyte4 status = 0;

status = SSH_shutdown();

Remarks

This function is applicable to synchronous and asynchronous servers.

ssh.h