# CoAP Secure

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

| ### Enumerations ||
|---|---|
| `https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1ga59934eaa971f185250a260a04c5d489f{ https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1gga59934eaa971f185250a260a04c5d489faccf8e5a4b6e4509cff5b36ccee938d8b = 0, https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1gga59934eaa971f185250a260a04c5d489fab94ad5d4fa53dac162ca4da75b601440, https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1gga59934eaa971f185250a260a04c5d489faa8eaeee4a19da3779200e6443119fc32, https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1gga59934eaa971f185250a260a04c5d489fab49821740a2e45d9101309d562ca5684, https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1gga59934eaa971f185250a260a04c5d489fa0fcbc57fdd8f87e91c8ded8738bb3318, https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1gga59934eaa971f185250a260a04c5d489fa931b9fbee02520f690d020ad6b249e21 }` | enumCoAP secure connection event types. |

| ### Typedefs ||
|---|---|
| `https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1gaa725182746ba1212b844a1c7332aca16)(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. |
| `https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1ga72bce22f84a2646d387e4a0ed665f208` | typedef `enum https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1ga59934eaa971f185250a260a04c5d489f` CoAP secure connection event types. |
| `https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1ga66bfee7c60e1b83ef2e6931277db1a91)(otCoapSecureConnectEvent aEvent, void *aContext)` | typedef `void(*` Pointer is called when the DTLS connection state changes. |

| ### Functions ||
|---|---|
| `https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1gabac36262398c2e937c5676e077428a6a(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/struct/ot-coap-blockwise-resource *aResource)` | `void` Adds a block-wise resource to the CoAP Secure server. |
| `https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1ga89283c6d248bab07bc84b9c003905ffb(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/struct/ot-coap-resource *aResource)` | `void` Adds a resource to the CoAP Secure server. |
| `https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1ga9319d2fbfd22822e6c41f7aea348fa35(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const https://openthread.io/reference/struct/ot-sock-addr *aSockAddr, https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1ga66bfee7c60e1b83ef2e6931277db1a91 aHandler, void *aContext)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Initializes DTLS session with a peer. |
| `https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1ga120bb4ea498c3495cd409a1d6221ee6f(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `void` Stops the DTLS connection. |
| `https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1gad5741a38686bc59ee17b2dc66d285f53(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, unsigned char *aPeerCert, size_t *aCertLength, size_t aCertBufferSize)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Returns the peer x509 certificate base64 encoded. |
| `https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1gaf95c9ad1be0c02a2a53718c96b1c8926(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `bool` Indicates whether or not the DTLS session is closed. |
| `https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1ga141c2451d0897088153d8bd1bd986367(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `bool` Indicates whether or not the DTLS session is connected. |
| `https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1ga12ee809d7363028f5bdf6e27811a0e79(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `bool` Indicates whether or not the DTLS session is active. |
| `https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1ga16818bccfaa54b3203633c7c5ff538d4(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/struct/ot-coap-blockwise-resource *aResource)` | `void` Removes a block-wise resource from the CoAP Secure server. |
| `https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1gac692987d889f6ae39ae5b241b99a6715(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/struct/ot-coap-resource *aResource)` | `void` Removes a resource from the CoAP Secure server. |
| `https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1gab1e3d5b9c42ecdeab2626c8504265191(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/group/api-message#group__api-message_1ga42d128a0a9ad58de0eb79673843c2955 *aMessage, https://openthread.io/reference/group/api-coap#group__api-coap_1ga42fc3fdfc2f3dacf34041b5ee4a9c6eb aHandler, void *aContext)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Sends a CoAP request over secure DTLS connection. |
| `https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1gac408782b165f3c93392761dbcc0bacd9(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/group/api-message#group__api-message_1ga42d128a0a9ad58de0eb79673843c2955 *aMessage, https://openthread.io/reference/group/api-coap#group__api-coap_1ga42fc3fdfc2f3dacf34041b5ee4a9c6eb aHandler, void *aContext, https://openthread.io/reference/group/api-coap#group__api-coap_1gaff785a9a39107f9447d5c183ab04aa6a aTransmitHook, https://openthread.io/reference/group/api-coap#group__api-coap_1ga0c640fe414553134e76899bad13e7242 aReceiveHook)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Sends a CoAP request block-wise over secure DTLS connection. |
| `https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1gab5bef9705faaa54c8ead7703cf222a13(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/group/api-message#group__api-message_1ga42d128a0a9ad58de0eb79673843c2955 *aMessage, const https://openthread.io/reference/struct/ot-message-info *aMessageInfo)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Sends a CoAP response from the CoAP Secure server. |
| `https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1ga31e58e7b01ac8b15062602f37d7cd8c4(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/group/api-message#group__api-message_1ga42d128a0a9ad58de0eb79673843c2955 *aMessage, const https://openthread.io/reference/struct/ot-message-info *aMessageInfo, void *aContext, https://openthread.io/reference/group/api-coap#group__api-coap_1gaff785a9a39107f9447d5c183ab04aa6a aTransmitHook)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Sends a CoAP response block-wise from the CoAP Secure server. |
| `https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1gabde839cb00b9003037466b75061aed41(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const uint8_t *aX509CaCertificateChain, uint32_t aX509CaCertChainLength)` | `void` Sets the trusted top level CAs. |
| `https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1ga9cbf06e3ec39343fa16dd08ebb172726(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *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. |
| `https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1ga7eaabd0b3882e699211bd7a08da18429(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1ga66bfee7c60e1b83ef2e6931277db1a91 aHandler, void *aContext)` | `void` Sets the connect event callback to indicate when a Client connection to the CoAP Secure server has changed. |
| `https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1gaeaabcf3f2b0ea58998204fd112999d05(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/group/api-coap#group__api-coap_1ga43485a1c168a672b36d35f4c6259dbea aHandler, void *aContext)` | `void` Sets the default handler for unhandled CoAP Secure requests. |
| `https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1ga15ef5aed4eb2c52d24c107017e0b607f(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *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. |
| `https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1ga28d536c5a549d18569c3a3e2a2c6b15d(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, bool aVerifyPeerCertificate)` | `void` Sets the authentication mode for the coap secure connection. |
| `https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1ga40e1bedcac22f1ea200a337b66d9876b(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint16_t aPort)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Starts the CoAP Secure service. |
| `https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1gad6c1fe2f4e40eb64a23b476d769c5bf2(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint16_t aPort, uint16_t aMaxAttempts, https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1gaa725182746ba1212b844a1c7332aca16 aCallback, void *aContext)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Starts the CoAP secure service and sets the maximum number of allowed connection attempts before stopping the agent automatically. |
| `https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1gaccd552e37efd3125fe690055d2ad666a(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `void` Stops the CoAP Secure server. |

| ### Macros ||
|---|---|
| `https://openthread.io/reference/group/api-coap-secure#group__api-coap-secure_1ga3a4fe10772adba8d71cfc464f1d17740 5684` | Default CoAP Secure port, as specified in RFC 7252. |

## Enumerations

### otCoapSecureConnectEvent

```
 otCoapSecureConnectEvent
```
CoAP secure connection event types.

| Properties ||
|---|---|
| `OT_COAP_SECURE_CONNECTED` | Connection established. |
| `OT_COAP_SECURE_DISCONNECTED_ERROR` | Disconnected due to an error. |
| `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_PEER_CLOSED` | Disconnected by peer. |
| `OT_COAP_SECURE_DISCONNECTED_TIMEOUT` | Disconnected locally due to session timeout. |

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

<br />

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

### otCoapSecureConnectEvent

```
enum otCoapSecureConnectEvent otCoapSecureConnectEvent
```
CoAP secure connection event types.

### otHandleCoapSecureClientConnect

```
void(* otHandleCoapSecureClientConnect)(otCoapSecureConnectEvent aEvent, void *aContext)
```
Pointer is called when the DTLS connection state changes.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aEvent` | The connection event. | | `[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.

<br />

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

<br />

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

<br />

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

<br />

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


> [!NOTE]
> **Note:** This function requires the build-time features `MBEDTLS_BASE64_C` and `MBEDTLS_SSL_KEEP_PEER_CERTIFICATE` to be enabled.

<br />

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

<br />

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

<br />

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

<br />

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

<br />

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

<br />

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

<br />

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

<br />

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

<br />

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

<br />

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


> [!NOTE]
> **Note:** This function requires `MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED=1`.

<br />

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


> [!NOTE]
> **Note:** This function requires `MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED=1`.

<br />

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

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

<br />

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

### otCoapSecureSetDefaultHandler

```
void otCoapSecureSetDefaultHandler(
  otInstance *aInstance,
  otCoapRequestHandler aHandler,
  void *aContext
)
```
Sets the default handler for unhandled CoAP Secure requests.

<br />

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


> [!NOTE]
> **Note:** This function requires the build-time feature `MBEDTLS_KEY_EXCHANGE_PSK_ENABLED` to be enabled.

<br />

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

<br />

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

<br />

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

<br />

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

<br />

| 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](https://github.com/openthread/openthread/tree/main/include/openthread).
For more information, or to contribute to our documentation, refer to
[Resources](https://openthread.io/resources).