Customizable "Ungrouped" callbacks. More...

Functions
MOC_EXTERN MSTATUS	SSL_populateMutualAuthCertStore (sbyte4 connectionInstance, const SizedBuffer pCerts, ubyte4 numCerts, ubyte pKey, ubyte4 keyLen, const ubyte *pCACert, ubyte4 caCertLength)
	Function to populate the mutual auth cert store. More...

MOC_EXTERN MSTATUS	SSL_setAlertCallback (sbyte4 connectionInstance, sbyte4(*funcPtrAlertCallback)(sbyte4 connectionInstance, sbyte4 alertId, sbyte4 alertClass))
	Register an alert msg callback function. More...

MOC_EXTERN MSTATUS	SSL_setAlpnCallback (sbyte4 connectionInstance, sbyte4(funcPtrAlpnCallback)(sbyte4 connectionInstance, ubyte out[], sbyte4 outlen, ubyte *in, sbyte4 inlen))
	Register an Application Layer Protocol Negotiation callback. More...

MOC_EXTERN MSTATUS	SSL_setCertAndStatusCallback (sbyte4 connectionInstance, MSTATUS(funcPtrGetCertAndStatusCallback)(sbyte4 connectionInstance, struct certChain pCertChain, MSTATUS validationstatus))
	Provide Certificate and its validation status from the SSL stack. More...

MOC_EXTERN MSTATUS	SSL_setClientCertAuthorityCallback (sbyte4 connectionInstance, MSTATUS(funcPtrClientCertAuthorityCallback)(sbyte4 connectionInstance, SizedBuffer pCertAuthorities, ubyte4 certAuthorityCount))
	Provide certificate authorities to SSL stack for client. More...

MOC_EXTERN MSTATUS	SSL_setClientCertCallback (sbyte4 connInstance, MSTATUS(funcPtrClientCertCallback)(sbyte4 connInstance, SizedBuffer ppRetCert, ubyte4 pRetNumCerts, ubyte *ppRetKeyBlob, ubyte4 pRetKeyBlobLen, ubyte *ppRetCACert, ubyte4 pRetNumCACerts))
	Set Callback to request cert and key from the Application. More...

MOC_EXTERN MSTATUS	SSL_setInvalidCertCallback (sbyte4 connectionInstance, MSTATUS(*funcPtrInvalidCertCallback)(sbyte4 connectionInstance, MSTATUS validationstatus))
	Provide status to application when stack receives empty certificate. More...

MOC_EXTERN MSTATUS	SSL_setVersionCallback (sbyte4 connectionInstance, MSTATUS(*funcPtrVersionCallback)(ubyte4 serverVersion, ubyte4 clientVersion, MSTATUS sslStatus))
	Register a version callback to record the server version and client version. More...

Variables
sbyte4(*	sslSettings::funcPtrCertStatusCallback )(sbyte4 connectionInstance, intBoolean certStatus)

sbyte4(*	sslSettings::funcPtrChooseECCCurve )(sbyte4 connectionInstance, ubyte2 cipherSuiteID, const enum tlsExtNamedCurves pECCCurvesList, ubyte4 eccCurvesListLength, enum tlsExtNamedCurves selectedCurve)
	Specify the curve to use for this ECDHE or ECDH_ANON cipher suite. More...

sbyte4(*	sslSettings::funcPtrSingleCertStatusCallback )(sbyte4 connectionInstance, const ubyte pCert, ubyte4 certLen, ubyte pOcspResp, ubyte4 ocspRespLen, sbyte4 ocspStatus)

sbyte4(*	sslSettings::funcPtrSRPCallback )(sbyte4 connectionInstance, const ubyte identity, ubyte4 identityLength, sbyte4 numBits, ubyte salt[SSL_PSK_SERVER_IDENTITY_LENGTH], ubyte4 saltLength, ubyte verifier, ubyte4 verifierLength)
	Specify the SRP parameters for the given identity. More...

Detailed Description

Function Documentation

◆ SSL_populateMutualAuthCertStore()

MOC_EXTERN MSTATUS SSL_populateMutualAuthCertStore	(	sbyte4	connectionInstance,
		const SizedBuffer *	pCerts,
		ubyte4	numCerts,
		ubyte *	pKey,
		ubyte4	keyLen,
		const ubyte *	pCACert,
		ubyte4	caCertLength
	)

This function lets you populate the Mutual Auth Cert Store with the give Certificate, Key and CA. This internal cert store is used by client in mutual auth case, if it is not able to select a certificate from the global cert store. This mutual auth cert store is per session, and valid as long as the session is alive.

Since

Version

Enabled by default. To disable, define tthe following flag in moptions.h +__DISABLE_MOCANA_SSL_CLIENT__ +__DISABLE_MOCANA_SSL_MUTUAL_AUTH_SUPPORT__

Parameters

connectionInstance	Connection instance returned from SSL_connect().
pCerts	Certificate to add to cert store (in der format).
numCerts	Number of certificates in the buffer.
pKey	Corresponding key.
keyLen	Length of the key.
pCACerts	Buffer of CA Certs
caCertLength	Length of the CA Cert Buffer
funcPtrGetCertAndStatusCallback	Function pointer to a valid function which provides certificate and key.

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

ssl.h

◆ SSL_setAlertCallback()

MOC_EXTERN MSTATUS SSL_setAlertCallback	(	sbyte4	connectionInstance,
		sbyte4(*)(sbyte4 connectionInstance, sbyte4 alertId, sbyte4 alertClass)	funcPtrAlertCallback
	)

This function lets you register an application-defined alert msg callback

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

__ENABLE_MOCANA_SSL_ALERTS__

Parameters

connectionInstance	Connection instance returned from SSL_connect().
funcPtrAlerCallback	Function pointer to a valid Alert callback function.

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

Remarks: This callback function is applicable to asynchronous and synchronous clients and servers.

◆ SSL_setAlpnCallback()

MOC_EXTERN MSTATUS SSL_setAlpnCallback	(	sbyte4	connectionInstance,
		sbyte4()(sbyte4 connectionInstance, ubyte out[], sbyte4 outlen, ubyte *in, sbyte4 inlen)	funcPtrAlpnCallback
	)

This function lets you register an application-defined callback

Since: 6.5

Version: 6.5 and later

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

__ENABLE_MOCANA_SSL_SERVER__
__ENABLE_MOCANA_SSL_CLIENT__

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

__DISABLE_MOCANA_ALPN_CALLBACK__

Parameters

connectionInstance	Connection instance returned from SSL_connect().
funcPtrAlpnCallback	Function pointer to a valid ALPN callback function.

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

Remarks: This callback function is applicable to asynchronous and synchronous clients and servers.

◆ SSL_setCertAndStatusCallback()

MOC_EXTERN MSTATUS SSL_setCertAndStatusCallback	(	sbyte4	connectionInstance,
		MSTATUS()(sbyte4 connectionInstance, struct certChain pCertChain, MSTATUS validationstatus)	funcPtrGetCertAndStatusCallback
	)

This function lets you register an application-defined function, which provides the application with the certificate used and its validation status. Application can perform additional checks on the certificate and can override the SSL stack's validation.

Since

Version

Enabled by default. To disable, define tthe following flag in moptions.h +__DISABLE_MOCANA_SSL_CERTIFICATE_CALLBACK__

Parameters

connectionInstance	Connection instance returned from SSL_connect().
funcPtrGetCertAndStatusCallback	Function pointer to a valid function which handles further certificate processing.
validationstatus	Status returned by the SSL Stack's certificate validation steps.

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

Remarks: This callback function is applicable to synchronous and asynchronous clients and servers. The function pointer passed as an argument provides the application with the certificate used and the SSL stack's validation status. The application can then perform additional checks on the certificate and optionally override the SSL stack's validation. The implementation of this function should return OK, to indicate that the certificate is valid irrespective of the SSL stack's status. The application can choose to accept the status proposed by the SSL stack. If application needs to store/modify the certificate, it should make a copy of the certificate.

ssl.h

◆ SSL_setClientCertAuthorityCallback()

MOC_EXTERN MSTATUS SSL_setClientCertAuthorityCallback	(	sbyte4	connectionInstance,
		MSTATUS()(sbyte4 connectionInstance, SizedBuffer pCertAuthorities, ubyte4 certAuthorityCount)	funcPtrClientCertAuthorityCallback
	)

This function lets you register an application-defined function, which provides the application with the certificate authorities provided in a certificate request message.

Since

Version

Enabled by default. To disable, define tthe following flag in moptions.h +__DISABLE_MOCANA_SSL_CLIENT__ +__DISABLE_MOCANA_SSL_MUTUAL_AUTH_SUPPORT__ +__DISABLE_MOCANA_SSL_CERTIFICATE_CALLBACK__

Parameters

connectionInstance	Connection instance returned from SSL_connect().
funcPtrClientCertAuthorityCallback	Function pointer to a valid function which handles the certificate authorities extension.

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

Remarks: This callback function is applicable to synchronous and asynchronous clients and servers. The function pointer passed as an argument provides the application with a SizedBuffer of certificate authorities.

ssl.h

◆ SSL_setClientCertCallback()

MOC_EXTERN MSTATUS SSL_setClientCertCallback	(	sbyte4	connInstance,
		MSTATUS()(sbyte4 connInstance, SizedBuffer ppRetCert, ubyte4 pRetNumCerts, ubyte *ppRetKeyBlob, ubyte4 pRetKeyBlobLen, ubyte *ppRetCACert, ubyte4 pRetNumCACerts)	funcPtrClientCertCallback
	)

This function lets you register an application-defined function, which provides the certificate and key to be used for a connection. This operation is performed during the handshake if ther certstore is not initialized or a suitable certificate is not found in the certstore. This API can only be used by Client Application.

Since

Version

Enabled by default. To disable, define tthe following flag in moptions.h +__DISABLE_MOCANA_SSL_CLIENT__ +__DISABLE_MOCANA_SSL_MUTUAL_AUTH_SUPPORT__

Parameters

connectionInstance	Connection instance returned from SSL_connect().
funcPtrClientCertCallback	Function pointer to a valid function which provides certificate and key.

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

Remarks: This callback function is applicable to synchronous and asynchronous clients. The function pointer passed as an argument provides a mechianish for the application to provide a cert and key for a given connection during the handshake. The implementation of this function should return OK and populate Cert and Key to be used by the SSL stack. The memory fo the cert and key is freed by the SSL stack.

ssl.h

◆ SSL_setInvalidCertCallback()

MOC_EXTERN MSTATUS SSL_setInvalidCertCallback	(	sbyte4	connectionInstance,
		MSTATUS(*)(sbyte4 connectionInstance, MSTATUS validationstatus)	funcPtrInvalidCertCallback
	)

This function lets you register an application-defined function, which provides the application option to accept an empty certificate sent by the client in reponse to certificate request message from the server.

Since

Version

To enable define the following fla in moptions.h +__ENABLE_MOCANA_SSL_INVALID_CERTIFICATE_CALLBACK__

Parameters

connectionInstance	Connection instance returned from SSL_connect().
funcPtrInvalidCertCallback	Function pointer to a valid function which handles further invalid certificate processing.

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

Remarks: This callback function is applicable to synchronous and asynchronous clients and servers. The application can choose whether to accept and optionally override the SSL stack's status. The implementation of this function should return OK, to indicate that the empty certificate is valid irrespective of the SSL stack's status. The application can choose to accept the status given by the SSL stack and throw out an error. return status >= 0; Ignore Invalid Certificate Error return status < 0; Process the error

ssl.h

◆ SSL_setVersionCallback()

MOC_EXTERN MSTATUS SSL_setVersionCallback	(	sbyte4	connectionInstance,
		MSTATUS(*)(ubyte4 serverVersion, ubyte4 clientVersion, MSTATUS sslStatus)	funcPtrVersionCallback
	)

This function allows the caller register a version callback which will be called during the SSL handshake process. The version callback will be called on the server side during the processing of the client hello message. The client will call the callback during the processing of the server hello message. Note that the return value of the callback does not affect how the client/server negotiates the version to use during a SSL handshake. This callback is primarily for logging the server version and client version during a SSL handshake.

Since

Version

Enabled by default.

Parameters

connectionInstance	Connection instance returned from SSL_connect().
funcPtrVersionCallback	Function pointer to a version callback.

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

ssl.h

Variable Documentation

◆ funcPtrCertStatusCallback

sbyte4(* sslSettings::funcPtrCertStatusCallback) (sbyte4 connectionInstance, intBoolean certStatus)

OCSP callback for TLS 1.2 to check for OCSP status extension.

This callback is invoked by TLS 1.2 Client. The callback alerts the application of whether or not the server has sent the OCSP extension.

Parameters

connectionInstance	Pointer to the SSL/TLS Client instance.
certStatus	`TRUE` is the server has provided an OCSP extension, otherwise `FALSE`.

Returns: OK (0) if the application wants to proceed with the connection; otherwise a negative number error code definition from merrors.h can be returned to terminate the connection.

◆ funcPtrChooseECCCurve

sbyte4(* sslSettings::funcPtrChooseECCCurve) (sbyte4 connectionInstance, ubyte2 cipherSuiteID, const enum tlsExtNamedCurves *pECCCurvesList, ubyte4 eccCurvesListLength, enum tlsExtNamedCurves *selectedCurve)

This callback lets you specify the curve to use for this ECDHE or ECDH_ANON cipher suite. Using this callback is optional. If it's not specified, the curve will be selected according to the global array gSupportedNamedGroup.

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

(is this for sync and/or async, client and/or server?)

Since: 5.5

Version: 5.5 and later

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

__ENABLE_MOCANA_SSL_SERVER__

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

__ENABLE_MOCANA_SSL_ECDHE_SUPPORT__
__ENABLE_MOCANA_SSL_ECDH_ANON_SUPPORT__

Parameters

connectionInstance	Pointer to the SSL/TLS Client instance.
cipherSuiteID	Identifier for the cipher suite. Values are as specified per RFC 4346 for the TLS Cipher Suite Registry; refer to the following Web page: http://www.iana.org/assignments/tls-parameters .
pECCCurvesList	List of ECC curves that can be possibly selected. This is the intersection of curves supported by both the client and the server.
eccCurvesListLength	Number of entries in PSK identity (`pIdentityPSK`).
selectedCurveIndex	On return, the curve to use for the key exchange.

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: Your implementation can return an error if the pECCCurvesList does not contain any appropriate curve. This could occur if the client does not support the minimum level of security you require for that cipher suite.

ssl.h

◆ funcPtrSingleCertStatusCallback

sbyte4(* sslSettings::funcPtrSingleCertStatusCallback) (sbyte4 connectionInstance, const ubyte *pCert, ubyte4 certLen, ubyte *pOcspResp, ubyte4 ocspRespLen, sbyte4 ocspStatus)

OCSP callback invoked during OCSP message processing.

This callback is invoked by the client or server after an OCSP message is processed. The application may decide to proceed or terminate the connection based on the provided certificate, OCSP message, and OCSP status.

Parameters

connectionInstance	Pointer to the SSL/TLS Client instance.
pCert	Pointer to the certificate for which the OCSP message is intended for.
certLen	Length of the certificate.
pOcspResp	Pointer to the OCSP message provided by the peer.
ocspRespLen	Length of the OCSP message.
ocspStatus	Status returned by NanoSSL when validating the OCSP message. `OK` (0) if successful; otherwise a negative number error code definition from merrors.h.

Returns: OK (0) if the application wants to proceed with the connection; otherwise a negative number error code definition from merrors.h can be returned to terminate the connection.

◆ funcPtrSRPCallback

sbyte4(* sslSettings::funcPtrSRPCallback) (sbyte4 connectionInstance, const ubyte *identity, ubyte4 identityLength, sbyte4 *numBits, ubyte salt[SSL_PSK_SERVER_IDENTITY_LENGTH], ubyte4 *saltLength, ubyte **verifier, ubyte4 *verifierLength)

This callback lets you specify the SRP salt and verifier for the specified identity.

: async/sync, server only

Since: 6.5

Version: 6.5 and later

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

__ENABLE_MOCANA_SSL_SERVER__
__ENABLE_MOCANA_SSL_SRP__

Parameters

connectionInstance	Pointer to the SSL/TLS Client instance.
identity	Pointer to the identity
identityLength	Length in bytes of identity
numBits	number of bits for the SRP operation Your function should return a number from the set 1024, 1536, 2048, 3172, 4096, 6144, 8192. Some of these values might be invalid based on the value of the compile time defined flag MOCANA_MIN_SRP_BITS Consult RFC 5054 for further information about these values.
salt	Salt used when computing the verifier.
saltLength	Length in bytes of salt.
verifier	Verifier for the identity.
verifierLength	Length in bytes of verifier.

Returns: OK (0) if successful; A non zero value may be returned to indicate an error.

Remarks: Your implementation of this function should return the number of bits, the salt and the verifier for a given identity. If the identity is not know, the TLS server will generate random values for this to prevent leaking information about the valid user names. The buffer verifier should be allocated with MALLOC by your implementation of this function. This buffers will be FREE'ed by the SSL stack.

ssl.h

Functions

Variables

Detailed Description

Function Documentation

◆ SSL_populateMutualAuthCertStore()

◆ SSL_setAlertCallback()

◆ SSL_setAlpnCallback()

◆ SSL_setCertAndStatusCallback()

◆ SSL_setClientCertAuthorityCallback()

◆ SSL_setClientCertCallback()

◆ SSL_setInvalidCertCallback()

◆ SSL_setVersionCallback()

Variable Documentation

◆ funcPtrCertStatusCallback

◆ funcPtrChooseECCCurve

◆ funcPtrSingleCertStatusCallback

◆ funcPtrSRPCallback