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

otCoapSecureAutoStopCallback)(void *aContext) typedef
void(*
Callback function pointer to notify when the CoAP secure agent is automatically stopped due to reaching the maximum number of connection attempts.
otHandleCoapSecureClientConnect)(bool aConnected, void *aContext) typedef
void(*
Pointer is called when the DTLS connection state changes.

Functions

otCoapSecureAddBlockWiseResource(otInstance *aInstance, otCoapBlockwiseResource *aResource)
void
Adds a block-wise resource to the CoAP Secure server.
otCoapSecureAddResource(otInstance *aInstance, otCoapResource *aResource)
void
Adds a resource to the CoAP Secure server.
otCoapSecureConnect(otInstance *aInstance, const otSockAddr *aSockAddr, otHandleCoapSecureClientConnect aHandler, void *aContext)
Initializes DTLS session with a peer.
otCoapSecureDisconnect(otInstance *aInstance)
void
Stops the DTLS connection.
otCoapSecureGetPeerCertificateBase64(otInstance *aInstance, unsigned char *aPeerCert, size_t *aCertLength, size_t aCertBufferSize)
Returns the peer x509 certificate base64 encoded.
otCoapSecureIsClosed(otInstance *aInstance)
bool
Indicates whether or not the DTLS session is closed.
otCoapSecureIsConnected(otInstance *aInstance)
bool
Indicates whether or not the DTLS session is connected.
otCoapSecureIsConnectionActive(otInstance *aInstance)
bool
Indicates whether or not the DTLS session is active.
otCoapSecureRemoveBlockWiseResource(otInstance *aInstance, otCoapBlockwiseResource *aResource)
void
Removes a block-wise resource from the CoAP Secure server.
otCoapSecureRemoveResource(otInstance *aInstance, otCoapResource *aResource)
void
Removes a resource from the CoAP Secure server.
otCoapSecureSendRequest(otInstance *aInstance, otMessage *aMessage, otCoapResponseHandler aHandler, void *aContext)
Sends a CoAP request over secure DTLS connection.
otCoapSecureSendRequestBlockWise(otInstance *aInstance, otMessage *aMessage, otCoapResponseHandler aHandler, void *aContext, otCoapBlockwiseTransmitHook aTransmitHook, otCoapBlockwiseReceiveHook aReceiveHook)
Sends a CoAP request block-wise over secure DTLS connection.
otCoapSecureSendResponse(otInstance *aInstance, otMessage *aMessage, const otMessageInfo *aMessageInfo)
Sends a CoAP response from 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.
otCoapSecureSetCaCertificateChain(otInstance *aInstance, const uint8_t *aX509CaCertificateChain, uint32_t aX509CaCertChainLength)
void
Sets the trusted top level CAs.
otCoapSecureSetCertificate(otInstance *aInstance, const uint8_t *aX509Cert, uint32_t aX509Length, const uint8_t *aPrivateKey, uint32_t aPrivateKeyLength)
void
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
Sets the connected callback to indicate, when a Client connect to the CoAP Secure server.
otCoapSecureSetDefaultHandler(otInstance *aInstance, otCoapRequestHandler aHandler, void *aContext)
void
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
Sets the Pre-Shared Key (PSK) and cipher suite DTLS_PSK_WITH_AES_128_CCM_8.
otCoapSecureSetSslAuthMode(otInstance *aInstance, bool aVerifyPeerCertificate)
void
Sets the authentication mode for the coap secure connection.
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.
otCoapSecureStop(otInstance *aInstance)
void
Stops the CoAP Secure server.

Macros

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

Typedefs

otCoapSecureAutoStopCallback

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.

Details
Parameters
[in] aContext
A pointer to arbitrary context information.

otHandleCoapSecureClientConnect

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

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
)

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
)

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
)

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
)

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
)

Returns the peer x509 certificate base64 encoded.

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.

otCoapSecureIsClosed

bool otCoapSecureIsClosed(
  otInstance *aInstance
)

Indicates whether or not the DTLS session is closed.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Return Values
TRUE
The DTLS session is closed.
FALSE
The DTLS session is not closed.

otCoapSecureIsConnected

bool otCoapSecureIsConnected(
  otInstance *aInstance
)

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
)

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
)

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
)

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
)

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
)

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

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.

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
)

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
)

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

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
)

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.

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
)

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

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
)

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
)

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
)

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

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
)

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
)

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.

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.

Details
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.
Return Values
OT_ERROR_NONE
Successfully started the CoAP agent.
OT_ERROR_ALREADY
Already started.

otCoapSecureStop

void otCoapSecureStop(
  otInstance *aInstance
)

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.