Core functions required by both asynchronous and synchronous NanoSSL clients and servers. More...

Functions
MOC_EXTERN sbyte4	DTLS_isTimerExpired (sbyte4 connectionInstance)
	Check if DTLS timer has expired. More...

MOC_EXTERN sbyte4	SSL_checkFIPS ()
	Check if FIPS library is loaded correctly. More...

MOC_EXTERN sbyte4	SSL_disableCipherHashAlgorithm (sbyte4 connectionInstance, TLS_HashAlgorithm hashId)
	Disable ciphers using the specified hash algorithm (and lower). More...

MOC_EXTERN sbyte4	SSL_DTLS_getTimeout (sbyte4 connectionInstance, void *pTime)
	Get the time remaing until DTLS timeout. More...

MOC_EXTERN sbyte4	SSL_enableCiphers (sbyte4 connectionInstance, const ubyte2 *pCipherSuiteList, ubyte4 listLength)
	Enable specified ciphers. More...

MOC_EXTERN sbyte4	SSL_enableECCCurves (sbyte4 connectionInstance, enum tlsExtNamedCurves *pECCCurvesList, ubyte4 listLength)
	Enable ECC curves. More...

MOC_EXTERN sbyte4	SSL_generateEarlyExportKeyMaterial (sbyte4 connectionInstance, ubyte pKey, ubyte2 keyLen, ubyte pLabel, ubyte2 labelLen, ubyte *pContext, ubyte4 contextLen)
	Generate export keying material based on the early exporter master secret, label, and context. More...

MOC_EXTERN sbyte4	SSL_generateExportKeyMaterial (sbyte4 connectionInstance, ubyte pKey, ubyte2 keyLen, ubyte pKeyphrase, ubyte2 keyPhrase, ubyte *pContext, ubyte2 contextLen, int useContext)
	Generate the export key material with the given label and context for a connection. More...

MOC_EXTERN sbyte4	SSL_getCipherInfo (sbyte4 connectionInstance, ubyte2 pCipherId, ubyte4 pPeerEcCurves)
	Get a connection's ciphers and ecCurves. More...

MOC_EXTERN sbyte4	SSL_getCipherList (sbyte4 connectionInstance, ubyte2 *ppCipherIdList, ubyte4 pCount)
	Get the enabled ciphers. More...

MOC_EXTERN sbyte4	SSL_getCookie (sbyte4 connectionInstance, void **pCookie)
	Get custom information for a connection instance. More...

MOC_EXTERN sbyte4	SSL_getInstanceFromSocket (TCP_SOCKET socket)
	Get a socket's connection instance. More...

MOC_EXTERN sbyte4	SSL_getSessionFlags (sbyte4 connectionInstance, ubyte4 *pRetFlagsSSL)
	Get a connection's context (its flags). More...

MOC_EXTERN sbyte4	SSL_getSessionStatus (sbyte4 connectionInstance, ubyte4 *pRetStatusSSL)
	Get a connection's status. More...

MOC_EXTERN sbyte4	SSL_getSocketId (sbyte4 connectionInstance, TCP_SOCKET *pRetSocket)
	Get a connection's socket identifier. More...

MOC_EXTERN sbyte4	SSL_initiateRehandshake (sbyte4 connectionInstance)
	Renegotiate an SSL/TLS session. More...

MOC_EXTERN sbyte4	SSL_ioctl (sbyte4 connectionInstance, ubyte4 setting, void *value)
	Enable dynamic management of a connection's features. More...

MOC_EXTERN sbyte4	SSL_isSessionDTLS (sbyte4 connectionInstance)
	Determine whether a connection instance represents a DTLS server, a DTLS client, or an unrecognized connection (for example, SSH). More...

MOC_EXTERN sbyte4	SSL_isSessionSSL (sbyte4 connectionInstance)
	Determine whether a connection instance represents an SSL/TLS server, an SSL/TLS client, or an unrecognized connection (for example, SSH). More...

MOC_EXTERN sbyte4	SSL_lookupAlert (sbyte4 connectionInstance, sbyte4 lookupError, sbyte4 pRetAlertId, sbyte4 pAlertClass)
	Get the SSL alert code for a Mocana error. More...

MOC_EXTERN sbyte4	SSL_releaseTables (void)
	Release memory used by internal SSL/TLS memory tables. More...

MOC_EXTERN sbyte4	SSL_sendAlert (sbyte4 connectionInstance, sbyte4 alertId, sbyte4 alertClass)
	Send an SSL alert message to an SSL peer. More...

MOC_EXTERN MSTATUS	SSL_setCipherAlgorithm (sbyte4 connectionInstance, ubyte2 *pList, ubyte4 listLength, ubyte4 listType)
	Set cipher, supported Groups and signature algorithm. More...

MOC_EXTERN sbyte4	SSL_setCookie (sbyte4 connectionInstance, void *cookie)
	Store custom information for a connection instance. More...

MOC_EXTERN sbyte4	SSL_setDHParameters (ubyte pP, ubyte4 pLen, ubyte pG, ubyte4 gLen, ubyte4 lengthY)
	Set the DH parameters to use during the SSL connection. More...

MOC_EXTERN sbyte4	SSL_setDSACiphers (sbyte4 connectionInstance, ubyte enableDSACiphers)
	Enable/disable DSA ciphers. More...

MOC_EXTERN sbyte4	SSL_setFIPSEnabled (ubyte isFIPSEnabled)
	Enable FIPS at runtime. More...

MOC_EXTERN sbyte4	SSL_setMinRSAKeySize (ubyte4 keySize)
	Set the minimum RSA Key Size. More...

MOC_EXTERN sbyte4	SSL_setSessionFlags (sbyte4 connectionInstance, ubyte4 flagsSSL)
	Store a connection's context (its flags). More...

MOC_EXTERN sbyte4	SSL_setSha1SigAlg (intBoolean setting)
	Dynamically set support for SHA-1 signature algorithms,. More...

MOC_EXTERN sbyte4	SSL_Settings_Ioctl (ubyte4 setting, void *value)
	Enable dynamic management of a connection's features. More...

MOC_EXTERN sbyte4	SSL_shutdownStack (void)
	Clean up memory and mutexes and shut down the SSL stack. More...

MOC_EXTERN sslSettings *	SSL_sslSettings (void)
	Get a pointer to current context's configuration settings. More...

Detailed Description

See also: Asynchronous Client Functions; Asynchronous Client and Server Functions; Asynchronous Server Functions; Synchronous Client Functions; Synchronous Client and Server Functions; Synchronous Server Functions

Function Documentation

◆ DTLS_isTimerExpired()

MOC_EXTERN sbyte4 DTLS_isTimerExpired ( sbyte4 connectionInstance )

This function checks if the current DTLS timer has expired.

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

__ENABLE_MOCANA_SSL_CLIENT__
__ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__
__ENABLE_MOCANA_SSL_SERVER__
__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__

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

__ENABLE_MOCANA_DTLS_SERVER__
__ENABLE_MOCANA_DTLS_CLIENT__
__ENABLE_MOCANA_DTLS_EXT_API__
__ENABLE_MOCANA_OPENSSL_SHIM__

ssl.h

Parameters

connectionInstance Connection instance returned from DTLS_connect().

Returns: 0 if timer has NOT expired/there is no timer. -1 if timer has expired.

ssl.c

◆ SSL_checkFIPS()

MOC_EXTERN sbyte4 SSL_checkFIPS ( )

This function checks if FIPS library is loaded correctly.

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_SSL_FIPS__

ssl.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 clients and servers.

ssl.c

◆ SSL_disableCipherHashAlgorithm()

MOC_EXTERN sbyte4 SSL_disableCipherHashAlgorithm	(	sbyte4	connectionInstance,
		TLS_HashAlgorithm	hashId
	)

This function dynamically disables cipher algorithms with the specified digest or lower. This function should be invoked after SSL_enableCiphers(). This will ensure that weak or disabled digest(s) based ciphers do not get reenabled.

The function must not be called before a connection is established (see SSL_connect() for synchronous clients, SSL_ASYNC_connect() for asynchronous clients), but must be called before SSL_negotiateConnection() (for either synchronous or asynchronous clients).

Since: 1.41

Version: 1.41 and later

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

__ENABLE_MOCANA_SSL_CIPHER_SUITES_SELECT__

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

__ENABLE_MOCANA_SSL_CLIENT__
__ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__
__ENABLE_MOCANA_SSL_SERVER__
__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__

ssl.h

Parameters

connectionInstance	Connection instance returned from SSL_connect().
hashId	Hash enumeration available in crypto.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 clients and servers.

ssl.c

◆ SSL_DTLS_getTimeout()

MOC_EXTERN sbyte4 SSL_DTLS_getTimeout	(	sbyte4	connectionInstance,
		void *	pTime
	)

This function returns the time remaining to timeout in the format of struct timeval.

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

__ENABLE_MOCANA_SSL_CLIENT__
__ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__
__ENABLE_MOCANA_SSL_SERVER__
__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__

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

__ENABLE_MOCANA_DTLS_SERVER__
__ENABLE_MOCANA_DTLS_CLIENT__
__ENABLE_MOCANA_DTLS_EXT_API__
__ENABLE_MOCANA_OPENSSL_SHIM__

ssl.h

Parameters

connectionInstance	Connection instance returned from DTLS_connect().
pTime	A pointer to the structure timeval. This structure is populated with the time remaining.

Returns: 0 if successful, negative number for errors

ssl.c

◆ SSL_enableCiphers()

MOC_EXTERN sbyte4 SSL_enableCiphers	(	sbyte4	connectionInstance,
		const ubyte2 *	pCipherSuiteList,
		ubyte4	listLength
	)

This function dynamically enables just those ciphers that are specified in the function call. If none of the specified ciphers match those supported by NanoSSL client/server and enabled in your implementation, an error is returned.

The function must not be called before a connection is established (see SSL_connect() for synchronous clients, SSL_ASYNC_connect() for asynchronous clients), but must be called before SSL_negotiateConnection() (for either synchronous or asynchronous clients).

Since: 1.41

Version: 1.41 and later

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

__ENABLE_MOCANA_SSL_CIPHER_SUITES_SELECT__

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

__ENABLE_MOCANA_SSL_CLIENT__
__ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__
__ENABLE_MOCANA_SSL_SERVER__
__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__

ssl.h

Parameters

connectionInstance	Connection instance returned from SSL_connect().
pCipherSuiteList	Pointer to value (or array of values) representing the desired cipher ID(s). 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 .
listLength	Number of entries in `pCipherSuiteList`.

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 clients and servers.

ssl.c

◆ SSL_enableECCCurves()

MOC_EXTERN sbyte4 SSL_enableECCCurves	(	sbyte4	connectionInstance,
		enum tlsExtNamedCurves *	pECCCurvesList,
		ubyte4	listLength
	)

This function dynamically enables ECC curves that are specified in the function call. If none of the specified curves match those supported by NanoSSL client/server and enabled in your implementation, an error is returned.

The function must not be called before a connection is established (see SSL_connect() for synchronous clients, SSL_ASYNC_connect() for asynchronous clients), but must be called before SSL_negotiateConnection() (for either synchronous or asynchronous clients).

Since: 1.41

Version: 1.41 and later

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

__ENABLE_MOCANA_SSL_CIPHER_SUITES_SELECT__

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

__ENABLE_MOCANA_SSL_ECDH_SUPPORT__
__ENABLE_MOCANA_SSL_ECDHE_SUPPORT__
__ENABLE_MOCANA_SSL_ECDH_ANON_SUPPORT__
__ENABLE_MOCANA_SSL_CLIENT__
__ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__
__ENABLE_MOCANA_SSL_SERVER__
__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__

ssl.h

Parameters

connectionInstance	Connection instance returned from SSL_connect().
pECCCurvesList	Pointer to value (or array of values) representing the desired ECC curves.
listLength	Number of entries in `pECCCurvesList`.

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 clients and servers.

ssl.c

◆ SSL_generateEarlyExportKeyMaterial()

MOC_EXTERN sbyte4 SSL_generateEarlyExportKeyMaterial	(	sbyte4	connectionInstance,
		ubyte *	pKey,
		ubyte2	keyLen,
		ubyte *	pLabel,
		ubyte2	labelLen,
		ubyte *	pContext,
		ubyte4	contextLen
	)

The label and optional context are provided by the caller.

This function will allow the caller to generate key material based on the early exporter master secret. The caller must pass in a label and an optional context. Applications will typically use this API to get their own keying material when performing 0-RTT. If 0-RTT is not being performed then it is recommended to get keying material from SSL_generateExportKeyMaterial. Refer to RFC 8446 and RFC 5705 on how to properly use exporters. This function is only available for TLS 1.3.

Since

Version

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

__ENABLE_MOCANA_SSL_KEY_EXPANSION__ ssl.h

Parameters

connectionInstance	Connection instance returned from SSL_connect().
pKey	Buffer where key material is returned.
keyLen	Length in bytes of how much key material to generate.
pLabel	Label string. This string cannot be NULL terminated.
labelLen	The length of the label string.
pContext	Optional context.
contextLen	Length of the context.

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.

ssl.c

◆ SSL_generateExportKeyMaterial()

MOC_EXTERN sbyte4 SSL_generateExportKeyMaterial	(	sbyte4	connectionInstance,
		ubyte *	pKey,
		ubyte2	keyLen,
		ubyte *	pKeyphrase,
		ubyte2	keyPhrase,
		ubyte *	pContext,
		ubyte2	contextLen,
		int	useContext
	)

This function will allow the caller to generate and get a export key. User can specify the label and context (otional) to be used to generate this export key.

Since

Version

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

__ENABLE_MOCANA_SSL_KEY_EXPANSION__ ssl.h

Parameters

connectionInstance	Connection instance returned from SSL_connect().
pKey	Export key returned.
keyLen	Key lenght.
pKeyPhrase	label to be used.
keyPhraseLen	label length.
pContext	Context to be used when generating the key.
contextLen	Length of context.
useContext	If this flag is set to 1, 0 length context is appended even if context length is 0 and pContext is NULL

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.

ssl.c

◆ SSL_getCipherInfo()

MOC_EXTERN sbyte4 SSL_getCipherInfo	(	sbyte4	connectionInstance,
		ubyte2 *	pCipherId,
		ubyte4 *	pPeerEcCurves
	)

This function retrieves the specified connection's cipher and ecCurves.

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_SSL_CLIENT__
__ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__
__ENABLE_MOCANA_SSL_SERVER__
__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__

ssl.h

Parameters

connectionInstance	Connection instance returned from SSL_connect().
pCipherId	On return, pointer to the connection's cipher value.
pPeerEcCurves	On return, pointer to the connection's supported ecCurves values (as a bit field built by OR-ing together shift-left combinations of bits shifted by the value of `tlsExtNamedCurves` enumerations).

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 clients and servers.

ssl.c

◆ SSL_getCipherList()

MOC_EXTERN sbyte4 SSL_getCipherList	(	sbyte4	connectionInstance,
		ubyte2 **	ppCipherIdList,
		ubyte4 *	pCount
	)

This functions returns the list of CipherIds enabled for the corresponding connection.

The function must not be called before a connection is established (see SSL_connect() for synchronous clients, SSL_ASYNC_connect() for asynchronous clients), but must be called before SSL_negotiateConnection() (for either synchronous or asynchronous clients).

Since: 1.41

Version: 1.41 and later

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

__ENABLE_MOCANA_SSL_CIPHER_SUITES_SELECT__

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

__ENABLE_MOCANA_SSL_CLIENT__
__ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__
__ENABLE_MOCANA_SSL_SERVER__
__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__

ssl.h

Parameters

connectionInstance	Connection instance returned from SSL_connect().
ppCipherIdList	Pointer to an empty array which will be filled by the API which contains the cipherIds of the enabled ciphers. Memory is allocated by the API, memory should be freed by the application.
pCount	Number of entries in `ppCipherIdList`.

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 clients and servers.

ssl.c

◆ SSL_getCookie()

MOC_EXTERN sbyte4 SSL_getCookie	(	sbyte4	connectionInstance,
		void **	pCookie
	)

This function retrieves custom information stored in the connection instance's context. Your application should not call this function until after calls to SSL_setCookie().

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_SSL_CLIENT__
__ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__
__ENABLE_MOCANA_SSL_SERVER__
__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__

ssl.h

Parameters

connectionInstance	Connection instance returned from SSL_connect().
pCookie	On return, pointer to the cookie containing the context's custom information.

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

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.

mySessionInfo *myCookie = NULL;
SSL_getCookie(connectionInstance, (int *)(&myCookie));

ssl.c

◆ SSL_getInstanceFromSocket()

MOC_EXTERN sbyte4 SSL_getInstanceFromSocket ( TCP_SOCKET socket )

This function returns a connection instance for the specified socket identifier. The connection instance can be used as a parameter in subsequent calls to NanoSSL client and server functions. This function is not applicable to ASYNC mode of operation where the socket descriptor is not managed by (or known) to the SSL layer

Since: 1.41

Version: 3.06 and later

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

__ENABLE_MOCANA_SSL_CLIENT__
__ENABLE_MOCANA_SSL_SERVER__

ssl.h

Parameters

socket TCP/IP socket for which you want to retrieve a connection instance.

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 clients and servers.

sbyte4 connectionInstance;
TCP_SOCKET socketClient;
connectionInstance = SSL_getInstanceFromSocket(socketClient);

ssl.c

◆ SSL_getSessionFlags()

MOC_EXTERN sbyte4 SSL_getSessionFlags	(	sbyte4	connectionInstance,
		ubyte4 *	pRetFlagsSSL
	)

This function returns a connection's context — its flags. Your application can call this function any time after it calls SSL_connect().

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_SSL_CLIENT__
__ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__
__ENABLE_MOCANA_SSL_SERVER__
__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__

Additionally, the following flag must not be defined:

__DISABLE_SSL_SESSION_FLAGS_API__

ssl.h

Parameters

connectionInstance	Connection instance returned from SSL_connect().
pRetFlagsSSL	Pointer to the connection's flags, which have been set by SSL_setSessionFlags.

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 clients and servers.

ssl.c

◆ SSL_getSessionStatus()

MOC_EXTERN sbyte4 SSL_getSessionStatus	(	sbyte4	connectionInstance,
		ubyte4 *	pRetStatusSSL
	)

This function returns a connection's status: SSL_CONNECTION_OPEN or SSL_CONNECTION_NEGOTIATE.

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_SSL_CLIENT__
__ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__
__ENABLE_MOCANA_SSL_SERVER__
__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__

ssl.h

Parameters

connectionInstance	Connection instance returned from SSL_connect().
pRetStatusSSL	On successful return, session's current status: `SSL_CONNECTION_OPEN` or `SSL_CONNECTION_NEGOTIATE`.

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 clients and servers.

ssl.c

◆ SSL_getSocketId()

MOC_EXTERN sbyte4 SSL_getSocketId	(	sbyte4	connectionInstance,
		TCP_SOCKET *	pRetSocket
	)

This function returns the socket identifier for the specified connection instance.

Since: 1.41

Version: 3.06 and later

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

__ENABLE_MOCANA_SSL_CLIENT__
__ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__
__ENABLE_MOCANA_SSL_SERVER__
__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__

Additionally, the following flags must not be defined:

__DISABLE_SSL_GET_SOCKET_API__
__ENABLE_MOCANA_DTLS_SERVER__
__ENABLE_MOCANA_DTLS_CLIENT__

ssl.h

Parameters

connectionInstance	Connection instance returned from SSL_connect().
pRetSocket	On return, pointer to the socket corresponding to the connection instance.

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 clients and servers.

ssl.c

◆ SSL_initiateRehandshake()

MOC_EXTERN sbyte4 SSL_initiateRehandshake ( sbyte4 connectionInstance )

This function renegotiates a client or server SSL session. Renegotiation can be necessary in a variety of circumstances, including:

Reducing attack vulnerability after a connection has been active for a long time
Enhancing security by using stronger encryption
Performing mutual authentication

The peer can ignore the rehandshake request or send back an SSL_ALERT_NO_RENEGOTIATION alert.

Since: 2.45

Version: 2.45 and later

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

__ENABLE_MOCANA_SSL_REHANDSHAKE__

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

__ENABLE_MOCANA_SSL_CLIENT__
__ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__
__ENABLE_MOCANA_SSL_SERVER__
__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__

ssl.h

Parameters

connectionInstance Connection instance returned from SSL_connect().

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.

ssl.c

◆ SSL_ioctl()

MOC_EXTERN sbyte4 SSL_ioctl	(	sbyte4	connectionInstance,
		ubyte4	setting,
		void *	value
	)

This function enables dynamic management (enabling and disabling) of selected features for a specific SSL session's connection instance. (The initial value for these settings is defined in ssl.h.)

You can dynamically alter whether SSLv3, TLS 1.0, or TLS 1.1 is used by calling this function for the SSL_SET_VERSION feature flag setting with any of the following values:

0 — Use SSLv3
1 — Use TLS 1.0
2 — Use TLS 1.1
3 — Use TLS 1.2

Since: 1.41

Version: 3.06 and later

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

__ENABLE_MOCANA_SSL_CLIENT__
__ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__
__ENABLE_MOCANA_SSL_SERVER__
__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__

Additionally, the following flag must not be defined:

__DISABLE_SSL_IOCTL_API__

ssl.h

Parameters

connectionInstance	Connection instance returned from SSL_connect().
setting	SSL feature flag to dynamically alter; see SSL runtime flag definitions (`SSL_FLAG_*`) in ssl.h.
value	Value to assign to the `setting` flag. Pass the value as a variable (eg : (void)1) for the following settings: setting : SSL_SET_VERSION setting : SSL_SET_MINIMUM_VERSION setting : SSL_SET_SCSV_VERSION setting : DTLS_SET_HANDSHAKE_RETRANSMISSION_TIMER setting : DTLS_SET_PMTU setting : DTLS_SET_HELLO_VERIFIED Pass the pointer to a variable for the following settings (eg : (void)&value): setting : DTLS_USE_SRTP

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 clients and servers.

ssl.c

◆ SSL_isSessionDTLS()

MOC_EXTERN sbyte4 SSL_isSessionDTLS ( sbyte4 connectionInstance )

This function determines whether a given connection instance represents a DTLS server, a DTLS client, or an unrecognized connection (for example, SSH). The returned value will be one of the following:

0 — Indicates an DTLS server connection
1 — Indicates an DTLS client connection
Negative number — Indicates an unknown connection type

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_SSL_CLIENT__
__ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__
__ENABLE_MOCANA_SSL_SERVER__
__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__

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

__ENABLE_MOCANA_DTLS_SERVER__
__ENABLE_MOCANA_DTLS_CLIENT__

ssl.h

Parameters

connectionInstance Connection instance returned from DTLS_connect().

Returns: 0 if the connection instance is a DTLS server; 1 if an DTLS client; negative number if an unrecognized connection.

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

ssl.c

◆ SSL_isSessionSSL()

MOC_EXTERN sbyte4 SSL_isSessionSSL ( sbyte4 connectionInstance )

This function determines whether a given connection instance represents an SSL/TLS server, an SSL/TLS client, or an unrecognized connection (for example, SSH). The returned value will be one of the following:

0 — Indicates an SSL/TLS server connection
1 — Indicates an SSL/TLS client connection
Negative number — Indicates an unknown connection type

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_SSL_CLIENT__
__ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__
__ENABLE_MOCANA_SSL_SERVER__
__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__

Additionally, the following flag must not be defined:

__DISABLE_SSL_IS_SESSION_API__

ssl.h

Parameters

connectionInstance Connection instance returned from SSL_connect().

Returns: 0 if the connection instance is an SSL/TLS server; 1 if an SSL/TLS client; negative number if an unrecognized connection.

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

ssl.c

◆ SSL_lookupAlert()

MOC_EXTERN sbyte4 SSL_lookupAlert	(	sbyte4	connectionInstance,
		sbyte4	lookupError,
		sbyte4 *	pRetAlertId,
		sbyte4 *	pAlertClass
	)

This function returns the SSL alert code for the specified Mocana error (from merrors.h), as well as the alert class (SSLALERTLEVEL_WARNING or SSLALERTLEVEL_FATAL). See ssl_alert_codes for the list of alert definitions.

Since: 1.41

Version: 1.41 and later

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

__ENABLE_MOCANA_SSL_ALERTS__

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

__ENABLE_MOCANA_SSL_CLIENT__
__ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__
__ENABLE_MOCANA_SSL_SERVER__
__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__

ssl.h

Parameters

connectionInstance	Connection instance returned from SSL_connect().
lookupError	Mocana error value to look up.
pRetAlertId	On return, pointer to SSL alert code.
pAlertClass	On return, pointer to alert class definition value.

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 clients and servers.

ssl.c

◆ SSL_releaseTables()

MOC_EXTERN sbyte4 SSL_releaseTables ( void )

This function releases the SSL/TLS Client's or Server's internal memory tables. It should only be called after a call to SSL_shutdownStack(). To resume communication with a device after calling this function, you must create a new connection and register encryption keys and an X.509 certificate.

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_SSL_CLIENT__
__ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__
__ENABLE_MOCANA_SSL_SERVER__
__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__

ssl.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 clients and servers.

sbyte4 status;
status = SSL_releaseTables();

ssl.c

◆ SSL_sendAlert()

MOC_EXTERN sbyte4 SSL_sendAlert	(	sbyte4	connectionInstance,
		sbyte4	alertId,
		sbyte4	alertClass
	)

This function sends an SSL alert message to an SSL peer. Typical usage is to look up an error code using SSL_lookupAlert(), and then send the alert message using this SSL_sendAlert() function.

Since: 1.41

Version: 1.41 and later

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

__ENABLE_MOCANA_SSL_ALERTS__

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

__ENABLE_MOCANA_SSL_CLIENT__
__ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__
__ENABLE_MOCANA_SSL_SERVER__
__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__

ssl.h

Parameters

connectionInstance	Connection instance returned from SSL_connect().
alertId	SSL alert code.
alertClass	SSL alert class definition value.

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 clients and servers.

ssl.c

◆ SSL_setCipherAlgorithm()

MOC_EXTERN MSTATUS SSL_setCipherAlgorithm	(	sbyte4	connectionInstance,
		ubyte2 *	pList,
		ubyte4	listLength,
		ubyte4	listType
	)

This function sets either cipher or supported groups or signature algorithm for a given connection. It is supported in TLS 1.3 only

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_SSL_CLIENT__
__ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__
__ENABLE_MOCANA_SSL_SERVER__
__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__ And the following flags have to be enabled
__ENABLE_MOCANA_TLS13__
__ENABLE_MOCANA_SSL_CIPHER_SUITES_SELECT__

ssl.h

Parameters

connectionInstance	Connection instance returned from SSL_connect().
pList	List of algorithms corresponding to the listType. Please refer to the supported listTypes below.
listLength	Number of entities in the list
listType	Type of the list. 0 - Ciphers 1 - Supported Groups 2 - Signatuer Algotrithm

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 clients and servers.

ssl.c

◆ SSL_setCookie()

MOC_EXTERN sbyte4 SSL_setCookie	(	sbyte4	connectionInstance,
		void *	cookie
	)

This function stores information about the context connection. Your application should not call this function until after calling SSL_connect().

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_SSL_CLIENT__
__ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__
__ENABLE_MOCANA_SSL_SERVER__
__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__

ssl.h

Parameters

connectionInstance	Connection instance returned from SSL_connect().
cookie	Custom information (cookie data) to store.

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 clients and servers.

mySessionInfo *mySession = malloc(sizeof(mySessionInfo));
SSL_setCookie(connectionInstance, (int)(&mySession));

ssl.c

◆ SSL_setDHParameters()

MOC_EXTERN sbyte4 SSL_setDHParameters	(	ubyte *	pP,
		ubyte4	pLen,
		ubyte *	pG,
		ubyte4	gLen,
		ubyte4	lengthY
	)

This function will allow the caller to set the DH prime and generator values used during a SSL connection. Additionally, the secret value size must be provided as well. If the DH parameters are not specified through this function then the default DH parameters will be used.

Since

Version

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

__ENABLE_MOCANA_SSL_DHE_SUPPORT__
__ENABLE_MOCANA_SSL_DH_ANON_SUPPORT__

ssl.h

Parameters

pP	The DH group value. This will be a prime number.
pLen	Length of pP buffer.
pG	The DH generator value. This value will be used to generate a secret during the server/client connection.
gLen	Length of pG buffer.
lengthY	This value will be the size of the secret to generate in bytes. This value should be less then the amount of bytes in the prime value.

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.

ssl.c

◆ SSL_setDSACiphers()

MOC_EXTERN sbyte4 SSL_setDSACiphers	(	sbyte4	connectionInstance,
		ubyte	enableDSACiphers
	)

This function dynamically enables/disables ciphers. This function should be invoked after SSL_setDSACiphers().

The function must not be called before a connection is established (see SSL_connect() for synchronous clients, SSL_ASYNC_connect() for asynchronous clients), but must be called before SSL_negotiateConnection() (for either synchronous or asynchronous clients).

Since: 1.41

Version: 1.41 and later

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

__ENABLE_MOCANA_SSL_CIPHER_SUITES_SELECT__

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

__ENABLE_MOCANA_SSL_CLIENT__
__ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__
__ENABLE_MOCANA_SSL_SERVER__
__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__
__ENABLE_MOCANA_SSL_DSA_SUPPORT__

ssl.h

Parameters

connectionInstance	Connection instance returned from SSL_connect().
enableDSACiphers	1 - Enables DSA ciphers 0 - Disables DSA ciphers

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 clients and servers.

ssl.c

◆ SSL_setFIPSEnabled()

MOC_EXTERN sbyte4 SSL_setFIPSEnabled ( ubyte isFIPSEnabled )

This function enables FIPS mode at runtime. When FIPS is enabled, only a subset of ciphers, keysizes, hash algorithms and symmetric algorithms are supported.

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_SSL_FIPS__

ssl.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 clients and servers.

ssl.c

◆ SSL_setMinRSAKeySize()

MOC_EXTERN sbyte4 SSL_setMinRSAKeySize ( ubyte4 keySize )

This function dynamically sets the minimum RSA Key size, that can be used in a SSL?TLS connection.

Parameters

keySize Indicates the keySize to be set as minimum RSA Key Size.

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 clients and servers.

◆ SSL_setSessionFlags()

MOC_EXTERN sbyte4 SSL_setSessionFlags	(	sbyte4	connectionInstance,
		ubyte4	flagsSSL
	)

This function stores a connection's context — its flags. Your application can call this function any time after it calls SSL_connect().

The context flags are specified by OR-ing the desired bitmask flag definitions, defined in ssl.h:

SSL_FLAG_ACCEPT_SERVER_NAME_LIST
SSL_FLAG_ENABLE_RECV_BUFFER
SSL_FLAG_ENABLE_SEND_BUFFER
SSL_FLAG_ENABLE_SEND_EMPTY_FRAME
SSL_FLAG_NO_MUTUAL_AUTH_REQ
SSL_FLAG_REQUIRE_MUTUAL_AUTH

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_SSL_CLIENT__
__ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__
__ENABLE_MOCANA_SSL_SERVER__
__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__

Additionally, the following flag must not be defined:

__DISABLE_SSL_SESSION_FLAGS_API__

ssl.h

Parameters

connectionInstance	Connection instance returned from SSL_connect().
flagsSSL	Bitmask of flags to set for the given connection's context. They can be retrieved by calling SSL_getSessionFlags().

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.

Note: To avoid clearing any flags that are already set, you should first call SSL_getSessionFlags(), then OR the returned value with the desired new flag, and only then call SSL_setSessionFlags().

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

ssl.c

◆ SSL_setSha1SigAlg()

MOC_EXTERN sbyte4 SSL_setSha1SigAlg ( intBoolean setting )

This function dynamically enables or disables the use of the SHA-1 algorithm for signature algorithms.

Parameters

setting Pass in TRUE to enable SHA-1 or FALSE to disable SHA-1.

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 clients and servers.

◆ SSL_Settings_Ioctl()

MOC_EXTERN sbyte4 SSL_Settings_Ioctl	(	ubyte4	setting,
		void *	value
	)

This function enables dynamic management (enabling and disabling) of selected features.

Since: 1.41

Version: 3.06 and later

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

__ENABLE_MOCANA_SSL_CLIENT__
__ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__
__ENABLE_MOCANA_SSL_SERVER__
__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__

Additionally, the following flag must not be defined:

__DISABLE_SSL_IOCTL_API__

ssl.h

Parameters

setting	SSL feature flag to dynamically alter; see SSL runtime flag definitions (`SSL_SETTINGS_*`) in ssl.h.
value	Value to assign to the `setting` flag.

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 clients and servers.

ssl.c

◆ SSL_shutdownStack()

MOC_EXTERN sbyte4 SSL_shutdownStack ( void )

This function performs memory and mutex cleanup and shuts down the SSL stack. In rare instances, for example changing the port number to which an embedded device listens, you may need to completely stop the SSL/TLS Client/Server and all its resources. However, in most circumstances this is unnecessary because the NanoSSL client/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_SSL_CLIENT__
__ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__
__ENABLE_MOCANA_SSL_SERVER__
__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__

ssl.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 clients and servers.

sbyte4 status = 0;
status = SSL_shutdownStack();

ssl.c

◆ SSL_sslSettings()

MOC_EXTERN sslSettings* SSL_sslSettings ( void )

This function returns a pointer to NanoSSL client/server settings that can be dynamically adjusted during initialization or runtime.

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_SSL_CLIENT__
__ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__
__ENABLE_MOCANA_SSL_SERVER__
__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__

ssl.h

Returns: Pointer to NanoSSL client/server settings that can be dynamically adjusted during initialization or runtime.

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

ssl.c

Functions

Detailed Description

Function Documentation

◆ DTLS_isTimerExpired()

◆ SSL_checkFIPS()

◆ SSL_disableCipherHashAlgorithm()

◆ SSL_DTLS_getTimeout()

◆ SSL_enableCiphers()

◆ SSL_enableECCCurves()

◆ SSL_generateEarlyExportKeyMaterial()

◆ SSL_generateExportKeyMaterial()

◆ SSL_getCipherInfo()

◆ SSL_getCipherList()

◆ SSL_getCookie()

◆ SSL_getInstanceFromSocket()

◆ SSL_getSessionFlags()

◆ SSL_getSessionStatus()

◆ SSL_getSocketId()

◆ SSL_initiateRehandshake()

◆ SSL_ioctl()

◆ SSL_isSessionDTLS()

◆ SSL_isSessionSSL()

◆ SSL_lookupAlert()

◆ SSL_releaseTables()

◆ SSL_sendAlert()

◆ SSL_setCipherAlgorithm()

◆ SSL_setCookie()

◆ SSL_setDHParameters()

◆ SSL_setDSACiphers()

◆ SSL_setFIPSEnabled()

◆ SSL_setMinRSAKeySize()

◆ SSL_setSessionFlags()

◆ SSL_setSha1SigAlg()

◆ SSL_Settings_Ioctl()

◆ SSL_shutdownStack()

◆ SSL_sslSettings()