CoAP Secure

此模块包含用于控制 CoAP Secure（通过 DTLS 进行 CoAP）通信的函数。

总结

启用 CoAP Secure API 功能 (OPENTHREAD_CONFIG_COAP_SECURE_API_ENABLE) 后，此模块中的函数可用。

类型定义符
otHandleCoapSecureClientConnect)(bool aConnected, void *aContext)	typedef void(* 当 DTLS 连接状态发生变化时，系统会调用指针。

函数
otCoapSecureAddBlockWiseResource(otInstance *aInstance, otCoapBlockwiseResource *aResource)	void 为 CoAP 安全服务器添加块级资源。
otCoapSecureAddResource(otInstance *aInstance, otCoapResource *aResource)	void 为 CoAP 安全服务器添加资源。
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 安全服务器中移除资源。
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 安全服务器。
otCoapSecureSetDefaultHandler(otInstance *aInstance, otCoapRequestHandler aHandler, void *aContext)	void 为未处理的 CoAP 安全请求设置默认处理程序。
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 安全服务器添加块级资源。

详情
参数	[in] aInstance 指向 OpenThread 实例的指针。 [in] aResource 指向资源的指针。

otCoapSecureAddResource

void otCoapSecureAddResource(
  otInstance *aInstance,
  otCoapResource *aResource
)

为 CoAP 安全服务器添加资源。

详情
参数	[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 连接。

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

详情
参数	[in] aInstance 指向 OpenThread 实例的指针。 [out] aPeerCert 指向 base64 编码证书缓冲区的指针。 [out] aCertLength 采用 base64 编码的对等证书的长度。 [in] aCertBufferSize PeerPeerCert 的缓冲区大小。
返回值	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 安全服务器中移除资源。

详情
参数	[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 配置后可用。

如果需要请求请求响应，则应提供相应的函数和上下文信息。如果没有预期响应，这些参数应为 NULL 指针。如果没有在标头中设置邮件 ID（等于 0），则此函数会为邮件分配唯一邮件 ID。

详情
参数	[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 模式“ECDHE ECDSA with AES 128 CCM 8”。

注意：此函数需要使用 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 安全服务器。

详情
参数	[in] aInstance 指向 OpenThread 实例的指针。 [in] aHandler 指向建立 DTLS 连接后调用的函数的指针。 [in] aContext 指向任意上下文信息的指针。如果未使用，则可能会为 NULL。

otCoapSecureSetDefaultHandler

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

为未处理的 CoAP 安全请求设置默认处理程序。

详情
参数	[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 服务器。

OTCoaSecureSecure

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 上获取。 如需了解详情或为我们的文档贡献内容，请参阅资源。