Functions
MOC_EXTERN MSTATUS	SSH_KNOWN_HOSTS_addKnownHostsEntry (ubyte *ppBuffer, ubyte4 bufferLen, ubyte hostName, ubyte pKey, sbyte4 pKeyLen, ubyte4 *pRetVal)
	Add a host entry to a NanoSSH known-host list. More...

MOC_EXTERN MSTATUS	SSH_KNOWN_HOSTS_checkHostEntryExists (ubyte pBuffer, ubyte4 bufferLen, ubyte hostName, ubyte4 pIndex, ubyte4 pRetVal)
	Determine whether a host entry already exists in a given known-host buffer. More...

MOC_EXTERN MSTATUS	SSH_KNOWN_HOSTS_getEntries (sbyte4 *pEntries)
	Get the number of entries in the NanoSSH known-hosts list. More...

MOC_EXTERN MSTATUS	SSH_KNOWN_HOSTS_removeKnownHostsEntry (ubyte *ppBuffer, ubyte4 pBufferLen, ubyte hostName, ubyte4 passed_index, ubyte4 *pRetVal)
	Remove a host entry from a given known-hosts buffer, if found. More...

MOC_EXTERN MSTATUS	SSH_KNOWN_HOSTS_retrieveKeyForKnownHostsEntry (ubyte pBuffer, ubyte4 bufferLen, ubyte hostName, ubyte *ppKey, ubyte4 pKeyLen, ubyte4 *pRetVal)
	Get the key that corresponds to a given host name. More...

MOC_EXTERN MSTATUS	SSH_KNOWN_HOSTS_updateEntries (ubyte *pBuffer, ubyte4 bufferLen)
	Update the global known-hosts entries count, based on a given known-hosts buffer. More...

MOC_EXTERN MSTATUS	SSH_KNOWN_HOSTS_updateKnownHostsEntry (ubyte *ppBuffer, ubyte4 pBufferLen, ubyte hostName, ubyte pKey, sbyte4 pKeyLen, ubyte4 *pRetVal)
	Update or add a host entry to a NanoSSH known-host list. More...

MOC_EXTERN MSTATUS	SSH_KNOWN_HOSTS_verifyKnownHostKeyEntry (ubyte pBuffer, ubyte4 bufferLen, ubyte hostName, ubyte pKey, sbyte4 pKeyLen, ubyte4 pRetVal)
	Verify that a given key matches a given host's key in the given known-hosts buffer. More...

Detailed Description

Function Documentation

◆ SSH_KNOWN_HOSTS_addKnownHostsEntry()

MOC_EXTERN MSTATUS SSH_KNOWN_HOSTS_addKnownHostsEntry	(	ubyte **	ppBuffer,
		ubyte4 *	bufferLen,
		ubyte *	hostName,
		ubyte *	pKey,
		sbyte4	pKeyLen,
		ubyte4 *	pRetVal
	)

This function adds a host entry to the end of the NanoSSH known-host list.

Before calling this function, call SSH_KNOWN_HOSTS_checkHostEntryExits() to check whether the host entry is already in the known-host list, which avoids adding duplicate entries.

Or instead of calling SSH_KNOWN_HOSTS_addKnownHostsEntry (this function), you can call SSH_KNOWN_HOSTS_updateKnownHostsEntry(), which checks the list to see if the specified host name is already in the known-host list. If the host is in the list, the entry is updated; if the host is not found, it is added.

Note: The address that is referenced by ppBuffer is changed by this function call.

This function allocates memory for a new known-host list buffer that is the combined size of the existing known-host list plus the new entry. The function copies the existing buffer contents plus the new entry to the newly allocated buffer, and then frees the original buffer.

If this is the first call to SSH_KNOWN_HOSTS_addKnownHostsEntry after reading a file of host entries, you should call SSH_KNOWN_HOSTS_updateEntries(), which updates the value of the global variable that tracks the number of entries in the known-hosts list.

Since: 5.4

Version: 5.4 and later

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

__ENABLE_SSH_KNOWN_HOSTS__

ssh_known_hosts.h

Parameters

ppBuffer	NULL or a pointer to the address of a buffer containing a list of known-host entries. On return, reference to the new buffer containing the contents of the submitted buffer (if any) plus an entry created from the submitted host name and key. The original buffer, if not NULL, is freed.
pBufferLen	Pointer to the length of the input buffer, `ppBuffer`. On return, the value is updated to the new buffer's length.
hostName	Pointer to DNS name or IP address to add.
pKey	Pointer to key associated with the host name, `hostName`, to add.
pKeyLen	Pointer to length of the key, `pKey`.
pRetVal	On return, pointer to the value 1 if the host is added to the known-host list; 0 if the host was not added.

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_known_hosts.c

◆ SSH_KNOWN_HOSTS_checkHostEntryExists()

MOC_EXTERN MSTATUS SSH_KNOWN_HOSTS_checkHostEntryExists	(	ubyte *	pBuffer,
		ubyte4	bufferLen,
		ubyte *	hostName,
		ubyte4 *	pIndex,
		ubyte4 *	pRetVal
	)

This function determines whether there is an entry for a given host in a given known-host buffer. If so, this function returns, through the pIndex parameter, the 0-based index to the found entry's line in the buffer.

Since: 5.4

Version: 5.4 and later

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

__ENABLE_SSH_KNOWN_HOSTS__

ssh_known_hosts.h

Parameters

pBuffer	Pointer to a buffer containing the known-hosts list for NanoSSH.
bufferLen	Length of the input buffer, `pBuffer`.
hostName	Pointer to DNS name or IP address to search for.
pIndex	On return, if the entry is found (indicated by a value of 1 returned through the `pRetVal` parameter is 1), the 0-based index to the found entry's line in `pBuffer`.
pRetVal	On return, pointer to the value 1 if the entry is found in `pBuffer`; 0 if the entry was not found.

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_known_hosts.c

◆ SSH_KNOWN_HOSTS_getEntries()

MOC_EXTERN MSTATUS SSH_KNOWN_HOSTS_getEntries ( sbyte4 * pEntries )

This function returns (through the pEntries parameter) the number of entries in the NanoSSH known-hosts list. The entries count equals the global known-hosts entries count, SSH_KNOWN_HOSTS_entries, which is incremented for every successful call to SSH_KNOWN_HOSTS_addKnownHostsEntry(), and decremented for every successful call to SSH_KNOWN_HOSTS_removeKnownHostsEntry().

Warning: If you directly manipulate the NanoSSH known-hosts list (that is, add or delete entries without calling SSH_KNOWN_HOSTS_addKnownHostsEntry() or SSH_KNOWN_HOSTS_removeKnownHostsEntry()), you must call call SSH_KNOWN_HOSTS_updateEntries() to update the global known-hosts entries count. If you do not make this call, the global known-hosts entries count, SSH_KNOWN_HOSTS_entries, will be incorrect.

Since: 5.4

Version: 5.4 and later

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

__ENABLE_SSH_KNOWN_HOSTS__

ssh_known_hosts.h

Parameters

pEntries On return, the number of entries in the NanoSSH known-hosts list, based on the value of the global known-hosts entries count, SSH_KNOWN_HOSTS_entries.

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_known_hosts.c

◆ SSH_KNOWN_HOSTS_removeKnownHostsEntry()

MOC_EXTERN MSTATUS SSH_KNOWN_HOSTS_removeKnownHostsEntry	(	ubyte **	ppBuffer,
		ubyte4 *	pBufferLen,
		ubyte *	hostName,
		ubyte4 *	passed_index,
		ubyte4 *	pRetVal
	)

This function removes a host entry from a given known-hosts buffer, if found.

Since: 5.4

Version: 5.4 and later

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

__ENABLE_SSH_KNOWN_HOSTS__
__ENABLE_MOCANA_IPV6__

ssh_known_hosts.h

Parameters

ppBuffer	NULL or a pointer to the address of a buffer containing a list of known-host entries. On return, referec to the new buffer containing the contents of the submitted buffer (if any) minus the deleted entry. The original buffer, if not NULL, is freed.
pBufferLen	Pointer to the length of the input buffer, `ppBuffer`. On return, the value is updated to the new buffer's length.
hostName	Pointer to DNS name or IP address to remove.

Note: If you pass a value in through the passed_index parameter, it overrides the hostName parameter. That is, the entry for the passed_index is removed even if it does not match the hostName value.

Parameters

passed_index	NULL to match the `hostName` value; otherwise the 0-based index of the line to remove from the given known-hosts buffer, `ppBuffer`.
pRetVal	On return, pointer to the value 1 if the host is removed from the known-host list; 0 if the host was not removed.

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_known_hosts.c

◆ SSH_KNOWN_HOSTS_retrieveKeyForKnownHostsEntry()

MOC_EXTERN MSTATUS SSH_KNOWN_HOSTS_retrieveKeyForKnownHostsEntry	(	ubyte *	pBuffer,
		ubyte4	bufferLen,
		ubyte *	hostName,
		ubyte **	ppKey,
		ubyte4 *	pKeyLen,
		ubyte4 *	pRetVal
	)

This function returns (through the ppKey parameter) the key for a given host name.

Since: 5.4

Version: 5.4 and later

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

__ENABLE_SSH_KNOWN_HOSTS__
__ENABLE_MOCANA_IPV6__

ssh_known_hosts.h

Parameters

pBuffer	NULL or a pointer to a buffer containing a list of known-host entries.
bufferLen	Length of the input buffer, `pBuffer`.
hostName	DNS name or IP address that the key is matched to.
ppKey	On return, pointer to key value, if the key is found.
pKeyLen	On return, length of the key value, `ppKey`, if the key is found.
pRetVal	On return, pointer to the value 1 if the is found; 0 if not.

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_known_hosts.c

◆ SSH_KNOWN_HOSTS_updateEntries()

MOC_EXTERN MSTATUS SSH_KNOWN_HOSTS_updateEntries	(	ubyte *	pBuffer,
		ubyte4	bufferLen
	)

The function updates the global known-hosts entries count, SSH_KNOWN_HOSTS_entries, based on the number of entries in a given buffer, pBuffer.

If you directly manipulate the NanoSSH known-hosts list (that is, read a hosts file by calling SSH_KNOWN_HOSTS_readFile(), or add or delete entries by means other than calling SSH_KNOWN_HOSTS_addKnownHostsEntry() or SSH_KNOWN_HOSTS_removeKnownHostsEntry()), you must call call SSH_KNOWN_HOSTS_updateEntries to update the global variable count.

Since: 5.4

Version: 5.4 and later

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

__ENABLE_SSH_KNOWN_HOSTS__
__ENABLE_MOCANA_IPV6__

ssh_known_hosts.h

Parameters

pBuffer	Pointer to a buffer containing a list of known-host entries.
bufferLen	Length the input buffer, `pBuffer`.

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_known_hosts.c

◆ SSH_KNOWN_HOSTS_updateKnownHostsEntry()

MOC_EXTERN MSTATUS SSH_KNOWN_HOSTS_updateKnownHostsEntry	(	ubyte **	ppBuffer,
		ubyte4 *	pBufferLen,
		ubyte *	hostName,
		ubyte *	pKey,
		sbyte4	pKeyLen,
		ubyte4 *	pRetVal
	)

This function updates a host entry in a NanoSSH known-host list if the entry is already present. If the entry is not in the known-host list, this function adds it.

Since: 5.4

Version: 5.4 and later

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

__ENABLE_SSH_KNOWN_HOSTS__
__ENABLE_MOCANA_IPV6__

ssh_known_hosts.h

Parameters

ppBuffer	NULL or a pointer to the address of a buffer containing a list of known-host entries. On return, reference to the new buffer containing the contents of the submitted buffer (if any) and the changed/added entry as specified by the remaining parameters. The original buffer, if not NULL, is freed.
pBufferLen	Pointer to the length of the input buffer, `ppBuffer`. On return, the value is updated to the new buffer's length.
hostName	Pointer to DNS name or IP address to update/add.
pKey	Pointer to key to update for the host name, `hostName`, if the host is already in the buffer, or the key include in the entry if it is added.
pKeyLen	Pointer to length of the key, `pKey`.
pRetVal	On return, pointer to the value 1 if the host is updated/added; 0 if the host was not updated/added.

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_known_hosts.c

◆ SSH_KNOWN_HOSTS_verifyKnownHostKeyEntry()

MOC_EXTERN MSTATUS SSH_KNOWN_HOSTS_verifyKnownHostKeyEntry	(	ubyte *	pBuffer,
		ubyte4	bufferLen,
		ubyte *	hostName,
		ubyte *	pKey,
		sbyte4	pKeyLen,
		ubyte4 *	pRetVal
	)

This function verifies that a given key matches a given host's key in the given known-hosts buffer.

Since: 5.4

Version: 5.4 and later

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

__ENABLE_SSH_KNOWN_HOSTS__
__ENABLE_MOCANA_IPV6__

ssh_known_hosts.h

Parameters

pBuffer	NULL or a pointer to the address of a buffer containing a list of known-host entries.
bufferLen	Length of the input buffer, `pBuffer`.
hostName	Pointer to DNS name or IP address of the host to verify.
pKey	Pointer to key to match.
pKeyLen	Pointer to length of the key, `pKey`.
pRetVal	On return, pointer to the value 1 if the host key matches the given key; 0 if the host key does not match the given key.

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_known_hosts.c

Functions

Detailed Description

Function Documentation

◆ SSH_KNOWN_HOSTS_addKnownHostsEntry()

◆ SSH_KNOWN_HOSTS_checkHostEntryExists()

◆ SSH_KNOWN_HOSTS_getEntries()

◆ SSH_KNOWN_HOSTS_removeKnownHostsEntry()

◆ SSH_KNOWN_HOSTS_retrieveKeyForKnownHostsEntry()

◆ SSH_KNOWN_HOSTS_updateEntries()

◆ SSH_KNOWN_HOSTS_updateKnownHostsEntry()

◆ SSH_KNOWN_HOSTS_verifyKnownHostKeyEntry()