CoAP Secure

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

Summary

The functions in this module are available when application-coap-secure feature (OPENTHREAD_ENABLE_APPLICATION_COAP_SECURE) is enabled.

Typedefs

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

Functions

otCoapSecureAddResource(otInstance *aInstance, otCoapResource *aResource)
This function adds a resource to the CoAP Secure server.
otCoapSecureConnect(otInstance *aInstance, const otSockAddr *aSockAddr, otHandleCoapSecureClientConnect aHandler, void *aContext)
This method initializes DTLS session with a peer.
otCoapSecureDisconnect(otInstance *aInstance)
This method stops the DTLS connection.
otCoapSecureGetPeerCertificateBase64(otInstance *aInstance, unsigned char *aPeerCert, uint64_t *aCertLength, uint64_t aCertBufferSize)
This method returns the peer x509 certificate base64 encoded.
otCoapSecureIsConncetionActive(otInstance *aInstance)
bool
This method indicates whether or not the DTLS session is active.
otCoapSecureIsConnected(otInstance *aInstance)
bool
This method indicates whether or not the DTLS session is connected.
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)
This method sends a CoAP request over secure DTLS connection.
otCoapSecureSendResponse(otInstance *aInstance, otMessage *aMessage, const otMessageInfo *aMessageInfo)
This function sends a CoAP response from the CoAP Secure server.
otCoapSecureSetCaCertificateChain(otInstance *aInstance, const uint8_t *aX509CaCertificateChain, uint32_t aX509CaCertChainLength)
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)
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)
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, void *aContext)
This function starts the CoAP Secure service.
otCoapSecureStop(otInstance *aInstance)
This function stops the CoAP Secure server.

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

otCoapSecureAddResource

otError 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.
Return Values
OT_ERROR_NONE
Successfully added aResource.
OT_ERROR_ALREADY
The aResource was already added.

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 sockaddr.
[in] aCallback
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

otError otCoapSecureDisconnect(
  otInstance *aInstance
)

This method stops the DTLS connection.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Return Values
OT_ERROR_NONE
Successfully stopped the DTLS connection.

otCoapSecureGetPeerCertificateBase64

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

This method 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_NONE
Successfully get the peer certificate.
OT_ERROR_DISABLED_FEATURE
Mbedtls config not enabled MBEDTLS_BASE64_C.

otCoapSecureIsConncetionActive

bool otCoapSecureIsConncetionActive(
  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.

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.

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.

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.

otCoapSecureSetCaCertificateChain

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

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.
Return Values
OT_ERROR_NONE
Successfully set the the trusted top level CAs.

otCoapSecureSetCertificate

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

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aX509Certificate
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.
Return Values
OT_ERROR_NONE
Successfully set the x509 certificate with his private key.
OT_ERROR_DISABLED_FEATURE
Mbedtls config not enabled MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED.

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] aMessageInfo
A pointer to a message info structure.
[in] aHandler
A pointer to a function that will be called once DTLS connection is established.

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

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

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.
Return Values
OT_ERROR_NONE
Successfully set the PSK.
OT_ERROR_INVALID_ARGS
The PSK is invalid.
OT_ERROR_DISABLED_FEATURE
Mbedtls config not enabled MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED

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,
  void *aContext
)

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.
[in] aContext
A pointer to arbitrary context information.
Return Values
OT_ERROR_NONE
Successfully started the CoAP Secure server.

otCoapSecureStop

otError otCoapSecureStop(
  otInstance *aInstance
)

This function stops the CoAP Secure server.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Return Values
OT_ERROR_NONE
Successfully stopped the CoAP Secure server.

Macros

OT_DEFAULT_COAP_SECURE_PORT

 OT_DEFAULT_COAP_SECURE_PORT 5684

Default CoAP Secure port, as specified in RFC 7252.