此页面由 Cloud Translation API 翻译。

CoAP 安全协议

此模块包含控制 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 安全服务器中移除分组资源。
`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` 此方法会为本地设备的 X509 证书设置相应的私钥，以便与 DTLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 进行 DTLS 会话。
`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 安全服务。
`otCoapSecureStop(otInstance *aInstance)`	`void` 此函数停止 CoAP 安全服务器。

类型定义符

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`	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 安全服务器中移除分组资源。

详情

参数

`[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 指针。如果标头中未设置 Message ID（等于 0），则此函数会为消息分配唯一的 Message 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`	在块 1 响应接收时调用的函数指针。
`[in] aReceiveHook`	在块 2 响应接收时调用的函数指针。

返回值

`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
)

此方法会为本地设备的 X509 证书设置相应的私钥，以便与 DTLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 进行 DTLS 会话。

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

详情

参数

`[in] aInstance`	指向 OpenThread 实例的指针。
`[in] aPort`	要绑定的本地 UDP 端口。

返回值

OT_ERROR_NONE

已成功启动 CoAP 安全服务器。

otCoapSecureStop

void otCoapSecureStop(
  otInstance *aInstance
)

此函数停止 CoAP 安全服务器。

详情

参数

[in] aInstance

指向 OpenThread 实例的指针。

宏

OT_DEFAULT_COAP_SECURE_PORT

 OT_DEFAULT_COAP_SECURE_PORT 5684

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

资源

OpenThread API 参考主题源自源代码，可在 GitHub 上找到。如需了解详情或为我们的文档做贡献，请参阅资源。