General Purpose Callbacks

Variables
sbyte4(*	sshClientSettings::funcPtrCertStatus )(sbyte4 connectionInstance, sbyte4 cert_status, ubyte *pCertificate, ubyte4 certLen, certChainPtr pCertChain, const ubyte *pAnchorCert, ubyte4 anchorCertLen)
	Verify a client's certificate. More...
sbyte4(*	sshSettings::funcPtrCertStatus )(sbyte4 connectionInstance, const ubyte *pUser, ubyte4 userLength, sbyte4 cert_status, ubyte *pCertificate, ubyte4 certLen, certChainPtr pCertChain, const ubyte *pAnchorCert, ubyte4 anchorCertLen)
	Verify a client's certificate. More...
sbyte4(*	sshSettings::funcPtrConnect )(sbyte4 connectionInstance, sbyte4 sessionNum, ubyte *pConnectHost, ubyte2 port, sbyte4 *pIgnoreRequest, sbyte4 channel)
	(Optional) Custom connection handler. More...
sbyte4(*	sshSettings::funcPtrGetAuthAdvertizedMethods )(sbyte4 connectionInstance)
	(Optional) Custom authorization methods handler. More...
sbyte4(*	sshSettings::funcPtrKeyIntAuthReq )(sbyte4 connectionInstance, const ubyte *pUser, ubyte4 userLength, keyIntInfoResp *pResponseInfo, keyIntInfoReq *pRequestInfo, sbyte4 *pAuthState)
	Authorize a user for an interactive keyboard session. More...
sbyte4(*	sshSettings::funcPtrPasswordAuth )(sbyte4 connectionInstance, const ubyte *pUser, ubyte4 userLength, const ubyte *pPassword, ubyte4 passwordLength)
	Validate the provided password to complete authentication. More...
sbyte4(*	sshSettings::funcPtrPubKeyAuth )(sbyte4 connectionInstance, const ubyte *pUser, ubyte4 userLength, const ubyte *pPubKey, ubyte4 pubKeyLength, ubyte4 keyType)
	Verify a client's public key. More...
sbyte4(*	sshSettings::funcPtrReleaseKeyIntReq )(sbyte4 connectionInstance, keyIntInfoReq *request)
	Release (free) memory used by an unneeded request data buffer. More...
sbyte4(*	sshSettings::funcPtrSessionReKey )(sbyte4 connectionInstance, intBoolean initiatedByRemote)
	Inform the calling application that Session Rekey has been initiated. More...

Detailed Description

Variable Documentation

funcPtrCertStatus [1/2]

sbyte4(* sshClientSettings::funcPtrCertStatus) (sbyte4 connectionInstance, sbyte4 cert_status, ubyte *pCertificate, ubyte4 certLen, certChainPtr pCertChain, const ubyte *pAnchorCert, ubyte4 anchorCertLen)

This callback function is invoked during authentication to verify a client's certificate

Since

6.5

Version

6.5 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().
cert_status	cert verification status done by the stack
pCertificate	certificate of the peer
certLen	length of the certificate buffer
pCertChain	certificate chain leading the to anchor
pAnchorCert	Anchor CA certificate if not present in pCertChain
anchorCertLen	anchor cert length if present

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

funcPtrCertStatus [2/2]

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

This callback function is invoked during authentication to verify a client's certificate

Since

6.5

Version

6.5 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().
pUser	Pointer to user name.
userLength	Number of bytes in user name (pUser).
cert_status	cert verification status done by the stack
pCertificate	certificate of the peer
certLen	length of the certificate buffer
pCertChain	certificate chain leading the to anchor
pAnchorCert	Anchor CA certificate if not present in pCertChain
anchorCertLen	anchor cert length if present

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

funcPtrConnect

sbyte4(* sshSettings::funcPtrConnect) (sbyte4 connectionInstance, sbyte4 sessionNum, ubyte *pConnectHost, ubyte2 port, sbyte4 *pIgnoreRequest, sbyte4 channel)

(Optional) If port forwarding is enabled, this callback function is invoked when a connection channel is opened. You can use this handler to block, redirect, or use a non-socket interface for an incoming channel open request. You can also change the connect address and/or port.

Since

1.41

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() or SSH_ASYNC_acceptConnection().
sessionNum	(Reserved for future use.)
pConnectHost	IP Address of the host to be connected with NanoSSH server.
port	Port number through which to connect to the NanoSSH server host.
pIgnoreRequest	(Reserved for future use.)
channel	Local port forwarded channel number.

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

funcPtrGetAuthAdvertizedMethods

sbyte4(* sshSettings::funcPtrGetAuthAdvertizedMethods) (sbyte4 connectionInstance)

This callback function is invoked at the start of authentication, when the 32-bit bitmask representing the selected authorization methods is returned. You can restrict authorization methods based on the incoming request characteristics, such as IP address.

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

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

funcPtrKeyIntAuthReq

sbyte4(* sshSettings::funcPtrKeyIntAuthReq) (sbyte4 connectionInstance, const ubyte *pUser, ubyte4 userLength, keyIntInfoResp *pResponseInfo, keyIntInfoReq *pRequestInfo, sbyte4 *pAuthState)

This callback function is invoked during interactive keyboard authentication to authorize a user.

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().
pUser	Pointer to user name.
userLength	Number of bytes in user name (pUser).
pResponseInfo	Pointer to previous response buffer (or NULL if this is the first request).
pRequestInfo	On return, pointer to request data.
pAuthState	On return, pointer to state of authentication. Supported states: AUTH_FAIL - Authentication failed. AUTH_PASS - Authentication succeeded. AUTH_MORE - Additional info requests are necessary. AUTH_FAIL_MORE - Authentication failed, additional info requests are necessary.

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

funcPtrPasswordAuth

sbyte4(* sshSettings::funcPtrPasswordAuth) (sbyte4 connectionInstance, const ubyte *pUser, ubyte4 userLength, const ubyte *pPassword, ubyte4 passwordLength)

This callback function is invoked as the final authentication step to validate the provided password.

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().
pUser	Pointer to user name.
userLength	Number of bytes in user name (pUser).
pPassword	Pointer to password.
passwordLength	Number of bytes in password (pPassword).

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

funcPtrPubKeyAuth

sbyte4(* sshSettings::funcPtrPubKeyAuth) (sbyte4 connectionInstance, const ubyte *pUser, ubyte4 userLength, const ubyte *pPubKey, ubyte4 pubKeyLength, ubyte4 keyType)

This callback function is invoked during authentication to verify a client's public key.

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().
pUser	Pointer to user name.
userLength	Number of bytes in user name (pUser).
pPubKey	Pointer to public key. The public key (pubKeyLength) is a byte string representation of the keyblob, both version 1 and version 2 are supported: Version 1, begins with a 12-byte header, with all bytes set to zero except the following: header[7] contains the Digicert keyblob version (1) header[11] contains the key type (any of the akt_* enumerated values defined in ca_mgmt.h) For DSA keys, the data following the header is: 4 bytes length of p string n bytes length of p byte string 4 bytes length of q string n bytes length of q byte string 4 bytes length of g string n bytes length of g byte string 4 bytes length of y string n bytes length of y byte string 4 bytes length of x string n bytes length of x byte string For RSA keys, the data following the header is: 4 bytes length of e string n bytes length of e byte string 4 bytes length of n string n bytes length of n byte string 4 bytes length of p string n bytes length of p byte string 4 bytes length of q string n bytes length of q byte string 4 bytes length of private string #1 n bytes length of private byte string #1 4 bytes length of private string #2 n bytes length of private byte string #2 4 bytes length of private string #3 n bytes length of private byte string #3 4 bytes length of private string #4 n bytes length of private byte string #4 4 bytes length of private string #5 n bytes length of private byte string #5 For ECC keys, the data following the header is: 1 byte OID suffix identifying the curve 4 bytes length of Point string n bytes length of Point byte string (uncompressed X9-62 format) 4 bytes length of Scalar string n bytes length of Scalar byte string Version 2: 4 bytes: all zeroes 4 bytes: version number which must be 0x00000002 4 bytes: key type which must be one of the KEYBLOB_TYPE enums 4 bytes: OID type which must be one of the MAlgoOid enums n bytes: ASN.1 encoded algorithm identifier 4 bytes: reserved n bytes: reserved 4 bytes: key data length (keylen) keylen bytes: key data (key data formats are mentioned above)
pubKeyLength	Number of bytes in public key (pPubKey).
keyType	Type of public key (pPubKey). The following enumerated values (defined in ca_mgmt.h) are supported: akt_rsa akt_ecc akt_ecc_ed akt_dsa

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

funcPtrReleaseKeyIntReq

sbyte4(* sshSettings::funcPtrReleaseKeyIntReq) (sbyte4 connectionInstance, keyIntInfoReq *request)

This callback function is invoked during interactive keyboard authentication to release (free) unneeded request data.

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().
request	Pointer to request to free.

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

funcPtrSessionReKey

sbyte4(* sshSettings::funcPtrSessionReKey) (sbyte4 connectionInstance, intBoolean initiatedByRemote)

This callback function is invoked on rekey negotiation start (initiated locally or by remote) - allowing the application to take update session context.

Since

3.06

Version

3.06 and later

There are no flag dependencies to enable this callback.

Parameters

connectionInstance	Connection instance returned from SSHC_connect.
initiatedByRemote	True if the rekey was initiated by remote.

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.