WS53指导资料

- hardware
  - SoC Wi-Fi、BLE和SLE Combo芯片 硬件用户指南
    - 前言
    - 封装与管脚
    - 电性能参数
    - 原理图设计建议
    - PCB设计建议
    - 热设计建议
    - 焊接工艺
    - 潮敏参数
    - 接口时序
    - 注意事项
    - 缩略语
  - 单板硬件关键器件选型指导
    - 前言
    - 关键器件选型约束
  - 射频测试 用户指南
    - 前言
    - 测试指令
    - 注意事项
- 软件资料
  - AT命令 使用指南
    - 前言
    - 指令说明
    - Wi-Fi模块AT指令
    - BLE&SLE模块AT指令
    - PLAT模块AT指令
  - BLE BQB认证测试 指导书
    - 前言
    - 蓝牙BQB认证简介
    - BQB协议认证
    - BQB 射频认证
    - WS53特性支持情况
    - 常见问题&测试命令汇总(FAQ)
  - BOOT API开发参考
    - 前言
    - 接口介绍
  - Boot移植应用 开发指南
    - 前言
    - Boot简介
    - RomBoot功能说明
    - LoaderBoot功能说明
    - FlashBoot说明
  - CJSON 开发指南
    - 前言
    - API接口说明
    - 开发指南
  - CoAP 开发指南
    - 前言
    - API接口说明
    - 开发指南
  - EFUSE 使用指南
    - 前言
    - 概述
    - 软件编程接口使用指导
    - Burntool烧写efuse_cfg.bin说明
  - FOTA 开发指南
    - 前言
    - 概述
    - 升级包制作
    - 升级包传输
    - 升级包保存
    - 升级包本地升级
    - AB面升级
    - FAQ
  - HTTP 开发指南
    - 前言
    - 开发指南
  - MQTT 开发指南
    - 前言
    - API接口描述
    - 开发指南
    - 注意事项
  - NV存储 用户指南
    - 前言
    - NV简介
    - NV编译预置
    - NV API指南
    - NV项汇总
  - SAMPLE用例 用户指南
    - 前言
    - SAMPLE简介
    - 外设SAMPLE用例
  - SDK 开发指南
    - 前言
    - 概述
    - 系统接口
  - SDK开发环境搭建 用户指南
    - 前言
    - 开发环境搭建
    - 编译
    - 新建APP
  - Syschannel 使用指南
    - 前言
    - Syschannel 简介
    - Syschannel 使用指南
    - Syschannel 编译指导
    - Syschannel 适配常见问题
  - TLS&DTLS 开发指南
    - 前言
    - API接口说明
    - 开发指南
    - 硬件适配
    - 注意事项
  - WFA认证测试指导书
    - 前言
    - WLAN WFA协议认证介绍
    - WS53 WFA认证
    - 缩略语
  - lwIP 开发指南
    - 前言
    - 概述
    - 功能特性
    - 开发指引
    - 网络安全
    - 常见问题
    - 术语
  - 产测FAQ
    - 前言
    - FAQ
    - 注意事项
    - 版本问题记录
  - 产线工装 用户指南
    - 前言
    - 测试软件准备
    - 单板测试方案
    - TX/RX测试参考
    - WLAN Facility与固件版本
    - 产线生产ESD防护要求
  - 低功耗 开发指南
    - 前言
    - 概述
    - 超深睡模式
    - 深睡模式
    - 浅睡模式
    - 常见问题
  - 单板冒烟 测试指南
    - 前言
    - 概述
    - 单板冒烟测试
  - 安全模块 使用指南
    - 前言
    - 概述
    - 错误码
    - 网络安全注意事项
  - 文件系统 使用指南
    - 前言
    - LFS简介
    - LFS编译预置
    - LFS接口API
  - 星闪认证测试 指导书
    - 前言
    - 星闪认证简介
    - 星闪协议认证
    - 星闪射频认证
    - 星闪特性支持
    - 常见问题&测试命令汇总（FAQ）
  - 特性开发说明书
    - 前言
    - 混杂模式特性说明
    - 动态国家码特性说明
    - BLE配网特性说明
    - 安全启动特性说明
    - FLASH在线解密特性说明
  - 第三方软件 移植指南
    - 前言
    - 移植指引
    - 常见问题
  - 设备驱动 开发指南
    - 前言
    - Pinctrl
    - GPIO
    - UART
    - SPI
    - QSPI
    - I2C
    - ADC
    - DMA
    - PWM
    - WDT
    - Timer
    - Systick
    - TCXO
    - SFC
    - eFuse
    - REBOOT
    - I2S
  - 软件 开发指南
    - 前言
    - 概述
    - Wi-Fi 软件开发指南
    - BLE&SLE 软件开发指南
    - 注意事项
  - 运维手册
    - 前言
    - 系统/平台模块
    - Wi-Fi模块
  - 鸿蒙XTS认证 指导书
    - 前言
    - 概述
    - 准备工作
    - 编译openharmony静态库
    - XTS版本编译和执行

### 该页内容

- 前言
- API接口说明
  - 结构体说明
  - API列表
  - 配置说明
- 开发指南
- 硬件适配
  - 配置说明
  - 适配说明
    - AES适配
    - 大数模幂适配
    - 随机数适配
    - RSA数字签名适配
    - HASH算法适配
    - ECP适配
- 注意事项
  - 关于配置SSL接收缓存的注意事项
  - 关于数字证书有效期验证的注意事项
  - 关于部分默认配置变更的说明
  - 使用场景典型问题说明
    - 内外部结构体大小不一致导致的挂死问题
    - 算法未完全适配硬加密导致的功能问题

# 前言

概述

本文档主要介绍TLS/DTLS组件的开发实现示例。

TLS/DTLS以及其他加密套基于开源组件MbedTLS 3.1.0实现，详细说明请参见官方说明：https://tls.mbed.org/api/index.html

如果官方说明版本与SDK版本不一致，请参考官方release说明：https://github.com/ARMmbed/mbedtls/releases

产品版本

与本文档相对应的产品版本如下。

产品名称 | 产品版本
--- | ---
WS53 | V100

读者对象

本文档主要适用于以下工程师：

- 技术支持工程师

- 软件开发工程师

符号约定

在本文中可能出现下列标志，它们所代表的含义如下。

符号 | 说明
--- | ---
| 表示如不避免则将会导致死亡或严重伤害的具有高等级风险的危害。
| 表示如不避免则可能导致死亡或严重伤害的具有中等级风险的危害。
| 表示如不避免则可能导致轻微或中度伤害的具有低等级风险的危害。
| 用于传递设备或环境安全警示信息。如不避免则可能会导致设备损坏、数据丢失、设备性能降低或其它不可预知的结果。 “须知”不涉及人身伤害。
| 对正文中重点信息的补充说明。 “说明”不是安全警示信息，不涉及人身、设备及环境伤害信息。

修改记录

文档版本 | 发布日期 | 修改说明
--- | --- | ---
02 | 2024-09-13 | 更新“API接口说明”章节内容。 更新“开发指南”章节内容。 更新“硬件适配”章节内容。 新增“使用场景典型问题说明”章节内容。
01 | 2024-08-08 | 第一次正式版本发布。
00B01 | 2024-06-11 | 第一次临时版本发布。

# API接口说明

- 结构体说明

- API列表

- 配置说明

## 结构体说明

MbedTLS详细的结构体说明请参考官方说明文档：https://tls.mbed.org/api/annotated.html

## API列表

MbedTLS详细的API说明请参考官方说明文档：https://tls.mbed.org/api/globals_func.html

## 配置说明

MbedTLS详细的配置项说明请参考官方说明文档：https://tls.mbed.org/api/config_8h.html#ab3bca0048342cf2789e7d170548ff3a5

# 开发指南

MbedTLS详细的开发DEMO请参考官方说明文档：https://tls.mbed.org/api/modules.html

# 硬件适配

- 配置说明

- 适配说明

## 配置说明

在工程的“build\config\target_config\ws53\config.py”中的对应编译目标中添加MBEDTLS_HARDEN_OPEN宏，开启硬件加速回调接口注册功能。

在“mbedtls_v3.1.0\harden\platform\connect\mbedtls_platform_hardware_config.h”中开启对应的算法宏，会直接调用硬件驱动接口。

目前支持的硬件算法有AES,RSA,HASH,大数模幂，随机数，ECP算法。

## 适配说明

- AES适配

- 大数模幂适配

- 随机数适配

- RSA数字签名适配

- HASH算法适配

- ECP适配

### AES适配

使能MBEDTLS_AES_ALT后，AES算法在使用硬件加速器时，会锁定硬件加速器资源，即AES操作是阻塞的，直至驱动获取资源或超时返回失败。

### 大数模幂适配

使能MBEDTLS_BIGNUM_EXP_MOD_USE_HARDWARE后，会调用硬件驱动接口完成大数模幂运算。

### 随机数适配

使能MBEDTLS_ENTROPY_HARDWARE_ALT后，系统会选用默认增加硬件随机数作为一个强随机数源。如果此宏被关闭，而用户也没有注册其他强随机数源，会导致MbedTLS无法提供安全随机数，影响系统的安全性。

### RSA数字签名适配

使能MBEDTLS_RSA_ALT编译宏之后，MbedTLS会对RSA数字签名操作和验签操作进行硬件加速。

### HASH算法适配

目前WS53规格支持的硬件加速HASH算法有SHA1、SHA224、SHA256、SHA384、SHA512，分别开启 MBEDTLS_SHA1_USE_HARDWARE、MBEDTLS_SHA224_USE_HARDWARE、MBEDTLS_SHA256_USE_HARDWARE、MBEDTLS_SHA384_USE_HARDWARE、MBEDTLS_SHA512_USE_HARDWARE来使能。

### ECP适配

目前WS53规格支持的硬件加速ECP算法有SECP192R1、SECP224R1、SECP256R1、SECP384R1、SECP521R1、BP256R1、BP384R1、BP512R1、CURVE25519、CURVE448，分别开启MBEDTLS_SECP192R1_USE_HARDWARE、MBEDTLS_SECP224R1_USE_HARDWARE、MBEDTLS_SECP256R1_USE_HARDWARE、MBEDTLS_SECP384R1_USE_HARDWARE、MBEDTLS_SECP521R1_USE_HARDWARE、MBEDTLS_BP256R1_USE_HARDWARE、MBEDTLS_BP384R1_USE_HARDWARE、MBEDTLS_BP512R1_USE_HARDWARE、MBEDTLS_CURVE25519_USE_HARDWARE、MBEDTLS_CURVE448_USE_HARDWARE来开启。

# 注意事项

- 关于配置SSL接收缓存的注意事项

- 关于数字证书有效期验证的注意事项

- 关于部分默认配置变更的说明

- 使用场景典型问题说明

## 关于配置SSL接收缓存的注意事项

- SSL接收缓存由编译项MBEDTLS_SSL_IN_CONTENT_LEN控制，默认为16KB。如果实际应用中，用户可以确保SSL上层数据包的最大长度不超过2KB或4KB，则可以通过mbedtls_ssl_conf_max_frag_len接口设置SSL接收缓存的长度，达到节省内存的目的。

  > 说明： mbedtls_ssl_conf_max_frag_len接口的调用必须先于mbedtls_ssl_setup接口。

- 考虑到多级数字证书可能导致TLS握手包的长度大于1KB，因此调用mbedtls_ssl_conf_max_frag_len接口时，只有mfl_code为MBEDTLS_SSL_MAX_FRAG_LEN_2048或MBEDTLS_SSL_MAX_FRAG_LEN_4096时，MbedTLS才会修改接收缓存；如果mfl_code为MBEDTLS_SSL_MAX_FRAG_LEN_512或MBEDTLS_SSL_MAX_FRAG_LEN_1024，则接收缓存仍然为16KB。

- 如果修改SSL接收缓存为2KB或4KB后，Client端接收到Server端的一个大于2KB或4KB的数据包，此时mbedtls_ssl_read接口会返回失败，错误码为MBEDTLS_ERR_SSL_MSG_TOO_LONG（此为新增的一个特定错误码），当用户获得此错误码时，必须关闭SSL连接，不允许继续从SSL链路接收数据。

- 通过mbedtls_ssl_conf_max_frag_len接口设置SSL接收缓存，目前只对SSL Client有效。

## 关于数字证书有效期验证的注意事项

由于WS53平台无Real Time Controller，因此系统启动后，无法获取UTC时间，这种情况下数字证书的有效期验证会失败，导致TLS建链失败。针对此种情况，MbedTLS默认关闭MBEDTLS_HAVE_TIME_DATE，此时TLS的证书校验会关闭。如果用户可以确保TLS证书校验之前，可以通过其他方式获取UTC时间（例如：SNTP），则可以打开MBEDTLS_HAVE_TIME_DATE编译宏。

## 关于部分默认配置变更的说明

MbedTLS安全库的默认配置见“include/mbedtls/mbedtls_config.h”文件。开源版本默认开启大部分功能，LiteOS对MbedTLS的默认配置进行了适度修改，主要目的是增强MbedTLS的安全性，降低代码体积。修改后的MbedTLS满足IoT绝大部分场景，改动的主要原则如下：

- 默认配置必须保证安全性要求。

- 关闭不安全算法或功能。

- 关闭不适合IoT场景的功能，例如TLS Server模式、X509证书签名请求CSR。

- 关闭不适合IoT场景的算法，例如SECP521R1 ECC曲线，IoT场景下推荐使用128比特安全强度的ECC曲线。

- 关闭不常用算法或功能，例如IoT场景不常用的PKCS#12证书。如果打开PKCS#12，可能存在一定的应用风险。

## 使用场景典型问题说明

- 内外部结构体大小不一致导致的挂死问题

- 算法未完全适配硬加密导致的功能问题

### 内外部结构体大小不一致导致的挂死问题

以SHA256算法举例说明。SHA256实现了硬件加速，在“open_source\mbedtls\mbedtls_v3.1.0\harden\platform\connect\mbedtls_platform_hardware_config.h”中定义了MBEDTLS_SHA256_ALT宏，但是外部调用者并不感知MBEDTLS_SHA256_ALT宏。这样会导致在MBEDTLS_SHA256_ALT宏包含范围中定义的结构体mbedtls_sha256_context不被外部感知。在实际使用场景中，外部和内部mbedtls_sha256_context结构体大小是不一样的，在使用mbedtls_sha256_context结构体内部成员时，会出现指针引用异常导致的挂死问题。为了解决这个问题，必须在调用处的Makefile或者CMakeLists.txt中也打开MBEDTLS_SHA256_ALT。使用其他算法有类似问题也可以用相同的方法处理。

### 算法未完全适配硬加密导致的功能问题

ECP算法未完全适配所有的椭圆曲线类型。在实际使用场景中，如果发现是因为椭圆曲线类型不支持导致的功能问题，可以关闭ECP硬件加速功能。在“open_source\mbedtls\mbedtls_v3.1.0\harden\platform\connect\mbedtls_platform_hardware_config.h”中注释掉MBEDTLS_ECP_MUL_ALT宏。这样ECP算法可以调用软件实现完成椭圆曲线计算。