CoAP安全

該模塊包括控制CoAP安全（DTLS上的CoAP）通信的功能。

概要

啟用CoAP安全API功能（ OPENTHREAD_CONFIG_COAP_SECURE_API_ENABLE ）時，此模塊中的功能可用。

類型定義
`otHandleCoapSecureClientConnect )(bool aConnected, void *aContext)`	類型定義 `void(*` 當DTLS連接狀態更改時，將調用此函數指針。

功能
`otCoapSecureAddBlockWiseResource ( otInstance aInstance, otCoapBlockwiseResource aResource)`	`void` 此功能將逐塊資源添加到CoAP Secure服務器。
`otCoapSecureAddResource ( otInstance aInstance, otCoapResource aResource)`	`void` 此功能將資源添加到CoAP Secure服務器。
`otCoapSecureConnect ( otInstance aInstance, const otSockAddr aSockAddr, otHandleCoapSecureClientConnect aHandler, void *aContext)`	`otError` 此方法初始化與對等方的DTLS會話。
`otCoapSecureDisconnect ( otInstance *aInstance)`	`void` 此方法停止DTLS連接。
`otCoapSecureGetPeerCertificateBase64 ( otInstance aInstance, unsigned char aPeerCert, size_t *aCertLength, size_t aCertBufferSize)`	`otError` 此方法返回對等的x509證書base64編碼。
`otCoapSecureIsConnected ( otInstance *aInstance)`	`bool` 此方法指示是否連接了DTLS會話。
`otCoapSecureIsConnectionActive ( otInstance *aInstance)`	`bool` 此方法指示DTLS會話是否處於活動狀態。
`otCoapSecureRemoveBlockWiseResource ( otInstance aInstance, otCoapBlockwiseResource aResource)`	`void` 此功能從CoAP Secure服務器中刪除逐塊資源。
`otCoapSecureRemoveResource ( otInstance aInstance, otCoapResource aResource)`	`void` 此功能從CoAP Secure服務器中刪除資源。
`otCoapSecureSendRequest ( otInstance aInstance, otMessage aMessage, otCoapResponseHandler aHandler, void *aContext)`	`otError` 此方法通過安全的DTLS連接發送CoAP請求。
`otCoapSecureSendRequestBlockWise ( otInstance aInstance, otMessage aMessage, otCoapResponseHandler aHandler, void *aContext, otCoapBlockwiseTransmitHook aTransmitHook, otCoapBlockwiseReceiveHook aReceiveHook)`	`otError` 此方法通過安全DTLS連接逐塊發送CoAP請求。
`otCoapSecureSendResponse ( otInstance aInstance, otMessage aMessage, const otMessageInfo *aMessageInfo)`	`otError` 此功能從CoAP安全服務器發送CoAP響應。
`otCoapSecureSendResponseBlockWise ( otInstance aInstance, otMessage aMessage, const otMessageInfo aMessageInfo, void aContext, otCoapBlockwiseTransmitHook aTransmitHook)`	`otError` 此功能從CoAP安全服務器逐塊發送CoAP響應。
`otCoapSecureSetCaCertificateChain ( otInstance aInstance, const uint8_t aX509CaCertificateChain, uint32_t aX509CaCertChainLength)`	`void` 此方法設置受信任的頂級CA。
`otCoapSecureSetCertificate ( otInstance aInstance, const uint8_t aX509Cert, uint32_t aX509Length, const uint8_t *aPrivateKey, uint32_t aPrivateKeyLength)`	`void` 此方法為具有DTLS_ECDHE_ECDSA_WITH_AES_128_CCM_8的DTLS會話設置具有相應私鑰的本地設備的X509證書。
`otCoapSecureSetClientConnectedCallback ( otInstance aInstance, otHandleCoapSecureClientConnect aHandler, void aContext)`	`void` 此方法設置連接的回調以指示客戶端何時連接到CoAP Secure服務器。
`otCoapSecureSetDefaultHandler ( otInstance aInstance, otCoapRequestHandler aHandler, void aContext)`	`void` 此功能為未處理的CoAP Secure請求設置默認處理程序。
`otCoapSecureSetPsk ( otInstance aInstance, const uint8_t aPsk, uint16_t aPskLength, const uint8_t *aPskIdentity, uint16_t aPskIdLength)`	`void` 此方法設置預共享密鑰（PSK）和密碼套件DTLS_PSK_WITH_AES_128_CCM_8。
`otCoapSecureSetSslAuthMode ( otInstance *aInstance, bool aVerifyPeerCertificate)`	`void` 此方法設置coap安全連接的身份驗證模式。
`otCoapSecureStart ( otInstance *aInstance, uint16_t aPort)`	`otError` 此功能啟動CoAP Secure服務。
`otCoapSecureStop ( otInstance *aInstance)`	`void` 此功能停止CoAP Secure服務器。

類型定義

otHandleCoapSecureClientConnect

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

當DTLS連接狀態更改時，將調用此函數指針。

細節

參量

`[in] aConnected`	如果建立連接，則為true，否則為false。
`[in] aContext`	指向任意上下文信息的指針。

功能

otCoapSecureAddBlockWiseResource

void otCoapSecureAddBlockWiseResource(
  otInstance *aInstance,
  otCoapBlockwiseResource *aResource
)

此功能將逐塊資源添加到CoAP Secure服務器。

細節

參量

`[in] aInstance`	指向OpenThread實例的指針。
`[in] aResource`	指向資源的指針。

otCoapSecureAddResource

void otCoapSecureAddResource(
  otInstance *aInstance,
  otCoapResource *aResource
)

此功能將資源添加到CoAP Secure服務器。

細節

參量

`[in] aInstance`	指向OpenThread實例的指針。
`[in] aResource`	指向資源的指針。

otCoapSecureConnect

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

此方法初始化與對等方的DTLS會話。

細節

參量

`[in] aInstance`	指向OpenThread實例的指針。
`[in] aSockAddr`	指向遠程sockaddr的指針。
`[in] aHandler`	指向DTLS連接狀態更改時將調用的函數的指針。
`[in] aContext`	指向任意上下文信息的指針。

返回值

OT_ERROR_NONE

成功啟動DTLS連接。

otCoapSecureDisconnect

void otCoapSecureDisconnect(
  otInstance *aInstance
)

此方法停止DTLS連接。

細節

參量

[in] aInstance

指向OpenThread實例的指針。

otCoapSecureGetPeerCertificateBase64

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

此方法返回對等的x509證書base64編碼。

注意：此功能需要啟用構建時功能MBEDTLS_BASE64_C 。

細節

參量

`[in] aInstance`	指向OpenThread實例的指針。
`[out] aPeerCert`	指向base64編碼證書緩衝區的指針。
`[out] aCertLength`	base64編碼的對等證書的長度。
`[in] aCertBufferSize`	aPeerCert的緩衝區大小。

返回值

`OT_ERROR_INVALID_STATE`	尚未連接。
`OT_ERROR_NONE`	成功獲取對等證書。
`OT_ERROR_NO_BUFS`	無法為證書分配內存。

otCoapSecureIsConnected

bool otCoapSecureIsConnected(
  otInstance *aInstance
)

此方法指示是否連接了DTLS會話。

細節

參量

[in] aInstance

指向OpenThread實例的指針。

返回值

`TRUE`	DTLS會話已連接。
`FALSE`	DTLS會話未連接。

otCoapSecureIsConnectionActive

bool otCoapSecureIsConnectionActive(
  otInstance *aInstance
)

此方法指示DTLS會話是否處於活動狀態。

細節

參量

[in] aInstance

指向OpenThread實例的指針。

返回值

`TRUE`	如果DTLS會話處於活動狀態。
`FALSE`	如果DTLS會話未激活。

otCoapSecureRemoveBlockWiseResource

void otCoapSecureRemoveBlockWiseResource(
  otInstance *aInstance,
  otCoapBlockwiseResource *aResource
)

此功能從CoAP Secure服務器中刪除逐塊資源。

細節

參量

`[in] aInstance`	指向OpenThread實例的指針。
`[in] aResource`	指向資源的指針。

otCoapSecureRemoveResource

void otCoapSecureRemoveResource(
  otInstance *aInstance,
  otCoapResource *aResource
)

此功能從CoAP Secure服務器中刪除資源。

細節

參量

`[in] aInstance`	指向OpenThread實例的指針。
`[in] aResource`	指向資源的指針。

otCoapSecureSendRequest

otError otCoapSecureSendRequest(
  otInstance *aInstance,
  otMessage *aMessage,
  otCoapResponseHandler aHandler,
  void *aContext
)

此方法通過安全的DTLS連接發送CoAP請求。

如果期望對請求的響應，則應提供相應的功能和上下文信息。如果沒有響應，則這些參數應為NULL指針。如果標頭中未設置消息ID（等於0），則此函數將為消息分配唯一的消息ID。

細節

參量

`[in] aInstance`	指向OpenThread實例的指針。
`[in] aMessage`	對要發送的消息的引用。
`[in] aHandler`	在響應接收或超時時應調用的函數指針。
`[in] aContext`	指向任意上下文信息的指針。

返回值

`OT_ERROR_NONE`	成功發送CoAP消息。
`OT_ERROR_NO_BUFS`	分配重傳數據失敗。
`OT_ERROR_INVALID_STATE`	DTLS連接未初始化。

otCoapSecureSendRequestBlockWise

otError otCoapSecureSendRequestBlockWise(
  otInstance *aInstance,
  otMessage *aMessage,
  otCoapResponseHandler aHandler,
  void *aContext,
  otCoapBlockwiseTransmitHook aTransmitHook,
  otCoapBlockwiseReceiveHook aReceiveHook
)

此方法通過安全DTLS連接逐塊發送CoAP請求。

啟用OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE配置時，此功能可用。

細節

參量

`[in] aInstance`	指向OpenThread實例的指針。
`[in] aMessage`	對要發送的消息的引用。
`[in] aHandler`	在響應接收或超時時應調用的函數指針。
`[in] aContext`	指向任意上下文信息的指針。
`[in] aTransmitHook`	在Block1響應接收時調用的函數指針。
`[in] aReceiveHook`	在Block2響應接收時調用的函數指針。

返回值

`OT_ERROR_NONE`	成功發送CoAP消息。
`OT_ERROR_NO_BUFS`	分配重傳數據失敗。
`OT_ERROR_INVALID_STATE`	DTLS連接未初始化。

otCoapSecureSendResponse

otError otCoapSecureSendResponse(
  otInstance *aInstance,
  otMessage *aMessage,
  const otMessageInfo *aMessageInfo
)

此功能從CoAP安全服務器發送CoAP響應。

細節

參量

`[in] aInstance`	指向OpenThread實例的指針。
`[in] aMessage`	指向要發送的CoAP響應的指針。
`[in] aMessageInfo`	指向與`aMessage`關聯的消息信息的指針。

返回值

`OT_ERROR_NONE`	成功將CoAP響應消息加入隊列。
`OT_ERROR_NO_BUFS`	可用於發送CoAP響應的緩衝區不足。

otCoapSecureSendResponseBlockWise

otError otCoapSecureSendResponseBlockWise(
  otInstance *aInstance,
  otMessage *aMessage,
  const otMessageInfo *aMessageInfo,
  void *aContext,
  otCoapBlockwiseTransmitHook aTransmitHook
)

此功能從CoAP安全服務器逐塊發送CoAP響應。

啟用OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE配置時，此功能可用。

細節

參量

`[in] aInstance`	指向OpenThread實例的指針。
`[in] aMessage`	指向要發送的CoAP響應的指針。
`[in] aMessageInfo`	指向與`aMessage`關聯的消息信息的指針。
`[in] aContext`	指向任意上下文信息的指針。如果不使用，則可以為NULL。
`[in] aTransmitHook`	在Block1請求接收時調用的函數指針。

返回值

`OT_ERROR_NONE`	成功將CoAP響應消息加入隊列。
`OT_ERROR_NO_BUFS`	可用於發送CoAP響應的緩衝區不足。

otCoapSecureSetCaCertificateChain

void otCoapSecureSetCaCertificateChain(
  otInstance *aInstance,
  const uint8_t *aX509CaCertificateChain,
  uint32_t aX509CaCertChainLength
)

此方法設置受信任的頂級CA。

驗證對等方的證書是必需的。

用於應用程序CoAPS的DTLS模式“帶有AES 128 CCM 8的ECDHE ECDSA”。

注意：此功能需要MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED=1 。

細節

參量

`[in] aInstance`	指向OpenThread實例的指針。
`[in] aX509CaCertificateChain`	指向PEM格式的X509 CA鏈的指針。
`[in] aX509CaCertChainLength`	鏈的長度。

otCoapSecureSetCertificate

void otCoapSecureSetCertificate(
  otInstance *aInstance,
  const uint8_t *aX509Cert,
  uint32_t aX509Length,
  const uint8_t *aPrivateKey,
  uint32_t aPrivateKeyLength
)

此方法為具有DTLS_ECDHE_ECDSA_WITH_AES_128_CCM_8的DTLS會話設置具有相應私鑰的本地設備的X509證書。

注意：此功能需要MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED=1 。

細節

參量

`[in] aInstance`	指向OpenThread實例的指針。
`[in] aX509Cert`	指向PEM格式的X509證書的指針。
`[in] aX509Length`	證書的長度。
`[in] aPrivateKey`	指向PEM格式的私鑰的指針。
`[in] aPrivateKeyLength`	私鑰的長度。

otCoapSecureSetClientConnectedCallback

void otCoapSecureSetClientConnectedCallback(
  otInstance *aInstance,
  otHandleCoapSecureClientConnect aHandler,
  void *aContext
)

此方法設置連接的回調以指示客戶端何時連接到CoAP Secure服務器。

細節

參量

`[in] aInstance`	指向OpenThread實例的指針。
`[in] aHandler`	建立DTLS連接後將調用的函數的指針。
`[in] aContext`	指向任意上下文信息的指針。如果不使用，則可以為NULL。

otCoapSecureSetDefaultHandler

void otCoapSecureSetDefaultHandler(
  otInstance *aInstance,
  otCoapRequestHandler aHandler,
  void *aContext
)

此功能為未處理的CoAP Secure請求設置默認處理程序。

細節

參量

`[in] aInstance`	指向OpenThread實例的指針。
`[in] aHandler`	當未處理的請求到達時應調用的函數指針。
`[in] aContext`	指向任意上下文信息的指針。如果不使用，則可以為NULL。

otCoapSecureSetPsk

void otCoapSecureSetPsk(
  otInstance *aInstance,
  const uint8_t *aPsk,
  uint16_t aPskLength,
  const uint8_t *aPskIdentity,
  uint16_t aPskIdLength
)

此方法設置預共享密鑰（PSK）和密碼套件DTLS_PSK_WITH_AES_128_CCM_8。

注意：此功能需要啟用構建時功能MBEDTLS_KEY_EXCHANGE_PSK_ENABLED 。

細節

參量

`[in] aInstance`	指向OpenThread實例的指針。
`[in] aPsk`	指向PSK的指針。
`[in] aPskLength`	PSK長度。
`[in] aPskIdentity`	PSK的標識名稱。
`[in] aPskIdLength`	PSK身份長度。

otCoapSecureSetSslAuthMode

void otCoapSecureSetSslAuthMode(
  otInstance *aInstance,
  bool aVerifyPeerCertificate
)

此方法設置coap安全連接的身份驗證模式。

禁用或啟用對等證書的驗證。必須在開始之前調用。

細節

參量

`[in] aInstance`	指向OpenThread實例的指針。
`[in] aVerifyPeerCertificate`	true，以驗證對等證書。

otCoapSecureStart

otError otCoapSecureStart(
  otInstance *aInstance,
  uint16_t aPort
)

此功能啟動CoAP Secure服務。

細節

參量

`[in] aInstance`	指向OpenThread實例的指針。
`[in] aPort`	要綁定的本地UDP端口。

返回值

OT_ERROR_NONE

成功啟動了CoAP Secure服務器。

otCoapSecureStop

void otCoapSecureStop(
  otInstance *aInstance
)

此功能停止CoAP Secure服務器。

細節

參量

[in] aInstance

指向OpenThread實例的指針。

巨集

OT_DEFAULT_COAP_SECURE_PORT

 OT_DEFAULT_COAP_SECURE_PORT 5684

默認CoAP安全端口，如RFC 7252中所指定。