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.

Typedefs#

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

Pointer is called when the DTLS connection state changes.

Functions#

otCoapSecureStart(otInstance *aInstance, uint16_t aPort)

Starts the CoAP Secure service.

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.

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.

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.

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

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

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
otCoapSecureSetClientConnectedCallback(otInstance *aInstance, otHandleCoapSecureClientConnect aHandler, void *aContext)

Sets the connected callback to indicate, when a Client connect to the CoAP Secure server.

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

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

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

Sends a CoAP response from the CoAP Secure server.

Macros#

#define

Default CoAP Secure port, as specified in RFC 7252.

Typedef Documentation#

otHandleCoapSecureClientConnect#

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

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.


Definition at line 77 of file include/openthread/coap_secure.h

Function Documentation#

otCoapSecureStart#

otError otCoapSecureStart (otInstance * aInstance, uint16_t aPort)

Starts the CoAP Secure service.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aPort

The local UDP port to bind to.


Definition at line 88 of file include/openthread/coap_secure.h

otCoapSecureStop#

void otCoapSecureStop (otInstance * aInstance)

Stops the CoAP Secure server.

Parameters
[in]aInstance

A pointer to an OpenThread instance.


Definition at line 96 of file include/openthread/coap_secure.h

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

Note

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


Definition at line 111 of file include/openthread/coap_secure.h

otCoapSecureGetPeerCertificateBase64#

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

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.

Note

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


Definition at line 133 of file include/openthread/coap_secure.h

otCoapSecureSetSslAuthMode#

void otCoapSecureSetSslAuthMode (otInstance * aInstance, bool aVerifyPeerCertificate)

Sets the authentication mode for the coap secure connection.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aVerifyPeerCertificate

true, to verify the peer certificate.

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


Definition at line 148 of file include/openthread/coap_secure.h

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

Note

  • This function requires MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED=1.


Definition at line 163 of file include/openthread/coap_secure.h

otCoapSecureSetCaCertificateChain#

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

Sets the trusted top level CAs.

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.

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.


Definition at line 182 of file include/openthread/coap_secure.h

otCoapSecureConnect#

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

Initializes DTLS session with a peer.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aSockAddr

A pointer to the remote socket address.

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


Definition at line 198 of file include/openthread/coap_secure.h

otCoapSecureDisconnect#

void otCoapSecureDisconnect (otInstance * aInstance)

Stops the DTLS connection.

Parameters
[in]aInstance

A pointer to an OpenThread instance.


Definition at line 209 of file include/openthread/coap_secure.h

otCoapSecureIsConnected#

bool otCoapSecureIsConnected (otInstance * aInstance)

Indicates whether or not the DTLS session is connected.

Parameters
[in]aInstance

A pointer to an OpenThread instance.


Definition at line 220 of file include/openthread/coap_secure.h

otCoapSecureIsConnectionActive#

bool otCoapSecureIsConnectionActive (otInstance * aInstance)

Indicates whether or not the DTLS session is active.

Parameters
[in]aInstance

A pointer to an OpenThread instance.


Definition at line 231 of file include/openthread/coap_secure.h

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

[in]aTransmitHook

A function pointer that is called on Block1 response reception.

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


Definition at line 255 of file include/openthread/coap_secure.h

otCoapSecureSendRequest#

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

Sends a CoAP request over secure DTLS connection.

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.

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.


Definition at line 279 of file include/openthread/coap_secure.h

otCoapSecureAddResource#

void otCoapSecureAddResource (otInstance * aInstance, otCoapResource * aResource)

Adds a resource to the CoAP Secure server.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aResource

A pointer to the resource.


Definition at line 291 of file include/openthread/coap_secure.h

otCoapSecureRemoveResource#

void otCoapSecureRemoveResource (otInstance * aInstance, otCoapResource * aResource)

Removes a resource from the CoAP Secure server.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aResource

A pointer to the resource.


Definition at line 300 of file include/openthread/coap_secure.h

otCoapSecureAddBlockWiseResource#

void otCoapSecureAddBlockWiseResource (otInstance * aInstance, otCoapBlockwiseResource * aResource)

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

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aResource

A pointer to the resource.


Definition at line 309 of file include/openthread/coap_secure.h

otCoapSecureRemoveBlockWiseResource#

void otCoapSecureRemoveBlockWiseResource (otInstance * aInstance, otCoapBlockwiseResource * aResource)

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

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aResource

A pointer to the resource.


Definition at line 318 of file include/openthread/coap_secure.h

otCoapSecureSetDefaultHandler#

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

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.


Definition at line 328 of file include/openthread/coap_secure.h

otCoapSecureSetClientConnectedCallback#

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

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.


Definition at line 339 of file include/openthread/coap_secure.h

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

[in]aContext

A pointer to arbitrary context information. May be NULL if not used.

[in]aTransmitHook

A function pointer that is called on Block1 request reception.

Is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration is enabled.


Definition at line 359 of file include/openthread/coap_secure.h

otCoapSecureSendResponse#

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

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.


Definition at line 376 of file include/openthread/coap_secure.h

Macro Definition Documentation#

OT_DEFAULT_COAP_SECURE_PORT#

#define OT_DEFAULT_COAP_SECURE_PORT
Value:
5684

Default CoAP Secure port, as specified in RFC 7252.


Definition at line 68 of file include/openthread/coap_secure.h