本頁面由 Cloud Translation API 翻譯而成。

CoAP 保護

這個模組包含控管 CoAP Secure (CoAP over DTLS) 通訊的功能。

摘要

啟用 CoAP Secure API 功能 (OPENTHREAD_CONFIG_COAP_SECURE_API_ENABLE) 時，即可使用本單元中的函式。

類型
`otHandleCoapSecureClientConnect)(bool aConnected, void *aContext)`	typedef `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 Secure 伺服器傳送 CoAP 回應。
`otCoapSecureSendResponseBlockWise(otInstance aInstance, otMessage aMessage, const otMessageInfo aMessageInfo, void aContext, otCoapBlockwiseTransmitHook aTransmitHook)`	`otError` 這項函式會從 CoAP Secure 伺服器以封鎖的方式傳送 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 為本機裝置設定 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 伺服器。

類型

otHandlingCoapSecureClientConnect

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

當 DTLS 連線狀態變更時，會呼叫此函式指標。

說明

參數

`[in] aConnected`	如果連線已建立，則傳回 False，否則傳回 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`	指向遠端通訊端位址的指標。
`[in] aHandler`	指標，當使用者在 DTLS 連線狀態變更時呼叫。
`[in] aContext`	指向任意內容資訊的指標。

傳回值

OT_ERROR_NONE

已成功啟動 DTLS 連線。

otCoapSecureConnect

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 和 MBEDTLS_SSL_KEEP_PEER_CERTIFICATE。

說明

參數

`[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 要求。

啟用 OPENCONVERSATION_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 Secure 伺服器傳送 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 Secure 伺服器以封鎖的方式傳送 CoAP 回應。

啟用 OPENCONVERSATION_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。

需要驗證對等點的憑證。

DTLS 模式「ECDHE ECDSA 搭配 AES 128 CCM 8」，適用於應用程式 CoAPS。

注意：這項功能需要 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 為本機裝置設定 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`	是，用來驗證對等憑證。

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

RFC 7252 中指定的預設 CoAP 安全通訊埠。

資源

OpenThread API 參照主題來自原始碼，位於 GitHub。如需更多資訊或參閱我們的說明文件，請參閱資源。