WS53指导资料
前言¶
本文档主要介绍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\ws53\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算法适配¶
目前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接收缓存由编译项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算法可以调用软件实现完成椭圆曲线计算。