This module includes functions that control CoAP Secure (CoAP over DTLS) communication.
More...
|
otError | otCoapSecureStart (otInstance *aInstance, uint16_t aPort) |
|
void | otCoapSecureStop (otInstance *aInstance) |
|
void | otCoapSecureSetPsk (otInstance *aInstance, const uint8_t *aPsk, uint16_t aPskLength, const uint8_t *aPskIdentity, uint16_t aPskIdLength) |
|
otError | otCoapSecureGetPeerCertificateBase64 (otInstance *aInstance, unsigned char *aPeerCert, size_t *aCertLength, size_t aCertBufferSize) |
|
void | otCoapSecureSetSslAuthMode (otInstance *aInstance, bool aVerifyPeerCertificate) |
|
void | otCoapSecureSetCertificate (otInstance *aInstance, const uint8_t *aX509Cert, uint32_t aX509Length, const uint8_t *aPrivateKey, uint32_t aPrivateKeyLength) |
|
void | otCoapSecureSetCaCertificateChain (otInstance *aInstance, const uint8_t *aX509CaCertificateChain, uint32_t aX509CaCertChainLength) |
|
otError | otCoapSecureConnect (otInstance *aInstance, const otSockAddr *aSockAddr, otHandleCoapSecureClientConnect aHandler, void *aContext) |
|
void | otCoapSecureDisconnect (otInstance *aInstance) |
|
bool | otCoapSecureIsConnected (otInstance *aInstance) |
|
bool | otCoapSecureIsConnectionActive (otInstance *aInstance) |
|
otError | otCoapSecureSendRequest (otInstance *aInstance, otMessage *aMessage, otCoapResponseHandler aHandler, void *aContext) |
|
otError | otCoapSecureAddResource (otInstance *aInstance, otCoapResource *aResource) |
|
void | otCoapSecureRemoveResource (otInstance *aInstance, otCoapResource *aResource) |
|
void | otCoapSecureSetDefaultHandler (otInstance *aInstance, otCoapRequestHandler aHandler, void *aContext) |
|
void | otCoapSecureSetClientConnectedCallback (otInstance *aInstance, otHandleCoapSecureClientConnect aHandler, void *aContext) |
|
otError | otCoapSecureSendResponse (otInstance *aInstance, otMessage *aMessage, const otMessageInfo *aMessageInfo) |
|
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 void(* otHandleCoapSecureClientConnect)(bool aConnected, void *aContext) |
This function pointer is called when the DTLS connection state changes.
- Parameters
-
[in] | aConnected | true, if a connection was established, false otherwise. |
[in] | aContext | A pointer to arbitrary context information. |
This function adds a resource to the CoAP Secure server.
- 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. |
This method initializes DTLS session with a peer.
- Parameters
-
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aSockAddr | A pointer to the remote sockaddr. |
[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. |
void otCoapSecureDisconnect |
( |
otInstance * |
aInstance | ) |
|
This method stops the DTLS connection.
- Parameters
-
[in] | aInstance | A pointer to an OpenThread instance. |
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 feature
MBEDTLS_BASE64_C
to be enabled.
- 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. |
bool otCoapSecureIsConnected |
( |
otInstance * |
aInstance | ) |
|
This method indicates whether or not the DTLS session is connected.
- Parameters
-
[in] | aInstance | A pointer to an OpenThread instance. |
- Return values
-
TRUE | The DTLS session is connected. |
FALSE | The DTLS session is not connected. |
bool otCoapSecureIsConnectionActive |
( |
otInstance * |
aInstance | ) |
|
This method indicates whether or not the DTLS session is active.
- Parameters
-
[in] | aInstance | A pointer to an OpenThread instance. |
- Return values
-
TRUE | If DTLS session is active. |
FALSE | If DTLS session is not active. |
This function removes a resource from the CoAP Secure server.
- Parameters
-
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aResource | A pointer to the resource. |
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] | 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. |
This function 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 . |
- Return values
-
OT_ERROR_NONE | Successfully enqueued the CoAP response message. |
OT_ERROR_NO_BUFS | Insufficient buffers available to send the CoAP response. |
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] | aInstance | A pointer to an OpenThread instance. |
[in] | aX509CaCertificateChain | A pointer to the PEM formatted X509 CA chain. |
[in] | aX509CaCertChainLength | The length of chain. |
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] | 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. |
This method sets the connected callback to indicate, when a Client connect to the CoAP Secure server.
- 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. |
This function 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. |
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] | 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. |
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] | aInstance | A pointer to an OpenThread instance. |
[in] | aVerifyPeerCertificate | true, to verify the peer certificate. |
This function starts the CoAP Secure service.
- 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. |
This function stops the CoAP Secure server.
- Parameters
-
[in] | aInstance | A pointer to an OpenThread instance. |