This module includes functions that control CoAP Secure (CoAP over DTLS) communication. More...

Macros
#define	OT_DEFAULT_COAP_SECURE_PORT 5684
	Default CoAP Secure port, as specified in RFC 7252.

Typedefs
typedef void(*	otHandleCoapSecureClientConnect )(bool aConnected, void *aContext)

Functions
otError	otCoapSecureStart (otInstance *aInstance, uint16_t aPort)

void	otCoapSecureStop (otInstance *aInstance)

otError	otCoapSecureSetPsk (otInstance aInstance, const uint8_t aPsk, uint16_t aPskLength, const uint8_t *aPskIdentity, uint16_t aPskIdLength)

otError	otCoapSecureGetPeerCertificateBase64 (otInstance aInstance, unsigned char aPeerCert, size_t *aCertLength, size_t aCertBufferSize)

void	otCoapSecureSetSslAuthMode (otInstance *aInstance, bool aVerifyPeerCertificate)

otError	otCoapSecureSetCertificate (otInstance aInstance, const uint8_t aX509Cert, uint32_t aX509Length, const uint8_t *aPrivateKey, uint32_t aPrivateKeyLength)

otError	otCoapSecureSetCaCertificateChain (otInstance aInstance, const uint8_t aX509CaCertificateChain, uint32_t aX509CaCertChainLength)

otError	otCoapSecureConnect (otInstance aInstance, const otSockAddr aSockAddr, otHandleCoapSecureClientConnect aHandler, void *aContext)

void	otCoapSecureDisconnect (otInstance *aInstance)

bool	otCoapSecureIsConnected (otInstance *aInstance)

bool	otCoapSecureIsConnectionActive (otInstance *aInstance)

otError	otCoapSecureSendRequest (otInstance aInstance, otMessage aMessage, otCoapResponseHandler aHandler, void *aContext)

otError	otCoapSecureAddResource (otInstance aInstance, otCoapResource aResource)

void	otCoapSecureRemoveResource (otInstance aInstance, otCoapResource aResource)

void	otCoapSecureSetDefaultHandler (otInstance aInstance, otCoapRequestHandler aHandler, void aContext)

void	otCoapSecureSetClientConnectedCallback (otInstance aInstance, otHandleCoapSecureClientConnect aHandler, void aContext)

otError	otCoapSecureSendResponse (otInstance aInstance, otMessage aMessage, const otMessageInfo *aMessageInfo)

Detailed Description

This module includes functions that control CoAP Secure (CoAP over DTLS) communication.

The functions in this module are available when application-coap-secure feature (OPENTHREAD_ENABLE_APPLICATION_COAP_SECURE) is enabled.

Typedef Documentation

typedef void(* otHandleCoapSecureClientConnect)(bool aConnected, void *aContext)

This function pointer is called when the DTLS connection state changes.

Parameters

[in]	aConnected	true, if a connection was established, false otherwise.
[in]	aContext	A pointer to arbitrary context information.

Function Documentation

otError otCoapSecureAddResource	(	otInstance *	aInstance,
		otCoapResource *	aResource
	)

This function adds a resource to the CoAP Secure server.

Parameters

[in]	aInstance	A pointer to an OpenThread instance.
[in]	aResource	A pointer to the resource.

Return values

OT_ERROR_NONE	Successfully added `aResource`.
OT_ERROR_ALREADY	The `aResource` was already added.

otError otCoapSecureConnect	(	otInstance *	aInstance,
		const otSockAddr *	aSockAddr,
		otHandleCoapSecureClientConnect	aHandler,
		void *	aContext
	)

This method initializes DTLS session with a peer.

Parameters

[in]	aInstance	A pointer to an OpenThread instance.
[in]	aSockAddr	A pointer to the remote sockaddr.
[in]	aHandler	A pointer to a function that will be called when the DTLS connection state changes.
[in]	aContext	A pointer to arbitrary context information.

Return values

OT_ERROR_NONE Successfully started DTLS connection.

void otCoapSecureDisconnect ( otInstance * aInstance )

This method stops the DTLS connection.

Parameters

[in] aInstance A pointer to an OpenThread instance.

otError otCoapSecureGetPeerCertificateBase64	(	otInstance *	aInstance,
		unsigned char *	aPeerCert,
		size_t *	aCertLength,
		size_t	aCertBufferSize
	)

This method returns the peer x509 certificate base64 encoded.

Parameters

[in]	aInstance	A pointer to an OpenThread instance.
[out]	aPeerCert	A pointer to the base64 encoded certificate buffer.
[out]	aCertLength	The length of the base64 encoded peer certificate.
[in]	aCertBufferSize	The buffer size of aPeerCert.

Return values

OT_ERROR_NONE	Successfully get the peer certificate.
OT_ERROR_DISABLED_FEATURE	Mbedtls config not enabled MBEDTLS_BASE64_C.

bool otCoapSecureIsConnected ( otInstance * aInstance )

This method indicates whether or not the DTLS session is connected.

Parameters

[in] aInstance A pointer to an OpenThread instance.

Return values

TRUE	The DTLS session is connected.
FALSE	The DTLS session is not connected.

bool otCoapSecureIsConnectionActive ( otInstance * aInstance )

This method indicates whether or not the DTLS session is active.

Parameters

[in] aInstance A pointer to an OpenThread instance.

Return values

TRUE	If DTLS session is active.
FALSE	If DTLS session is not active.

void otCoapSecureRemoveResource	(	otInstance *	aInstance,
		otCoapResource *	aResource
	)

This function removes a resource from the CoAP Secure server.

Parameters

[in]	aInstance	A pointer to an OpenThread instance.
[in]	aResource	A pointer to the resource.

otError otCoapSecureSendRequest	(	otInstance *	aInstance,
		otMessage *	aMessage,
		otCoapResponseHandler	aHandler,
		void *	aContext
	)

This method sends a CoAP request over secure DTLS connection.

If a response for a request is expected, respective function and context information should be provided. If no response is expected, these arguments should be NULL pointers. If Message Id was not set in the header (equal to 0), this function will assign unique Message Id to the message.

Parameters

[in]	aInstance	A pointer to an OpenThread instance.
[in]	aMessage	A reference to the message to send.
[in]	aHandler	A function pointer that shall be called on response reception or time-out.
[in]	aContext	A pointer to arbitrary context information.

Return values

OT_ERROR_NONE	Successfully sent CoAP message.
OT_ERROR_NO_BUFS	Failed to allocate retransmission data.
OT_ERROR_INVALID_STATE	DTLS connection was not initialized.

otError otCoapSecureSendResponse	(	otInstance *	aInstance,
		otMessage *	aMessage,
		const otMessageInfo *	aMessageInfo
	)

This function sends a CoAP response from the CoAP Secure server.

Parameters

[in]	aInstance	A pointer to an OpenThread instance.
[in]	aMessage	A pointer to the CoAP response to send.
[in]	aMessageInfo	A pointer to the message info associated with `aMessage`.

Return values

OT_ERROR_NONE	Successfully enqueued the CoAP response message.
OT_ERROR_NO_BUFS	Insufficient buffers available to send the CoAP response.

otError otCoapSecureSetCaCertificateChain	(	otInstance *	aInstance,
		const uint8_t *	aX509CaCertificateChain,
		uint32_t	aX509CaCertChainLength
	)

This method sets the trusted top level CAs. It is needed for validating the certificate of the peer.

DTLS mode "ECDHE ECDSA with AES 128 CCM 8" for Application CoAPS.

Parameters

[in]	aInstance	A pointer to an OpenThread instance.
[in]	aX509CaCertificateChain	A pointer to the PEM formatted X509 CA chain.
[in]	aX509CaCertChainLength	The length of chain.

Return values

OT_ERROR_NONE Successfully set the trusted top level CAs.

otError otCoapSecureSetCertificate	(	otInstance *	aInstance,
		const uint8_t *	aX509Cert,
		uint32_t	aX509Length,
		const uint8_t *	aPrivateKey,
		uint32_t	aPrivateKeyLength
	)

This method sets the local device's X509 certificate with corresponding private key for DTLS session with DTLS_ECDHE_ECDSA_WITH_AES_128_CCM_8.

Parameters

[in]	aInstance	A pointer to an OpenThread instance.
[in]	aX509Cert	A pointer to the PEM formatted X509 certificate.
[in]	aX509Length	The length of certificate.
[in]	aPrivateKey	A pointer to the PEM formatted private key.
[in]	aPrivateKeyLength	The length of the private key.

Return values

OT_ERROR_NONE	Successfully set the x509 certificate with his private key.
OT_ERROR_DISABLED_FEATURE	Mbedtls config not enabled MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED.

void otCoapSecureSetClientConnectedCallback	(	otInstance *	aInstance,
		otHandleCoapSecureClientConnect	aHandler,
		void *	aContext
	)

This method sets the connected callback to indicate, when a Client connect to the CoAP Secure server.

Parameters

[in]	aInstance	A pointer to an OpenThread instance.
[in]	aHandler	A pointer to a function that will be called once DTLS connection is established.
[in]	aContext	A pointer to arbitrary context information. May be NULL if not used.

void otCoapSecureSetDefaultHandler	(	otInstance *	aInstance,
		otCoapRequestHandler	aHandler,
		void *	aContext
	)

This function sets the default handler for unhandled CoAP Secure requests.

Parameters

[in]	aInstance	A pointer to an OpenThread instance.
[in]	aHandler	A function pointer that shall be called when an unhandled request arrives.
[in]	aContext	A pointer to arbitrary context information. May be NULL if not used.

otError otCoapSecureSetPsk	(	otInstance *	aInstance,
		const uint8_t *	aPsk,
		uint16_t	aPskLength,
		const uint8_t *	aPskIdentity,
		uint16_t	aPskIdLength
	)

This method sets the Pre-Shared Key (PSK) and cipher suite DTLS_PSK_WITH_AES_128_CCM_8.

Parameters

[in]	aInstance	A pointer to an OpenThread instance.
[in]	aPsk	A pointer to the PSK.
[in]	aPskLength	The PSK length.
[in]	aPskIdentity	The Identity Name for the PSK.
[in]	aPskIdLength	The PSK Identity Length.

Return values

OT_ERROR_NONE	Successfully set the PSK.
OT_ERROR_INVALID_ARGS	The PSK is invalid.
OT_ERROR_DISABLED_FEATURE	Mbedtls config not enabled MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED

void otCoapSecureSetSslAuthMode	(	otInstance *	aInstance,
		bool	aVerifyPeerCertificate
	)

This method sets the authentication mode for the coap secure connection.

Disable or enable the verification of peer certificate. Must be called before start.

Parameters

[in]	aInstance	A pointer to an OpenThread instance.
[in]	aVerifyPeerCertificate	true, to verify the peer certificate.

otError otCoapSecureStart	(	otInstance *	aInstance,
		uint16_t	aPort
	)

This function starts the CoAP Secure service.

Parameters

[in]	aInstance	A pointer to an OpenThread instance.
[in]	aPort	The local UDP port to bind to.

Return values

OT_ERROR_NONE Successfully started the CoAP Secure server.

void otCoapSecureStop ( otInstance * aInstance )

This function stops the CoAP Secure server.

Parameters

[in] aInstance A pointer to an OpenThread instance.

Macros

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation