Core (Async and Sync) Client Callbacks

Customizable asynchronous and synchronous NanoSSL client callbacks. More...

Variables
sbyte4(*	sslSettings::funcPtrChoosePSK )(sbyte4 connectionInstance, ubyte *pHintPSK, ubyte4 hintLength, ubyte retPskIdentity[SSL_PSK_SERVER_IDENTITY_LENGTH], ubyte4 *pRetPskIdentity, ubyte retPSK[SSL_PSK_MAX_LENGTH], ubyte4 *pRetLengthPSK)
	Retrieve (based on the provided hint) the chosen PSK, its identifying name, and their lengths. More...
sbyte4(*	sslSettings::funcPtrMutualAuthCertificateVerify )(sbyte4 connectionInstance, const ubyte *hash, ubyte4 hashLen, ubyte *result, ubyte4 resultLength)
	Compute the signature for a certificate verify message sent for client authentication. More...

Detailed Description

Variable Documentation

funcPtrChoosePSK

sbyte4(* sslSettings::funcPtrChoosePSK) (sbyte4 connectionInstance, ubyte *pHintPSK, ubyte4 hintLength, ubyte retPskIdentity[SSL_PSK_SERVER_IDENTITY_LENGTH], ubyte4 *pRetPskIdentity, ubyte retPSK[SSL_PSK_MAX_LENGTH], ubyte4 *pRetLengthPSK)

This callback function retrieves (based on the provided hint) the chosen PSK and its identifying name, as well as their lengths. A negative return status indicates that the session should be aborted.

Callback registration happens at session creation and initialization by assigning your custom callback function (which can have any name) to this callback pointer.

Note

If this function isn't defined, no hint can be returned to the client.

Since

1.41

Version

1.41 and later

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

• __ENABLE_MOCANA_SSL_PSK_SUPPORT__

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

• __ENABLE_MOCANA_SSL_CLIENT__
• __ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__

Parameters

connectionInstance	Pointer to the SSL/TLS Client instance.
pHintPSK	Pointer to buffer containing the PSK hint — a previously agreed on identifier which client and server use to look up the PSK.
hintLength	Number of bytes (excluding any terminating NULL) in pHintPSK.
retPskIdentity	On return, buffer containing the chosen PSK.
pRetPskIdentity	On return, pointer to number of bytes in chosen PSK (retPskIdentity).
retPSK	On return, buffer containing the chosen PSK's name.
pRetLengthPSK	On return, pointer to number of bytes in chosen PSK's name (retPSK).

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

You should define and customize this hookup function for your application if SSL is configured for PSK support.

ssl.h

funcPtrMutualAuthCertificateVerify

sbyte4(* sslSettings::funcPtrMutualAuthCertificateVerify) (sbyte4 connectionInstance, const ubyte *hash, ubyte4 hashLen, ubyte *result, ubyte4 resultLength)

This callback function is used by an ssl client when it needs to compute the content of a certificate verify message for mutual authentication.

Callback registration happens at session creation and initialization by assigning your custom callback function (which can have any name) to this callback pointer.

Since

3.2

Version

3.2 and later

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

• __ENABLE_MOCANA_SSL_MUTUAL_AUTH_SUPPORT__

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

• __ENABLE_MOCANA_SSL_CLIENT__
• __ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__

Parameters

connectionInstance	Pointer to the SSL/TLS client instance.
hash	Pointer to hash byte string.
hashLen	Number of bytes in the hash byte string (hash).
result	Pointer to the signature.
resultLength	Number of bytes in the signature buffer (result).

Returns

0 or a positive number if successful; for ECDSA signatures, the return value is the size of the signature (a DER encoded SEQUENCE); for RSA signatures, the return value has no additional significance. 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

You should define and customize this hookup function for your application if SSL is configured to use mutual authentication and the private key used for mutual authentication is not accessible (that is, it's provided by external hardware such as a smart card). Your implementation of this function must place the signature of the hash (of length hashLength) into this result buffer.

ssl.h