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

CoAP 安全

這個模組包含可控管 CoAP Secure (CoAP on DTLS) 通訊的函式。

摘要

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

Typedefs
`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，為本機裝置的 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` 設定用於安全連線的驗證模式。
`otCoapSecureStart(otInstance *aInstance, uint16_t aPort)`	`otError` 啟動 CoAP Secure 服務。
`otCoapSecureStop(otInstance *aInstance)`	`void` 停止 CoAP Secure 伺服器。

Typedefs

otHandleCoapSecureClientConnect

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

當 DTLS 連線狀態變更時，系統會呼叫指標。

詳細說明

參數

`[in] aConnected`	如果已建立連線，則為 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 連線。

otCoapSecure 中斷連線

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

啟用 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 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 回應。

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

系統需要憑證才能驗證對等互連憑證。

DTLS 模式「ECDHE ECDSA with 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，為本機裝置的 DTLS 工作階段設定對應的私密金鑰 X509 憑證。

注意：此函式需要 MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED=1。

詳細說明

參數

`[in] aInstance`	指向 OpenThread 執行個體的指標。
`[in] aX509Cert`	指向 PEM 格式 X509 憑證的指標。
`[in] aX509Length`	憑證的長度，
`[in] aPrivateKey`	指向 PEM 格式私密金鑰的指標。
`[in] aPrivateKeyLength`	私密金鑰的長度。

otCoapSecureSetClientClientCallback

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
)

設定用於安全連線的驗證模式。

停用或啟用對等互連憑證的驗證程序。必須在呼叫開始前呼叫。

詳細說明

參數

`[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 安全伺服器。

otCoapSecureStop

void otCoapSecureStop(
  otInstance *aInstance
)

停止 CoAP Secure 伺服器。

詳細說明

參數

[in] aInstance

指向 OpenThread 執行個體的指標。

巨集

OT_DEFAULT_COAP_SECURE_PORT

 OT_DEFAULT_COAP_SECURE_PORT 5684

預設 CoAP 安全通訊埠，如 RFC 7252 中所述。

資源

OpenThread API 參考資料主題源自原始碼，可於 GitHub 取得。如需更多資訊或為說明文件貢獻心力，請參閱資源。