CoAP Secure#

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

The functions in this module are available when CoAP Secure API feature (OPENTHREAD_CONFIG_COAP_SECURE_API_ENABLE) is enabled.

Enumerations#

enum

otCoapSecureConnectEvent {

OT_COAP_SECURE_CONNECTED = 0

OT_COAP_SECURE_DISCONNECTED_PEER_CLOSED

OT_COAP_SECURE_DISCONNECTED_LOCAL_CLOSED

OT_COAP_SECURE_DISCONNECTED_MAX_ATTEMPTS

OT_COAP_SECURE_DISCONNECTED_ERROR

}

CoAP secure connection event types.

Typedefs#

typedef enum otCoapSecureConnectEvent

otCoapSecureConnectEvent

CoAP secure connection event types.

typedef void(*

otHandleCoapSecureClientConnect)(otCoapSecureConnectEvent aEvent, void *aContext)

Pointer is called when the DTLS connection state changes.

typedef void(*

otCoapSecureAutoStopCallback)(void *aContext)

Callback function pointer to notify when the CoAP secure agent is automatically stopped due to reaching the maximum number of connection attempts.

Functions#

otError

otCoapSecureStart(otInstance *aInstance, uint16_t aPort)

Starts the CoAP Secure service.

otError

otCoapSecureStartWithMaxConnAttempts(otInstance *aInstance, uint16_t aPort, uint16_t aMaxAttempts, otCoapSecureAutoStopCallback aCallback, void *aContext)

Starts the CoAP secure service and sets the maximum number of allowed connection attempts before stopping the agent automatically.

void

otCoapSecureStop(otInstance *aInstance)

Stops the CoAP Secure server.

void

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

Sets the Pre-Shared Key (PSK) and cipher suite DTLS_PSK_WITH_AES_128_CCM_8.

otError

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

Returns the peer x509 certificate base64 encoded.

void

otCoapSecureSetSslAuthMode(otInstance *aInstance, bool aVerifyPeerCertificate)

Sets the authentication mode for the coap secure connection.

void

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

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

void

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

Sets the trusted top level CAs.

otError

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

Initializes DTLS session with a peer.

void

otCoapSecureDisconnect(otInstance *aInstance)

Stops the DTLS connection.

bool

otCoapSecureIsConnected(otInstance *aInstance)

Indicates whether or not the DTLS session is connected.

bool

otCoapSecureIsConnectionActive(otInstance *aInstance)

Indicates whether or not the DTLS session is active.

bool

otCoapSecureIsClosed(otInstance *aInstance)

Indicates whether or not the DTLS session is closed.

otError

otCoapSecureSendRequestBlockWise(otInstance *aInstance, otMessage *aMessage, otCoapResponseHandler aHandler, void *aContext, otCoapBlockwiseTransmitHook aTransmitHook, otCoapBlockwiseReceiveHook aReceiveHook)

Sends a CoAP request block-wise over secure DTLS connection.

otError

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

Sends a CoAP request over secure DTLS connection.

void

otCoapSecureAddResource(otInstance *aInstance, otCoapResource *aResource)

Adds a resource to the CoAP Secure server.

void

otCoapSecureRemoveResource(otInstance *aInstance, otCoapResource *aResource)

Removes a resource from the CoAP Secure server.

void

otCoapSecureAddBlockWiseResource(otInstance *aInstance, otCoapBlockwiseResource *aResource)

Adds a block-wise resource to the CoAP Secure server.

void

otCoapSecureRemoveBlockWiseResource(otInstance *aInstance, otCoapBlockwiseResource *aResource)

Removes a block-wise resource from the CoAP Secure server.

void

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

Sets the default handler for unhandled CoAP Secure requests.

void

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

Sets the connect event callback to indicate when a Client connection to the CoAP Secure server has changed.

otError

otCoapSecureSendResponseBlockWise(otInstance *aInstance, otMessage *aMessage, const otMessageInfo *aMessageInfo, void *aContext, otCoapBlockwiseTransmitHook aTransmitHook)

Sends a CoAP response block-wise from the CoAP Secure server.

otError

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

Sends a CoAP response from the CoAP Secure server.

Macros#

#define

OT_DEFAULT_COAP_SECURE_PORT 5684

Default CoAP Secure port, as specified in RFC 7252.

Enumeration Documentation#

otCoapSecureConnectEvent#

otCoapSecureConnectEvent

CoAP secure connection event types.

Enumerator
OT_COAP_SECURE_CONNECTED	Connection established.
OT_COAP_SECURE_DISCONNECTED_PEER_CLOSED	Disconnected by peer.
OT_COAP_SECURE_DISCONNECTED_LOCAL_CLOSED	Disconnected locally.
OT_COAP_SECURE_DISCONNECTED_MAX_ATTEMPTS	Disconnected due to reaching the max connection attempts.
OT_COAP_SECURE_DISCONNECTED_ERROR	Disconnected due to an error.

Typedef Documentation#

otCoapSecureConnectEvent#

typedef enum otCoapSecureConnectEvent otCoapSecureConnectEvent

CoAP secure connection event types.

otHandleCoapSecureClientConnect#

typedef void(* otHandleCoapSecureClientConnect) (otCoapSecureConnectEvent aEvent, void *aContext) )(otCoapSecureConnectEvent aEvent, void *aContext)

Pointer is called when the DTLS connection state changes.

Parameters

Type	Direction	Argument Name	Description
	[in]	aEvent	The connection event.
	[in]	aContext	A pointer to arbitrary context information.

otCoapSecureAutoStopCallback#

typedef void(* otCoapSecureAutoStopCallback) (void *aContext) )(void *aContext)

Callback function pointer to notify when the CoAP secure agent is automatically stopped due to reaching the maximum number of connection attempts.

Parameters

Type	Direction	Argument Name	Description
	[in]	aContext	A pointer to arbitrary context information.

Function Documentation#

otCoapSecureStart#

otError otCoapSecureStart (otInstance * aInstance, uint16_t aPort)

Starts the CoAP Secure service.

Parameters

Type	Direction	Argument Name	Description
otInstance *	[in]	aInstance	A pointer to an OpenThread instance.
uint16_t	[in]	aPort	The local UDP port to bind to.

otCoapSecureStartWithMaxConnAttempts#

otError otCoapSecureStartWithMaxConnAttempts (otInstance * aInstance, uint16_t aPort, uint16_t aMaxAttempts, otCoapSecureAutoStopCallback aCallback, void * aContext)

Starts the CoAP secure service and sets the maximum number of allowed connection attempts before stopping the agent automatically.

Parameters

Type	Direction	Argument Name	Description
otInstance *	[in]	aInstance	A pointer to an OpenThread instance.
uint16_t	[in]	aPort	The local UDP port to bind to.
uint16_t	[in]	aMaxAttempts	Maximum number of allowed connection request attempts. Zero indicates no limit.
otCoapSecureAutoStopCallback	[in]	aCallback	Callback to notify if max number of attempts has reached and agent is stopped.
void *	[in]	aContext	A pointer to arbitrary context to use with `aCallback`.

otCoapSecureStop#

void otCoapSecureStop (otInstance * aInstance)

Stops the CoAP Secure server.

Parameters

Type	Direction	Argument Name	Description
otInstance *	[in]	aInstance	A pointer to an OpenThread instance.

otCoapSecureSetPsk#

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

Sets the Pre-Shared Key (PSK) and cipher suite DTLS_PSK_WITH_AES_128_CCM_8.

Parameters

Type	Direction	Argument Name	Description
otInstance *	[in]	aInstance	A pointer to an OpenThread instance.
const uint8_t *	[in]	aPsk	A pointer to the PSK.
uint16_t	[in]	aPskLength	The PSK length.
const uint8_t *	[in]	aPskIdentity	The Identity Name for the PSK.
uint16_t	[in]	aPskIdLength	The PSK Identity Length.

Note

This function requires the build-time feature MBEDTLS_KEY_EXCHANGE_PSK_ENABLED to be enabled.

otCoapSecureGetPeerCertificateBase64#

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

Returns the peer x509 certificate base64 encoded.

Parameters

Type	Direction	Argument Name	Description
otInstance *	[in]	aInstance	A pointer to an OpenThread instance.
unsigned char *	[out]	aPeerCert	A pointer to the base64 encoded certificate buffer.
size_t *	[out]	aCertLength	The length of the base64 encoded peer certificate.
size_t	[in]	aCertBufferSize	The buffer size of aPeerCert.

Note

This function requires the build-time features MBEDTLS_BASE64_C and MBEDTLS_SSL_KEEP_PEER_CERTIFICATE to be enabled.

otCoapSecureSetSslAuthMode#

void otCoapSecureSetSslAuthMode (otInstance * aInstance, bool aVerifyPeerCertificate)

Sets the authentication mode for the coap secure connection.

Parameters

Type	Direction	Argument Name	Description
otInstance *	[in]	aInstance	A pointer to an OpenThread instance.
bool	[in]	aVerifyPeerCertificate	true, to verify the peer certificate.

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

otCoapSecureSetCertificate#

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

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

Parameters

Type	Direction	Argument Name	Description
otInstance *	[in]	aInstance	A pointer to an OpenThread instance.
const uint8_t *	[in]	aX509Cert	A pointer to the PEM formatted X509 certificate.
uint32_t	[in]	aX509Length	The length of certificate.
const uint8_t *	[in]	aPrivateKey	A pointer to the PEM formatted private key.
uint32_t	[in]	aPrivateKeyLength	The length of the private key.

Note

This function requires MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED=1.

otCoapSecureSetCaCertificateChain#

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

Sets the trusted top level CAs.

Parameters

Type	Direction	Argument Name	Description
otInstance *	[in]	aInstance	A pointer to an OpenThread instance.
const uint8_t *	[in]	aX509CaCertificateChain	A pointer to the PEM formatted X509 CA chain.
uint32_t	[in]	aX509CaCertChainLength	The length of chain.

It is needed for validating the certificate of the peer.

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

Note

This function requires MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED=1.

otCoapSecureConnect#

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

Initializes DTLS session with a peer.

Parameters

Type	Direction	Argument Name	Description
otInstance *	[in]	aInstance	A pointer to an OpenThread instance.
const otSockAddr *	[in]	aSockAddr	A pointer to the remote socket address.
otHandleCoapSecureClientConnect	[in]	aHandler	A pointer to a function that will be called when the DTLS connection state changes.
void *	[in]	aContext	A pointer to arbitrary context information.

otCoapSecureDisconnect#

void otCoapSecureDisconnect (otInstance * aInstance)

Stops the DTLS connection.

Parameters

Type	Direction	Argument Name	Description
otInstance *	[in]	aInstance	A pointer to an OpenThread instance.

otCoapSecureIsConnected#

bool otCoapSecureIsConnected (otInstance * aInstance)

Indicates whether or not the DTLS session is connected.

Parameters

Type	Direction	Argument Name	Description
otInstance *	[in]	aInstance	A pointer to an OpenThread instance.

otCoapSecureIsConnectionActive#

bool otCoapSecureIsConnectionActive (otInstance * aInstance)

Indicates whether or not the DTLS session is active.

Parameters

Type	Direction	Argument Name	Description
otInstance *	[in]	aInstance	A pointer to an OpenThread instance.

otCoapSecureIsClosed#

bool otCoapSecureIsClosed (otInstance * aInstance)

Indicates whether or not the DTLS session is closed.

Parameters

Type	Direction	Argument Name	Description
otInstance *	[in]	aInstance	A pointer to an OpenThread instance.

otCoapSecureSendRequestBlockWise#

otError otCoapSecureSendRequestBlockWise (otInstance * aInstance, otMessage * aMessage, otCoapResponseHandler aHandler, void * aContext, otCoapBlockwiseTransmitHook aTransmitHook, otCoapBlockwiseReceiveHook aReceiveHook)

Sends a CoAP request block-wise over secure DTLS connection.

Parameters

Type	Direction	Argument Name	Description
otInstance *	[in]	aInstance	A pointer to an OpenThread instance.
otMessage *	[in]	aMessage	A reference to the message to send.
otCoapResponseHandler	[in]	aHandler	A function pointer that shall be called on response reception or time-out.
void *	[in]	aContext	A pointer to arbitrary context information.
otCoapBlockwiseTransmitHook	[in]	aTransmitHook	A function pointer that is called on Block1 response reception.
otCoapBlockwiseReceiveHook	[in]	aReceiveHook	A function pointer that is called on Block2 response reception.

Is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration is enabled.

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.

otCoapSecureSendRequest#

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

Sends a CoAP request over secure DTLS connection.

Parameters

Type	Direction	Argument Name	Description
otInstance *	[in]	aInstance	A pointer to an OpenThread instance.
otMessage *	[in]	aMessage	A reference to the message to send.
otCoapResponseHandler	[in]	aHandler	A function pointer that shall be called on response reception or time-out.
void *	[in]	aContext	A pointer to arbitrary context information.

otCoapSecureAddResource#

void otCoapSecureAddResource (otInstance * aInstance, otCoapResource * aResource)

Adds a resource to the CoAP Secure server.

Parameters

Type	Direction	Argument Name	Description
otInstance *	[in]	aInstance	A pointer to an OpenThread instance.
otCoapResource *	[in]	aResource	A pointer to the resource.

otCoapSecureRemoveResource#

void otCoapSecureRemoveResource (otInstance * aInstance, otCoapResource * aResource)

Removes a resource from the CoAP Secure server.

Parameters

Type	Direction	Argument Name	Description
otInstance *	[in]	aInstance	A pointer to an OpenThread instance.
otCoapResource *	[in]	aResource	A pointer to the resource.

otCoapSecureAddBlockWiseResource#

void otCoapSecureAddBlockWiseResource (otInstance * aInstance, otCoapBlockwiseResource * aResource)

Adds a block-wise resource to the CoAP Secure server.

Parameters

Type	Direction	Argument Name	Description
otInstance *	[in]	aInstance	A pointer to an OpenThread instance.
otCoapBlockwiseResource *	[in]	aResource	A pointer to the resource.

otCoapSecureRemoveBlockWiseResource#

void otCoapSecureRemoveBlockWiseResource (otInstance * aInstance, otCoapBlockwiseResource * aResource)

Removes a block-wise resource from the CoAP Secure server.

Parameters

Type	Direction	Argument Name	Description
otInstance *	[in]	aInstance	A pointer to an OpenThread instance.
otCoapBlockwiseResource *	[in]	aResource	A pointer to the resource.

otCoapSecureSetDefaultHandler#

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

Sets the default handler for unhandled CoAP Secure requests.

Parameters

Type	Direction	Argument Name	Description
otInstance *	[in]	aInstance	A pointer to an OpenThread instance.
otCoapRequestHandler	[in]	aHandler	A function pointer that shall be called when an unhandled request arrives.
void *	[in]	aContext	A pointer to arbitrary context information. May be NULL if not used.

otCoapSecureSetClientConnectEventCallback#

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

Sets the connect event callback to indicate when a Client connection to the CoAP Secure server has changed.

Parameters

Type	Direction	Argument Name	Description
otInstance *	[in]	aInstance	A pointer to an OpenThread instance.
otHandleCoapSecureClientConnect	[in]	aHandler	A pointer to a function that will be called once DTLS connection has changed.
void *	[in]	aContext	A pointer to arbitrary context information. May be NULL if not used.

otCoapSecureSendResponseBlockWise#

otError otCoapSecureSendResponseBlockWise (otInstance * aInstance, otMessage * aMessage, const otMessageInfo * aMessageInfo, void * aContext, otCoapBlockwiseTransmitHook aTransmitHook)

Sends a CoAP response block-wise from the CoAP Secure server.

Parameters

Type	Direction	Argument Name	Description
otInstance *	[in]	aInstance	A pointer to an OpenThread instance.
otMessage *	[in]	aMessage	A pointer to the CoAP response to send.
const otMessageInfo *	[in]	aMessageInfo	A pointer to the message info associated with `aMessage`.
void *	[in]	aContext	A pointer to arbitrary context information. May be NULL if not used.
otCoapBlockwiseTransmitHook	[in]	aTransmitHook	A function pointer that is called on Block1 request reception.

Is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration is enabled.

otCoapSecureSendResponse#

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

Sends a CoAP response from the CoAP Secure server.

Parameters

Type	Direction	Argument Name	Description
otInstance *	[in]	aInstance	A pointer to an OpenThread instance.
otMessage *	[in]	aMessage	A pointer to the CoAP response to send.
const otMessageInfo *	[in]	aMessageInfo	A pointer to the message info associated with `aMessage`.