Edit On Gitee
前言
本文档主要介绍TLS/DTLS组件的开发实现示例。
TLS/DTLS以及其他加密套基于开源组件mbedtls 3.1.0实现，详细说明请参见官方说明：https://tls.mbed.org/api/index.html
如果官方说明版本与SDK版本不一致，请参考官方release说明：https://github.com/ARMmbed/mbedtls/releases
与本文档相对应的产品版本如下。
本文档主要适用于以下工程师：
技术支持工程师
软件开发工程师
在本文中可能出现下列标志，它们所代表的含义如下。
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\ws63\config.py中的对应编译目标中添加MBEDTLS_HARDEN_OPEN宏，开启硬件加速回调接口注册功能。
在mbedtls_v3.1.0\harden\platform\connect\mbedtls_platform_hardware_config.h中开启对应的算法宏，会直接调用硬件驱动接口。
目前支持的硬件算法有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算法适配
目前WS63规格支持的硬件加速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适配
目前WS63规格支持的硬件加速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接收缓存由编译项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有效。
关于数字证书有效期验证的注意事项
由于WS63平台无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，可能存在一定的应用风险。
关于FCC认证默认配置变更说明
FCC认证为EMC强制性认证, 主要针对 9K-3000GHZ的电子电器产品，内容涉及无线电、通信等各方面。FCC认证过程依赖KEY_EXCHANGE_ECDHE_RSA算法，此算法默认未开启。如果设备有通过FCC认证的需求，可以开启此算法。开启方法：修改open_source/mbedtls/mbedtls_v3.1.0/harden/platform/connect/mbedtls_platform_hardware_config.h文件，将#undef MBEDTLS_KEY_EXCHANGE_ECDHE_RSA_ENABLED注释掉。