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

CoAP secure connection event types.

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

Pointer is called when the DTLS connection state changes.

typedef void(*

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

Functions#

otCoapSecureStart(otInstance *aInstance, uint16_t aPort)

Starts the CoAP Secure service.

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.

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.

bool
otCoapSecureIsClosed(otInstance *aInstance)

Indicates whether or not the DTLS session is closed.

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

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.

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.


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

Typedef Documentation#

otCoapSecureConnectEvent#

typedef enum otCoapSecureConnectEvent otCoapSecureConnectEvent

CoAP secure connection event types.


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

otHandleCoapSecureClientConnect#

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

Pointer is called when the DTLS connection state changes.

Parameters
[in]aEvent

The connection event.

[in]aContext

A pointer to arbitrary context information.


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

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
[in]aContext

A pointer to arbitrary context information.


Definition at line 95 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 105 of file include/openthread/coap_secure.h

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
[in]aInstance

A pointer to an OpenThread instance.

[in]aPort

The local UDP port to bind to.

[in]aMaxAttempts

Maximum number of allowed connection request attempts. Zero indicates no limit.

[in]aCallback

Callback to notify if max number of attempts has reached and agent is stopped.

[in]aContext

A pointer to arbitrary context to use with aCallback.


Definition at line 120 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 131 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 145 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 166 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 180 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 194 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 212 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 227 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 237 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 247 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 257 of file include/openthread/coap_secure.h

otCoapSecureIsClosed#

bool otCoapSecureIsClosed (otInstance * aInstance)

Indicates whether or not the DTLS session is closed.

Parameters
[in]aInstance

A pointer to an OpenThread instance.


Definition at line 267 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 290 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 313 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 324 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 332 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 340 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 348 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 357 of file include/openthread/coap_secure.h

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
[in]aInstance

A pointer to an OpenThread instance.

[in]aHandler

A pointer to a function that will be called once DTLS connection has changed.

[in]aContext

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


Definition at line 367 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 386 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 402 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 67 of file include/openthread/coap_secure.h