NanoDTLS developer API header. More...

Functions
MOC_EXTERN sbyte4	DTLS_acceptConnection (peerDescr pPeerDescr, struct certStore pCertStore)
	Register a secure NanoDTLS connection. More...

MOC_EXTERN sbyte4	DTLS_checkHandshakeTimer (sbyte4 connectionInstance)
	Check a NanoDTLS client's or server's timer to provide time to the NanoDTLS stack. More...

MOC_EXTERN sbyte4	DTLS_closeConnection (sbyte4 connectionInstance)
	Close a NanoDTLS session and release resources. More...

MOC_EXTERN sbyte4	DTLS_connect (peerDescr pPeerDescr, ubyte sessionIdLen, ubyte sessionId, ubyte masterSecret, const sbyte dnsName, struct certStore *pCertStore)
	Create a NanoDTLS client connection descriptor. More...

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

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

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

MOC_EXTERN sbyte4	DTLS_enableSrtpProfiles (sbyte4 connectionInstance, ubyte2 *pSrtpProfileList, ubyte4 listLength)
	Enable specified SRTP profiles. More...

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

MOC_EXTERN sbyte4	DTLS_getClientSessionInfo (sbyte4 connectionInstance, ubyte *sessionIdLen, ubyte sessionId[32], ubyte masterSecret[48])
	Get connection instance's identifying information. More...

MOC_EXTERN sbyte4	DTLS_getConnectionInstance (MOC_IP_ADDRESS srcAddr, ubyte2 srcPort, MOC_IP_ADDRESS peerAddr, ubyte2 peerPort)
	Get a DTLS connection instance for the specified src-dst connection. More...

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

MOC_EXTERN sbyte4	DTLS_getNextConnectionInstance (ubyte4 pCookie, sbyte4 pConnectionInstance, const peerDescr **ppRetPeerDescr)
	Get a server's next open client connection instance. More...

MOC_EXTERN sbyte4	DTLS_getPeerDescr (sbyte4 connectionInstance, const peerDescr **ppRetPeerDescr)
	Get a NanoDTLS connection descriptor. More...

MOC_EXTERN sbyte4	DTLS_getRecvBuffer (sbyte4 connectionInstance, ubyte *data, ubyte4 len, ubyte4 *pRetProtocol)
	Get a pointer to the connection's receive data buffer (the socket buffer itself). More...

MOC_EXTERN sbyte4	DTLS_getSendBuffer (sbyte4 connectionInstance, ubyte data, ubyte4 len)
	Get a copy of the connection's send data buffer. More...

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

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

MOC_EXTERN sbyte4	DTLS_init (sbyte4 numServerConnections, sbyte4 numClientConnections)
	Initialize NanoDTLS client or server internal structures. More...

MOC_EXTERN sbyte4	DTLS_initEx (sbyte4 numServerConnections, sbyte4 numClientConnections, RNGFun rngFun, void *arg)
	Initialize NanoDTLS client or server internal structures with custom RNG. More...

MOC_EXTERN sbyte4	DTLS_initiateRehandshake (sbyte4 connectionInstance)
	Renegotiate a NanoDTLS session. More...

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

MOC_EXTERN sbyte4	DTLS_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	DTLS_lookupAlert (sbyte4 connectionInstance, sbyte4 lookupError, sbyte4 pRetAlertId, sbyte4 pAlertClass)
	Get the SSL alert code for a Digicert SoT Platform error. More...

MOC_EXTERN sbyte4	DTLS_recvMessage (sbyte4 connectionInstance, ubyte pBytesReceived, ubyte4 numBytesReceived, ubyte ppRetBytesReceived, ubyte4 pRetNumRxBytesRemaining)
	Get a pointer to the connection's most recently receiveed message. More...

MOC_EXTERN sbyte4	DTLS_releaseTables (void)
	Release memory used by internal NanoDTLS memory tables. More...

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

MOC_EXTERN MSTATUS	DTLS_sendKeyUpdateRequest (sbyte4 connectionInstance, ubyte updateRequest)
	Sends a key update request. More...

MOC_EXTERN sbyte4	DTLS_sendMessage (sbyte4 connectionInstance, sbyte pBuffer, sbyte4 bufferSize, sbyte4 pBytesSent)
	Send data to a connected server/client. More...

MOC_EXTERN MSTATUS	DTLS_sendPosthandshakeAuthCertificateRequest (sbyte4 connectionInstance)
	Sends a post-handshake authentication request to client. More...

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

MOC_EXTERN sbyte4	DTLS_setDNSNames (sbyte4 connectionInstance, const CNMatchInfo *cnMatchInfo)
	Specify a list of DNS names acceptable to the client. More...

MOC_EXTERN sbyte4	DTLS_setEarlyData (sbyte4 connectionInstance, ubyte *pEarlyData, ubyte4 earlyDataSize)
	Set the max early data. More...

MOC_EXTERN sbyte4	DTLS_setMaxEarlyDataSize (sbyte4 connectionInstance, sbyte4 earlyDataSize)
	Set the max early data size. More...

MOC_EXTERN sbyte4	DTLS_setReceiveApplicationDataCallback (sbyte4(funcPtrTLS13ApplicationDataCallback)(sbyte4 connectionInstance, ubyte pData, ubyte4 dataLen, dataState state))
	Function to set the callback to pass data to the application received during the SSL handshake. More...

MOC_EXTERN sbyte4	DTLS_setRecvEarlyDataSize (sbyte4 connectionInstance, sbyte4 recvEarlyDataSize)
	Set the recv early data size. More...

MOC_EXTERN sbyte4	DTLS_setServerNameIndication (sbyte4 connectionInstance, const char *serverName)
	Specify the server name required by the client. More...

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

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

MOC_EXTERN sbyte4	DTLS_start (sbyte4 connectionInstance)
	Start establishing a secure client-server connection. More...

MOC_EXTERN sbyte4	DTLS_verifyClientHelloCookie (MOC_IP_ADDRESS peerAddr, ubyte pReceived, ubyte4 length, ubyte pToSend, ubyte4 *pToSendLen)
	Verify a client's legitimacy by using the provided cookie. More...

Detailed Description

This file contains functions used by NanoDTLS servers and clients.

Since: 3.06

Version: 5.1.1 and later

Whether the following flags are defined determines which function declarations and callbacks are enabled:

__ENABLE_MOCANA_DTLS_CLIENT__
__ENABLE_MOCANA_DTLS_SERVER__
__ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__
__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__
__ENABLE_MOCANA_MULTIPLE_COMMON_NAMES__
__ENABLE_MOCANA_SSL_CUSTOM_RNG__
__ENABLE_MOCANA_SSL_ALERTS__
__ENABLE_MOCANA_SSL_CIPHER_SUITES_SELECT__
__ENABLE_MOCANA_SSL_ECDH_SUPPORT__
__ENABLE_MOCANA_SSL_ECDHE_SUPPORT__
__ENABLE_MOCANA_SSL_ECDH_ANON_SUPPORT__
__ENABLE_MOCANA_SSL_REHANDSHAKE__
__ENABLE_MOCANA_DTLS_SRTP__
__ENABLE_MOCANA_SRTP_PROFILES_SELECT__
__DISABLE_SSL_IS_SESSION_API__
__DISABLE_SSL_SESSION_FLAGS_API__
__DISABLE_SSL_IOCTL_API__

dtls.h

Function Documentation

◆ DTLS_acceptConnection()

MOC_EXTERN sbyte4 DTLS_acceptConnection	(	peerDescr *	pPeerDescr,
		struct certStore *	pCertStore
	)

This function registers a secure NanoDTLS connection.

Since: 3.06

Version: 3.06 and later

To enable this function, the following flag must be defined:

__ENABLE_MOCANA_DTLS_SERVER__

dtls.h

Parameters

pPeerDescr	DTLS connection descriptor returned by a call to `accept()`.
pCertStore	Pointer to SoT Platform certificate store that contains the DTLS connection's certificate (as a trust point or identity).

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 servers only.

dtls.h

◆ DTLS_checkHandshakeTimer()

MOC_EXTERN sbyte4 DTLS_checkHandshakeTimer ( sbyte4 connectionInstance )

This function checks a NanoDTLS client's or server's timer. Your application should call this function on every clock tick (every 300 to 500 milliseconds) to provide time to the NanoDTLS stack.

Since: 3.06

Version: 3.06 and later

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

__ENABLE_MOCANA_DTLS_CLIENT__
__ENABLE_MOCANA_DTLS_SERVER__

dtls.h

Parameters

connectionInstance Connection instance returned from DTLS_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.

Remarks: This function is applicable to clients and servers.

dtls.h

◆ DTLS_closeConnection()

MOC_EXTERN sbyte4 DTLS_closeConnection ( sbyte4 connectionInstance )

This function closes a NanoDTLS session and releases all the resources that are managed by the NanoDTLS client/server.

Since: 3.06

Version: 3.06 and later

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

__ENABLE_MOCANA_DTLS_CLIENT__
__ENABLE_MOCANA_DTLS_SERVER__

dtls.h

Parameters

connectionInstance Connection instance returned from DTLS_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.

Note: This function does not close UDP sockets. Your integration code should explicitly close all UDP sockets defined in peerDescr connection descriptors.

Remarks: This function is applicable to clients and servers.

dtls.h

◆ DTLS_connect()

MOC_EXTERN sbyte4 DTLS_connect	(	peerDescr *	pPeerDescr,
		ubyte	sessionIdLen,
		ubyte *	sessionId,
		ubyte *	masterSecret,
		const sbyte *	dnsName,
		struct certStore *	pCertStore
	)

This function creates a connection descriptor for a secure NanoDTLS connection with a remote server.

Since: 3.06

Version: 3.06 and later

To enable this function, the following flag must be defined:

__ENABLE_MOCANA_DTLS_CLIENT__

dtls.h

Parameters

pPeerDescr	NanoDTLS connection descriptor returned by a call to `connect()`.
sessionIdLen	Number of bytes in `sessionId`, excluding the `NULL` terminator.
sessionId	Pointer to session ID.
masterSecret	Pointer to master secret for the session.
dnsName	Pointer to expected DNS name of the server's certificate.
pCertStore	Pointer to SoT Platform certificate store that contains the DTLS connection's certificate (as a trust point or identity).

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 clients only.

dtls.h

◆ DTLS_dtlsSettings()

MOC_EXTERN struct sslSettings* DTLS_dtlsSettings ( void )

This function returns a pointer to NanoSSL and NanoDTLS settings that can be dynamically adjusted during initialization or runtime.

Since: 3.06

Version: 3.06 and later

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

__ENABLE_MOCANA_DTLS_CLIENT__
__ENABLE_MOCANA_DTLS_SERVER__

dtls.h

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

Remarks: This function is applicable to clients and servers.

dtls.h

◆ DTLS_enableCiphers()

MOC_EXTERN sbyte4 DTLS_enableCiphers	(	sbyte4	connectionInstance,
		ubyte2 *	pCipherSuiteList,
		ubyte4	listLength
	)

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

This function must not be called before a connection is established (see DTLS_connect()), but must be called before DTLS_start().

Since: 3.06

Version: 3.2 and later

To enable this function, the following flag must be defined:

__ENABLE_MOCANA_SSL_CIPHER_SUITES_SELECT__

Additionally, at least one of the following flags must be defined:

__ENABLE_MOCANA_DTLS_CLIENT__
__ENABLE_MOCANA_DTLS_SERVER__

dtls.h

Parameters

connectionInstance	Connection instance returned from DTLS_connect().
pCipherSuiteList	Pointer to value (or array of values) representing the desired cipher ID(s). Be sure not to specify only streaming (RC4) ciphers. Streaming ciphers do not conform to the DTLS protocol, and so will never be chosen by the server during handshaking. Therefore, if only streaming ciphers are enabled, the handshake will never succeed. 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 clients and servers.

dtls.h

◆ DTLS_enableECCCurves()

MOC_EXTERN sbyte4 DTLS_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 NanoDTLS client/server and enabled in your implementation, an error is returned.

The function must not be called before a connection is established,

Since: 1.41

Version: 1.41 and later

To enable this function, the following flag must be defined:

__ENABLE_MOCANA_SSL_CIPHER_SUITES_SELECT__

Additionally, at least one of the following flags must be defined:

__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__

dtls.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.

dtls.h

◆ DTLS_enableSrtpProfiles()

MOC_EXTERN sbyte4 DTLS_enableSrtpProfiles	(	sbyte4	connectionInstance,
		ubyte2 *	pSrtpProfileList,
		ubyte4	listLength
	)

This function dynamically enables only those SRTP profiles that are specified in the function call. If none of the specified profiles match those supported by NanoDTLS and enabled in your implementation, an error is returned.

Since: 5.1

Version: 5.1 and later

To enable this function, the following flags must be defined:

__ENABLE_MOCANA_DTLS_SRTP__
__ENABLE_MOCANA_SRTP_PROFILES_SELECT__

Additionally, at least one of the following flags must be defined:

__ENABLE_MOCANA_DTLS_CLIENT__
__ENABLE_MOCANA_DTLS_SERVER__

dtls.h

Parameters

connectionInstance	Connection instance returned from DTLS_connect() or DTLS_acceptConnection().
pSrtpProfileList	Pointer to value (or array of values) representing the desired profile ID(s).
listLength	Number of entries in `pSrtpProfileList`.

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 client and server.

dtls.h

◆ DTLS_getCipherInfo()

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

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

Since: 3.06

Version: 3.06 and later

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

__ENABLE_MOCANA_DTLS_CLIENT__
__ENABLE_MOCANA_DTLS_SERVER__

dtls.h

Parameters

connectionInstance	Connection instance returned from DTLS_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 clients and servers.

dtls.h

◆ DTLS_getClientSessionInfo()

MOC_EXTERN sbyte4 DTLS_getClientSessionInfo	(	sbyte4	connectionInstance,
		ubyte *	sessionIdLen,
		ubyte	sessionId[32],
		ubyte	masterSecret[48]
	)

This function retrieves identifying information for the connection instance's context. This information can be saved for DTLS session reuse, allowing subsequent connections to be made much more quickly than the initial connection.

Since: 3.06

Version: 3.06 and later

To enable this function, the following flag must be defined:

__ENABLE_MOCANA_DTLS_CLIENT__

dtls.h

Parameters

connectionInstance	Connection instance returned from DTLS_connect
sessionIdLen	Pointer to number of bytes in $sessionId$.
sessionId	Buffer for returned session ID.
masterSecret	Buffer for returned master secret.

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 clients only.

dtls.h

◆ DTLS_getConnectionInstance()

MOC_EXTERN sbyte4 DTLS_getConnectionInstance	(	MOC_IP_ADDRESS	srcAddr,
		ubyte2	srcPort,
		MOC_IP_ADDRESS	peerAddr,
		ubyte2	peerPort
	)

This function returns a connection instance for the specified src-dst connection. The returned connection instance can be used as a parameter in subsequent calls to NanoDTLS server functions.

Since: 3.06

Version: 3.06 and later

To enable this function, the following flag must be defined:

__ENABLE_MOCANA_DTLS_SERVER__

dtls.h

Parameters

srcAddr	Source's IP address.
srcPort	Source's port number.
peerAddr	Peer's IP address.
peerPort	Peer's port 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.

Remarks: This function is applicable to servers only.

dtls.h

◆ DTLS_getCookie()

MOC_EXTERN sbyte4 DTLS_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 DTLS_setCookie().

Since: 3.06

Version: 3.06 and later

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

__ENABLE_MOCANA_DTLS_CLIENT__
__ENABLE_MOCANA_DTLS_SERVER__

dtls.h

Parameters

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

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

dtls.h

◆ DTLS_getNextConnectionInstance()

MOC_EXTERN sbyte4 DTLS_getNextConnectionInstance	(	ubyte4 *	pCookie,
		sbyte4 *	pConnectionInstance,
		const peerDescr **	ppRetPeerDescr
	)

This function returns a server's next open client connection instance. Typically your application will call this function in an iterative fashion to examine all a server's client connections in turn, performing necessary message processing and communication for each connection.

Since: 3.06

Version: 3.06 and later

To enable this function, the following flag must be defined:

__ENABLE_MOCANA_DTLS_SERVER__

dtls.h

Parameters

pCookie	At function call, reference to opaque cookie that points to previously returned open connection instance. (The first time you call this function, use a value of `NULL`.) On return, reference to updated cookie pointing to next connection instance. (Save this value for subsequent calls to this function.)
pConnectionInstance	On return, pointer to next open connection instance.
ppRetPeerDescr	On return, pointer to DTLS connection descriptor corresponding to the next open connection instance (`pConnectionInstance`).

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 servers only.

dtls.h

◆ DTLS_getPeerDescr()

MOC_EXTERN sbyte4 DTLS_getPeerDescr	(	sbyte4	connectionInstance,
		const peerDescr **	ppRetPeerDescr
	)

This function gets a NanoDTLS connection descriptor.

Since: 3.06

Version: 3.06 and later

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

__ENABLE_MOCANA_DTLS_CLIENT__
__ENABLE_MOCANA_DTLS_SERVER__

dtls.h

Parameters

connectionInstance	Connection instance returned from DTLS_connect().
ppRetPeerDescr	On return, pointer to NanoDTLS connection descriptor returned by a call to `accept()`.

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

dtls.h

◆ DTLS_getRecvBuffer()

MOC_EXTERN sbyte4 DTLS_getRecvBuffer	(	sbyte4	connectionInstance,
		ubyte **	data,
		ubyte4 *	len,
		ubyte4 *	pRetProtocol
	)

This function returns a pointer (through the data parameter) to the specified connection's most recently received data buffer (the socket buffer itself).

Since: 3.06

Version: 3.06 and later

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

__ENABLE_MOCANA_DTLS_CLIENT__
__ENABLE_MOCANA_DTLS_SERVER__

dtls.h

Parameters

connectionInstance	Connection instance returned from DTLS_connect().
data	On return, pointer to the address of the connection's receive buffer.
len	On return pointer to number of bytes in `data`.
pRetProtocol	On return, the DTLS protocol type for `data` (usually 23 == SSL Application Data)

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

dtls.h

◆ DTLS_getSendBuffer()

MOC_EXTERN sbyte4 DTLS_getSendBuffer	(	sbyte4	connectionInstance,
		ubyte *	data,
		ubyte4 *	len
	)

This function returns a copy (through the data parameter) of the specified connection's most recently sent data buffer.

Since: 3.06

Version: 3.06 and later

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

__ENABLE_MOCANA_DTLS_CLIENT__
__ENABLE_MOCANA_DTLS_SERVER__

dtls.h

Parameters

connectionInstance	Connection instance returned from DTLS_connect().
data	On return, pointer to the buffer containing the data in the connection's send buffer.
len	On return pointer to number of bytes in `data`.

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

dtls.h

◆ DTLS_getSessionFlags()

MOC_EXTERN sbyte4 DTLS_getSessionFlags	(	sbyte4	connectionInstance,
		ubyte4 *	pRetFlagsSSL
	)

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

Since: 3.06

Version: 3.06 and later

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

__ENABLE_MOCANA_DTLS_CLIENT__
__ENABLE_MOCANA_DTLS_SERVER__

Additionally, the following flag must not be defined:

__DISABLE_SSL_SESSION_FLAGS_API__

dtls.h

Parameters

connectionInstance	Connection instance returned from DTLS_connect().
pRetFlagsDTLS	Pointer to the connection's flags, which have been set by DTLS_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 clients and servers.

dtls.h

◆ DTLS_getSessionStatus()

MOC_EXTERN sbyte4 DTLS_getSessionStatus	(	sbyte4	connectionInstance,
		ubyte4 *	pRetStatusSSL
	)

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

Since: 3.06

Version: 3.06 and later

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

__ENABLE_MOCANA_DTLS_CLIENT__
__ENABLE_MOCANA_DTLS_SERVER__

dtls.h

Parameters

connectionInstance	Connection instance returned from DTLS_connect().
pRetStatusDTLS	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 clients and servers.

dtls.h

◆ DTLS_init()

MOC_EXTERN sbyte4 DTLS_init	(	sbyte4	numServerConnections,
		sbyte4	numClientConnections
	)

This function initializes NanoDTLS client/server internal structures. Your application should call this function before staring the application servers.

Since: 3.06

Version: 3.06 and later

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

__ENABLE_MOCANA_DTLS_CLIENT__
__ENABLE_MOCANA_DTLS_SERVER__

dtls.h

Parameters

numServerConnections	Maximum number of NanoDTLS server connections to allow. (Each connection requires only a few bytes of memory.) If operating in dual mode, this is the sum of the synchronous and asynchronous server connections.
numClientConnections	Maximum number of NanoDTLS client connections to allow.

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

dtls.h

◆ DTLS_initEx()

MOC_EXTERN sbyte4 DTLS_initEx	(	sbyte4	numServerConnections,
		sbyte4	numClientConnections,
		RNGFun	rngFun,
		void *	arg
	)

This function initializes NanoDTLS client/server internal structures with a custom RNG. Your application should call this function before staring the application servers.

Since: 3.06

Version: 3.06 and later

To enable this function, at least one of the flags must be defined:

__ENABLE_MOCANA_DTLS_CLIENT__
__ENABLE_MOCANA_DTLS_SERVER__

Additionally, the following flags must be defined:

__ENABLE_MOCANA_SSL_CUSTOM_RNG__

dtls.h

Parameters

numServerConnections	Maximum number of NanoDTLS server connections to allow. (Each connection requires only a few bytes of memory.) If operating in dual mode, this is the sum of the synchronous and asynchronous server connections.
numClientConnections	Maximum number of NanoDTLS client connections to allow.
rngFun	Function pointer to the RNG method
arg	The argument used by the RNG method, typically a randomContext.

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

dtls.h

◆ DTLS_initiateRehandshake()

MOC_EXTERN sbyte4 DTLS_initiateRehandshake ( sbyte4 connectionInstance )

This function causes a client or server to renegotiate a NanoDTLS session. Renegoatiation 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: 3.06

Version: 3.06 and later

To enable this function, the following flag must be defined:

__ENABLE_MOCANA_SSL_REHANDSHAKE__

Additionally, at least one of the following flags must be defined:

__ENABLE_MOCANA_DTLS_CLIENT__
__ENABLE_MOCANA_DTLS_SERVER__

dtls.h

Parameters

connectionInstance Connection instance returned from DTLS_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.

Remarks: This function is applicable to clients and servers.

dtls.h

◆ DTLS_ioctl()

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

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

Since: 3.06

Version: 3.06 and later

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

__ENABLE_MOCANA_DTLS_CLIENT__
__ENABLE_MOCANA_DTLS_SERVER__

Additionally, the following flag must not be defined:

__DISABLE_SSL_IOCTL_API__

dtls.h

Parameters

connectionInstance	Connection instance returned from DTLS_connect().
setting	SSL feature flag to dynamically alter; see SSL ioctl 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 clients and servers.

dtls.h

◆ DTLS_isSessionDTLS()

MOC_EXTERN sbyte4 DTLS_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 a DTLS server connection
1—Indicates a DTLS client connection
Negative number—Indicates an unknown connection type

Since: 3.06

Version: 3.06 and later

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

__ENABLE_MOCANA_DTLS_CLIENT__
__ENABLE_MOCANA_DTLS_SERVER__

Additionally, the following flag must not be defined:

__DISABLE_SSL_IS_SESSION_API__

dtls.h

Parameters

connectionInstance Connection instance returned from DTLS_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 clients and servers.

dtls.h

◆ DTLS_lookupAlert()

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

This function returns the SSL alert code for the specified Mocana SoT Platform 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: 3.06

Version: 3.06 and later

To enable this function, the following flag must be defined:

__ENABLE_MOCANA_SSL_ALERTS__

Additionally, at least one of the following flags must be defined:

__ENABLE_MOCANA_DTLS_CLIENT__
__ENABLE_MOCANA_DTLS_SERVER__

dtls.h

Parameters

connectionInstance	Connection instance returned from DTLS_connect().
lookupError	Digicert SoT Platform 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 clients and servers.

dtls.h

◆ DTLS_recvMessage()

MOC_EXTERN sbyte4 DTLS_recvMessage	(	sbyte4	connectionInstance,
		ubyte *	pBytesReceived,
		ubyte4	numBytesReceived,
		ubyte **	ppRetBytesReceived,
		ubyte4 *	pRetNumRxBytesRemaining
	)

This function returns a pointer (through the pBytesReceived parameter) to the specified connection's most recently received message. Typically, you'll call this function and then call DTLS_getRecvBuffer() to get the pointer to the decrypted data.

Since: 3.06

Version: 3.06 and later

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

__ENABLE_MOCANA_DTLS_CLIENT__
__ENABLE_MOCANA_DTLS_SERVER__

Additionally, the following flags must be defined:

__ENABLE_MOCANA_SSL_ASYNC_API_EXTENSIONS__

dtls.h

Parameters

connectionInstance	Connection instance returned from DTLS_connect().
pBytesReceived	On return, pointer to the packet or message received from the UDP/IP stack.
numBytesReceived	On return, number of bytes in `BytesReceived`.
ppRetBytesReceived	On return, pointer to buffer containing number of bytes remaining to be read.
pRetNumRxBytesRemaining	On return, pointer to number of bytes in `ppRetBytesReceived`.

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

dtls.h

◆ DTLS_releaseTables()

MOC_EXTERN sbyte4 DTLS_releaseTables ( void )

This function releases the NanoDTLS client's or Server's internal memory tables. It should only be called after a call to DTLS_shutdown(). 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: 3.06

Version: 3.06 and later

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

__ENABLE_MOCANA_DTLS_CLIENT__
__ENABLE_MOCANA_DTLS_SERVER__

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

sbyte4 status;
status = DTLS_releaseTables();

dtls.h

◆ DTLS_sendAlert()

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

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

Since: 3.06

Version: 3.06 and later

To enable this function, the following flag must be defined:

__ENABLE_MOCANA_SSL_ALERTS__

Additionally, at least one of the following flags must be defined:

__ENABLE_MOCANA_DTLS_CLIENT__
__ENABLE_MOCANA_DTLS_SERVER__

dtls.h

Parameters

connectionInstance	Connection instance returned from DTLS_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 clients and servers.

dtls.h

◆ DTLS_sendKeyUpdateRequest()

MOC_EXTERN MSTATUS DTLS_sendKeyUpdateRequest	(	sbyte4	connectionInstance,
		ubyte	updateRequest
	)

Sends a key update request

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

__ENABLE_MOCANA_DTLS_CLIENT__
__ENABLE_MOCANA_DTLS_SERVER__ and also define the flag
__ENABLE_MOCANA_TLS13__

dtls.h

Parameters

connectionInstance	Connection instance returned from SSL_connect().
updateRequest	1 for initiator.

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.

dtls.h

◆ DTLS_sendMessage()

MOC_EXTERN sbyte4 DTLS_sendMessage	(	sbyte4	connectionInstance,
		sbyte *	pBuffer,
		sbyte4	bufferSize,
		sbyte4 *	pBytesSent
	)

This function sends data to a connected server/client. It should not be called until a secure NanoDTLS connection is established between the client and server.

Since: 3.06

Version: 3.06 and later

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

__ENABLE_MOCANA_DTLS_CLIENT__
__ENABLE_MOCANA_DTLS_SERVER__

dtls.h

Parameters

connectionInstance	Connection instance returned from DTLS_connect().
pBuffer	Pointer to buffer containing the data to send.
bufferSize	Number of bytes in `pBuffer`.
pBytesSent	On return, pointer to number of bytes successfully sent.

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: This function should not be called until after a $funcPtrOpenStateUpcall$ upcall event.

Remarks: This function is applicable to clients and servers.

static void DTLS_EXAMPLE_helloWorld(int connectionInstance)
{
    sbyte4 bytesSent = 0;
    sbyte4 status;
    status = DTLS_sendMessage(connInstance,
                                   "hello world!", 12,
                                   &bytesSent);
}

dtls.h

◆ DTLS_sendPosthandshakeAuthCertificateRequest()

MOC_EXTERN MSTATUS DTLS_sendPosthandshakeAuthCertificateRequest ( sbyte4 connectionInstance )

Sends a post-handshake authentication request to client.

To enable this function, the following flags must be defined:

__ENABLE_MOCANA_DTLS_SERVER__
__ENABLE_MOCANA_SSL_MUTUAL_AUTH_SUPPORT__ and also define the flag
__ENABLE_MOCANA_TLS13__

dtls.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.

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

dtls.h

◆ DTLS_setCookie()

MOC_EXTERN sbyte4 DTLS_setCookie	(	sbyte4	connectionInstance,
		void *	cookie
	)

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

Since: 3.06

Version: 3.06 and later

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

__ENABLE_MOCANA_DTLS_CLIENT__
__ENABLE_MOCANA_DTLS_SERVER__

dtls.h

Parameters

connectionInstance	Connection instance returned from DTLS_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 clients and servers.

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

dtls.h

◆ DTLS_setDNSNames()

MOC_EXTERN sbyte4 DTLS_setDNSNames	(	sbyte4	connectionInstance,
		const CNMatchInfo *	cnMatchInfo
	)

This function specifies a list of DNS names that when matched to the certificate subject name will enable a connection.

Since: 3.06

Version: 3.06 and later

To enable this function, the following flags must be defined:

__ENABLE_MOCANA_DTLS_CLIENT__
__ENABLE_MOCANA_MULTIPLE_COMMON_NAMES__

dtls.h

Parameters

connectionInstance	Connection instance returned from DTLS_connect().
cnMatchInfos	Pointer to CNMatchInfo structure (defined in ca_mgmt.h) containing acceptable DNS names. The `flags` field is a bit combination of `matchFlag` enumerations (see ca_mgmt.h). The length of the array is indicated by setting the `name` field of the array's final element to `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.

Remarks: This function is applicable to clients only.

dtls.h

◆ DTLS_setEarlyData()

MOC_EXTERN sbyte4 DTLS_setEarlyData	(	sbyte4	connectionInstance,
		ubyte *	pEarlyData,
		ubyte4	earlyDataSize
	)

This function sets the early data which should be sent if 0-RTT is being used. The early data is not copied. It is a shallow copy. Application owns the memory.

To enable this function, the following flags must be defined:

__ENABLE_MOCANA_DTLS_CLIENT__
__ENABLE_MOCANA_TLS13__
__ENABLE_MOCANA_TLS13_PSK__
__ENABLE_MOCANA_TLS13_0RTT__

dtls.h

Parameters

connectionInstance	Connection instance returned from SSL_connect().
pEarlyData	Early data to set.

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.

dtls.h

◆ DTLS_setMaxEarlyDataSize()

MOC_EXTERN sbyte4 DTLS_setMaxEarlyDataSize	(	sbyte4	connectionInstance,
		sbyte4	earlyDataSize
	)

This function sets (defines) the max early data size use during connection negotiations.

To enable this function, the following flags must be defined:

__ENABLE_MOCANA_DTLS_SERVER__
__ENABLE_MOCANA_TLS13__
__ENABLE_MOCANA_TLS13_PSK__
__ENABLE_MOCANA_TLS13_0RTT__

dtls.h

Parameters

connectionInstance	Connection instance returned from SSL_connect().
earlyDataSize	max early data size to set.

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.

dtls.h

◆ DTLS_setReceiveApplicationDataCallback()

MOC_EXTERN sbyte4 DTLS_setReceiveApplicationDataCallback ( sbyte4(*)(sbyte4 connectionInstance, ubyte *pData, ubyte4 dataLen, dataState state) funcPtrTLS13ApplicationDataCallback )

This function sets the callback function, which is invoked by the stack when it receives Application Data during the handshake is in progress. TLS 1.3 provides such a provision.

Since

Version

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

__ENABLE_MOCANA_TLS13__
__ENABLE_MOCANA_TLS13_PSK__
__ENABLE_MOCANA_TLS13_0RTT__

dtls.h

Parameters

connectionInstance	Connection instance returned from SSL_connect()/SSL_acceptConnection().
funcPtrTLS13ApplicationDataCallback	Function pointer to a valid function, which handles the data.

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.

dtls.c

◆ DTLS_setRecvEarlyDataSize()

MOC_EXTERN sbyte4 DTLS_setRecvEarlyDataSize	(	sbyte4	connectionInstance,
		sbyte4	recvEarlyDataSize
	)

This function sets the recv early data size for the server. Server can recieve early Data of size less than or equal to this value. MaxEarlyDataSize per session should be less than or equal to this value

To enable this function, the following flags must be defined:

__ENABLE_MOCANA_DTLS_SERVER__
__ENABLE_MOCANA_TLS13__
__ENABLE_MOCANA_TLS13_PSK__
__ENABLE_MOCANA_TLS13_0RTT__

dtls.h

Parameters

connectionInstance	Connection instance returned from SSL_connect().
earlyDataSize	recv early data size to set.

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.

dtls.h

◆ DTLS_setServerNameIndication()

MOC_EXTERN sbyte4 DTLS_setServerNameIndication	(	sbyte4	connectionInstance,
		const char *	serverName
	)

This function specifies the server name requested by the client. This enables a client to tell a server the server name the client is attempting to connect to. This may facilitate secure connections to servers that host multiple virtual servers at a single underlying network address.

Since: 3.06

Version: 3.1.1 and later

To enable this function, the following flags must be defined:

__ENABLE_MOCANA_DTLS_CLIENT__

dtls.h

Parameters

connectionInstance	Connection instance returned from DTLS_connect().
serverName	Pointer to string containing a host name.

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

dtls.h

◆ DTLS_setSessionFlags()

MOC_EXTERN sbyte4 DTLS_setSessionFlags	(	sbyte4	connectionInstance,
		ubyte4	flagsSSL
	)

This function stores a connection's context—its flags. Your application can call this function anytime after it calls DTLS_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: 3.06

Version: 3.06 and later

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

__ENABLE_MOCANA_DTLS_CLIENT__
__ENABLE_MOCANA_DTLS_SERVER__

Additionally, the following flag must not be defined:

__DISABLE_SSL_SESSION_FLAGS_API__

dtls.h

Parameters

connectionInstance	Connection instance returned from DTLS_connect().
flagsDTLS	Bitmask of flags to set for the given connection's context. They can be retrieved by calling DTLS_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 DTLS_getSessionFlags(), then OR the returned value with the desired new flag, and only then call DTLS_setSessionFlags().

Remarks: This function is applicable to clients and servers.

dtls.h

◆ DTLS_shutdown()

MOC_EXTERN sbyte4 DTLS_shutdown ( void )

This function performs memory and mutex cleanup and shuts down the NanoDTLS stack. In rare instances, for example changing the port number to which an embedded device listens, you many need to completely stop the NanoDTLS client/server and all its resources. However, in most circumstances this is unnecessary because the NanoDTLS client/server is threadless.

Since: 3.06

Version: 3.06 and later

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

__ENABLE_MOCANA_DTLS_CLIENT__
__ENABLE_MOCANA_DTLS_SERVER__

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

sbyte4 status = 0;
status = DTLS_shutdown();

dtls.h

◆ DTLS_start()

MOC_EXTERN sbyte4 DTLS_start ( sbyte4 connectionInstance )

This function begins the process of establishing a secure connection between a client and server by sending a DTLS Hello message to a server.

Since: 3.06

Version: 3.06 and later

To enable this function, the following flag must be defined:

__ENABLE_MOCANA_DTLS_CLIENT__

dtls.h

Parameters

connectionInstance Connection instance returned from DTLS_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.

Remarks: This function is applicable to clients only.

dtls.h

◆ DTLS_verifyClientHelloCookie()

MOC_EXTERN sbyte4 DTLS_verifyClientHelloCookie	(	MOC_IP_ADDRESS	peerAddr,
		ubyte *	pReceived,
		ubyte4	length,
		ubyte *	pToSend,
		ubyte4 *	pToSendLen
	)

This function uses a server-generated stateless cookie to verify that a known client is located at its claimed IP address, thereby preventing DOS (denial of service) attacks.

Before calling this function (but after the successful return of DTLS_acceptConnection()), the DTLS_SET_HELLO_VERIFIED ioctl must be set to ensure that the server's handshake and record sequence numbers are set correctly. Use the following call: DTLS_ioctl(connectionInstance, DTLS_SET_HELLO_VERIFIED, 1);

Since: 3.06

Version: 3.06 and later

To enable this function, the following flag must be defined:

__ENABLE_MOCANA_DTLS_SERVER__

dtls.h

Parameters

peerAddr	Client's IP address.
pReceived	Pointer to buffer containing `Hello` message received from client.
length	Number of bytes in `Hello` message (`pReceived`).
pToSend	Pointer to buffer containing `HelloVerifyRequest` message, which contains the cookie generated by the server for the client.
pToSendLen	Pointer to number of bytes in `HelloVerifyRequest` message (`pToSend`).

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 servers only.

dtls.h

Functions

Detailed Description

Function Documentation

◆ DTLS_acceptConnection()

◆ DTLS_checkHandshakeTimer()

◆ DTLS_closeConnection()

◆ DTLS_connect()

◆ DTLS_dtlsSettings()

◆ DTLS_enableCiphers()

◆ DTLS_enableECCCurves()

◆ DTLS_enableSrtpProfiles()

◆ DTLS_getCipherInfo()

◆ DTLS_getClientSessionInfo()

◆ DTLS_getConnectionInstance()

◆ DTLS_getCookie()

◆ DTLS_getNextConnectionInstance()

◆ DTLS_getPeerDescr()

◆ DTLS_getRecvBuffer()

◆ DTLS_getSendBuffer()

◆ DTLS_getSessionFlags()

◆ DTLS_getSessionStatus()

◆ DTLS_init()

◆ DTLS_initEx()

◆ DTLS_initiateRehandshake()

◆ DTLS_ioctl()

◆ DTLS_isSessionDTLS()

◆ DTLS_lookupAlert()

◆ DTLS_recvMessage()

◆ DTLS_releaseTables()

◆ DTLS_sendAlert()

◆ DTLS_sendKeyUpdateRequest()

◆ DTLS_sendMessage()

◆ DTLS_sendPosthandshakeAuthCertificateRequest()

◆ DTLS_setCookie()

◆ DTLS_setDNSNames()

◆ DTLS_setEarlyData()

◆ DTLS_setMaxEarlyDataSize()

◆ DTLS_setReceiveApplicationDataCallback()

◆ DTLS_setRecvEarlyDataSize()

◆ DTLS_setServerNameIndication()

◆ DTLS_setSessionFlags()

◆ DTLS_shutdown()

◆ DTLS_start()

◆ DTLS_verifyClientHelloCookie()