CoAP Secure

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

Macros

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

Typedefs

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

Functions

otError otCoapSecureStart (otInstance *aInstance, uint16_t aPort)
 This function starts the CoAP Secure service.
 
void otCoapSecureStop (otInstance *aInstance)
 This function stops the CoAP Secure server.
 
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.
 
otError otCoapSecureGetPeerCertificateBase64 (otInstance *aInstance, unsigned char *aPeerCert, size_t *aCertLength, size_t aCertBufferSize)
 This method returns the peer x509 certificate base64 encoded.
 
void otCoapSecureSetSslAuthMode (otInstance *aInstance, bool aVerifyPeerCertificate)
 This method 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)
 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.
 
void otCoapSecureSetCaCertificateChain (otInstance *aInstance, const uint8_t *aX509CaCertificateChain, uint32_t aX509CaCertChainLength)
 This method sets the trusted top level CAs.
 
otError otCoapSecureConnect (otInstance *aInstance, const otSockAddr *aSockAddr, otHandleCoapSecureClientConnect aHandler, void *aContext)
 This method initializes DTLS session with a peer.
 
void otCoapSecureDisconnect (otInstance *aInstance)
 This method stops the DTLS connection.
 
bool otCoapSecureIsConnected (otInstance *aInstance)
 This method indicates whether or not the DTLS session is connected.
 
bool otCoapSecureIsConnectionActive (otInstance *aInstance)
 This method indicates whether or not the DTLS session is active.
 
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.
 
otError otCoapSecureSendRequest (otInstance *aInstance, otMessage *aMessage, otCoapResponseHandler aHandler, void *aContext)
 This method sends a CoAP request over secure DTLS connection.
 
void otCoapSecureAddResource (otInstance *aInstance, otCoapResource *aResource)
 This function adds a resource to the CoAP Secure server.
 
void otCoapSecureRemoveResource (otInstance *aInstance, otCoapResource *aResource)
 This function removes a resource from the CoAP Secure server.
 
void otCoapSecureAddBlockWiseResource (otInstance *aInstance, otCoapBlockwiseResource *aResource)
 This function adds a block-wise resource to the CoAP Secure server.
 
void otCoapSecureRemoveBlockWiseResource (otInstance *aInstance, otCoapBlockwiseResource *aResource)
 This function removes a block-wise resource from the CoAP Secure server.
 
void otCoapSecureSetDefaultHandler (otInstance *aInstance, otCoapRequestHandler aHandler, void *aContext)
 This function sets the default handler for unhandled CoAP Secure requests.
 
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.
 
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.
 
otError otCoapSecureSendResponse (otInstance *aInstance, otMessage *aMessage, const otMessageInfo *aMessageInfo)
 This function sends a CoAP response from the CoAP Secure server.

Detailed Description

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.

Typedef Documentation

◆ otHandleCoapSecureClientConnect

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

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

Parameters
[in]aConnectedtrue, if a connection was established, false otherwise.
[in]aContextA pointer to arbitrary context information.

Function Documentation

◆ otCoapSecureAddBlockWiseResource()

void otCoapSecureAddBlockWiseResource ( otInstance aInstance,
otCoapBlockwiseResource aResource 
)

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

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aResourceA pointer to the resource.

◆ otCoapSecureAddResource()

void otCoapSecureAddResource ( otInstance aInstance,
otCoapResource aResource 
)

This function adds a resource to the CoAP Secure server.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aResourceA pointer to the resource.

◆ otCoapSecureConnect()

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

This method initializes DTLS session with a peer.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aSockAddrA pointer to the remote socket address.
[in]aHandlerA pointer to a function that will be called when the DTLS connection state changes.
[in]aContextA pointer to arbitrary context information.
Return values
OT_ERROR_NONESuccessfully started DTLS connection.

◆ otCoapSecureDisconnect()

void otCoapSecureDisconnect ( otInstance aInstance)

This method stops the DTLS connection.

Parameters
[in]aInstanceA 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.
Parameters
[in]aInstanceA pointer to an OpenThread instance.
[out]aPeerCertA pointer to the base64 encoded certificate buffer.
[out]aCertLengthThe length of the base64 encoded peer certificate.
[in]aCertBufferSizeThe buffer size of aPeerCert.
Return values
OT_ERROR_INVALID_STATENot connected yet.
OT_ERROR_NONESuccessfully get the peer certificate.
OT_ERROR_NO_BUFSCan't allocate memory for certificate.

◆ otCoapSecureIsConnected()

bool otCoapSecureIsConnected ( otInstance aInstance)

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

Parameters
[in]aInstanceA pointer to an OpenThread instance.
Return values
TRUEThe DTLS session is connected.
FALSEThe DTLS session is not connected.

◆ otCoapSecureIsConnectionActive()

bool otCoapSecureIsConnectionActive ( otInstance aInstance)

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

Parameters
[in]aInstanceA pointer to an OpenThread instance.
Return values
TRUEIf DTLS session is active.
FALSEIf DTLS session is not active.

◆ otCoapSecureRemoveBlockWiseResource()

void otCoapSecureRemoveBlockWiseResource ( otInstance aInstance,
otCoapBlockwiseResource aResource 
)

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

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aResourceA pointer to the resource.

◆ otCoapSecureRemoveResource()

void otCoapSecureRemoveResource ( otInstance aInstance,
otCoapResource aResource 
)

This function removes a resource from the CoAP Secure server.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aResourceA 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.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aMessageA reference to the message to send.
[in]aHandlerA function pointer that shall be called on response reception or time-out.
[in]aContextA pointer to arbitrary context information.
Return values
OT_ERROR_NONESuccessfully sent CoAP message.
OT_ERROR_NO_BUFSFailed to allocate retransmission data.
OT_ERROR_INVALID_STATEDTLS 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.

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.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aMessageA reference to the message to send.
[in]aHandlerA function pointer that shall be called on response reception or time-out.
[in]aContextA pointer to arbitrary context information.
[in]aTransmitHookA function pointer that is called on Block1 response reception.
[in]aReceiveHookA function pointer that is called on Block2 response reception.
Return values
OT_ERROR_NONESuccessfully sent CoAP message.
OT_ERROR_NO_BUFSFailed to allocate retransmission data.
OT_ERROR_INVALID_STATEDTLS 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.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aMessageA pointer to the CoAP response to send.
[in]aMessageInfoA pointer to the message info associated with aMessage.
Return values
OT_ERROR_NONESuccessfully enqueued the CoAP response message.
OT_ERROR_NO_BUFSInsufficient 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.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aMessageA pointer to the CoAP response to send.
[in]aMessageInfoA pointer to the message info associated with aMessage.
[in]aContextA pointer to arbitrary context information. May be NULL if not used.
[in]aTransmitHookA function pointer that is called on Block1 request reception.
Return values
OT_ERROR_NONESuccessfully enqueued the CoAP response message.
OT_ERROR_NO_BUFSInsufficient 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.
Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aX509CaCertificateChainA pointer to the PEM formatted X509 CA chain.
[in]aX509CaCertChainLengthThe 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.
Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aX509CertA pointer to the PEM formatted X509 certificate.
[in]aX509LengthThe length of certificate.
[in]aPrivateKeyA pointer to the PEM formatted private key.
[in]aPrivateKeyLengthThe 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.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aHandlerA pointer to a function that will be called once DTLS connection is established.
[in]aContextA 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.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aHandlerA function pointer that shall be called when an unhandled request arrives.
[in]aContextA 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.
Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aPskA pointer to the PSK.
[in]aPskLengthThe PSK length.
[in]aPskIdentityThe Identity Name for the PSK.
[in]aPskIdLengthThe 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.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aVerifyPeerCertificatetrue, to verify the peer certificate.

◆ otCoapSecureStart()

otError otCoapSecureStart ( otInstance aInstance,
uint16_t  aPort 
)

This function starts the CoAP Secure service.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aPortThe local UDP port to bind to.
Return values
OT_ERROR_NONESuccessfully started the CoAP Secure server.

◆ otCoapSecureStop()

void otCoapSecureStop ( otInstance aInstance)

This function stops the CoAP Secure server.

Parameters
[in]aInstanceA pointer to an OpenThread instance.