CoAP Secure

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

Summary

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

Typedefs
`otHandleCoapSecureClientConnect)(bool aConnected, void *aContext)`	typedef `void(*` This function pointer is called when the DTLS connection state changes.

Functions
`otCoapSecureAddBlockWiseResource(otInstance aInstance, otCoapBlockwiseResource aResource)`	`void` This function adds a block-wise resource to the CoAP Secure server.
`otCoapSecureAddResource(otInstance aInstance, otCoapResource aResource)`	`void` This function adds a resource to the CoAP Secure server.
`otCoapSecureConnect(otInstance aInstance, const otSockAddr aSockAddr, otHandleCoapSecureClientConnect aHandler, void *aContext)`	`otError` This method initializes DTLS session with a peer.
`otCoapSecureDisconnect(otInstance *aInstance)`	`void` This method stops the DTLS connection.
`otCoapSecureGetPeerCertificateBase64(otInstance aInstance, unsigned char aPeerCert, size_t *aCertLength, size_t aCertBufferSize)`	`otError` This method returns the peer x509 certificate base64 encoded.
`otCoapSecureIsConnected(otInstance *aInstance)`	`bool` This method indicates whether or not the DTLS session is connected.
`otCoapSecureIsConnectionActive(otInstance *aInstance)`	`bool` This method indicates whether or not the DTLS session is active.
`otCoapSecureRemoveBlockWiseResource(otInstance aInstance, otCoapBlockwiseResource aResource)`	`void` This function removes a block-wise resource from the CoAP Secure server.
`otCoapSecureRemoveResource(otInstance aInstance, otCoapResource aResource)`	`void` This function removes a resource from the CoAP Secure server.
`otCoapSecureSendRequest(otInstance aInstance, otMessage aMessage, otCoapResponseHandler aHandler, void *aContext)`	`otError` This method sends a CoAP request over secure DTLS connection.
`otCoapSecureSendRequestBlockWise(otInstance aInstance, otMessage aMessage, otCoapResponseHandler aHandler, void *aContext, otCoapBlockwiseTransmitHook aTransmitHook, otCoapBlockwiseReceiveHook aReceiveHook)`	`otError` This method sends a CoAP request block-wise over secure DTLS connection.
`otCoapSecureSendResponse(otInstance aInstance, otMessage aMessage, const otMessageInfo *aMessageInfo)`	`otError` This function sends a CoAP response from the CoAP Secure server.
`otCoapSecureSendResponseBlockWise(otInstance aInstance, otMessage aMessage, const otMessageInfo aMessageInfo, void aContext, otCoapBlockwiseTransmitHook aTransmitHook)`	`otError` This function sends a CoAP response block-wise from the CoAP Secure server.
`otCoapSecureSetCaCertificateChain(otInstance aInstance, const uint8_t aX509CaCertificateChain, uint32_t aX509CaCertChainLength)`	`void` This method sets the trusted top level CAs.
`otCoapSecureSetCertificate(otInstance aInstance, const uint8_t aX509Cert, uint32_t aX509Length, const uint8_t *aPrivateKey, uint32_t aPrivateKeyLength)`	`void` 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.
`otCoapSecureSetClientConnectedCallback(otInstance aInstance, otHandleCoapSecureClientConnect aHandler, void aContext)`	`void` This method sets the connected callback to indicate, when a Client connect to the CoAP Secure server.
`otCoapSecureSetDefaultHandler(otInstance aInstance, otCoapRequestHandler aHandler, void aContext)`	`void` This function sets the default handler for unhandled CoAP Secure requests.
`otCoapSecureSetPsk(otInstance aInstance, const uint8_t aPsk, uint16_t aPskLength, const uint8_t *aPskIdentity, uint16_t aPskIdLength)`	`void` This method sets the Pre-Shared Key (PSK) and cipher suite DTLS_PSK_WITH_AES_128_CCM_8.
`otCoapSecureSetSslAuthMode(otInstance *aInstance, bool aVerifyPeerCertificate)`	`void` This method sets the authentication mode for the coap secure connection.
`otCoapSecureStart(otInstance *aInstance, uint16_t aPort)`	`otError` This function starts the CoAP Secure service.
`otCoapSecureStop(otInstance *aInstance)`	`void` This function stops the CoAP Secure server.

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

Typedefs

otHandleCoapSecureClientConnect

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

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

Details

Parameters

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

Functions

otCoapSecureAddBlockWiseResource

void otCoapSecureAddBlockWiseResource(
  otInstance *aInstance,
  otCoapBlockwiseResource *aResource
)

This function adds a block-wise resource to the CoAP Secure server.

Details

Parameters

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

otCoapSecureAddResource

void otCoapSecureAddResource(
  otInstance *aInstance,
  otCoapResource *aResource
)

This function adds a resource to the CoAP Secure server.

Details

Parameters

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

otCoapSecureConnect

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

This method initializes DTLS session with a peer.

Details

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.

Return Values

OT_ERROR_NONE

Successfully started DTLS connection.

otCoapSecureDisconnect

void otCoapSecureDisconnect(
  otInstance *aInstance
)

This method stops the DTLS connection.

Details

Parameters

[in] aInstance

A pointer to an OpenThread instance.

otCoapSecureGetPeerCertificateBase64

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

This method returns the peer x509 certificate base64 encoded.

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

Details

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_INVALID_STATE`	Not connected yet.
`OT_ERROR_NONE`	Successfully get the peer certificate.
`OT_ERROR_NO_BUFS`	Can't allocate memory for certificate.

otCoapSecureIsConnected

bool otCoapSecureIsConnected(
  otInstance *aInstance
)

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

Details

Parameters

[in] aInstance

A pointer to an OpenThread instance.

Return Values

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

otCoapSecureIsConnectionActive

bool otCoapSecureIsConnectionActive(
  otInstance *aInstance
)

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

Details

Parameters

[in] aInstance

A pointer to an OpenThread instance.

Return Values

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

otCoapSecureRemoveBlockWiseResource

void otCoapSecureRemoveBlockWiseResource(
  otInstance *aInstance,
  otCoapBlockwiseResource *aResource
)

This function removes a block-wise resource from the CoAP Secure server.

Details

Parameters

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

otCoapSecureRemoveResource

void otCoapSecureRemoveResource(
  otInstance *aInstance,
  otCoapResource *aResource
)

This function removes a resource from the CoAP Secure server.

Details

Parameters

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

otCoapSecureSendRequest

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.

Details

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.

otCoapSecureSendRequestBlockWise

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

This method sends a CoAP request block-wise over secure DTLS connection.

This function is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration is enabled.

Details

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.

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.

otCoapSecureSendResponse

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

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

Details

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.

otCoapSecureSendResponseBlockWise

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

This function sends a CoAP response block-wise from the CoAP Secure server.

This function is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration is enabled.

Details

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.

Return Values

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

otCoapSecureSetCaCertificateChain

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

Note: This function requires MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED=1.

Details

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.

otCoapSecureSetCertificate

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

Note: This function requires MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED=1.

Details

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.

otCoapSecureSetClientConnectedCallback

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.

Details

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.

otCoapSecureSetDefaultHandler

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

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

Details

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.

otCoapSecureSetPsk

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

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

Details

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.

otCoapSecureSetSslAuthMode

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.

Details

Parameters

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

otCoapSecureStart

otError otCoapSecureStart(
  otInstance *aInstance,
  uint16_t aPort
)

This function starts the CoAP Secure service.

Details

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.

otCoapSecureStop

void otCoapSecureStop(
  otInstance *aInstance
)

This function stops the CoAP Secure server.

Details

Parameters

[in] aInstance

A pointer to an OpenThread instance.

Macros

OT_DEFAULT_COAP_SECURE_PORT

 OT_DEFAULT_COAP_SECURE_PORT 5684

Default CoAP Secure port, as specified in RFC 7252.

Resources

OpenThread API Reference topics originate from the source code, available on GitHub. For more information, or to contribute to our documentation, refer to Resources.