ESP8266 SDK SSL User Manual CN V1.0

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 14

!
!
!
ESP8266 SSL 加密使册
Version 1.0
Espressif Systems IOT Team
Copyright (c) 2015
!
" " !"
Espressif Systems
ESP8266 SSL User Manual
免责申明和版权公告
本中的信息，包括供参考的URL地址，如有变更，恕不另通知。
档“按现状”提供，不负任何担保责任，包括对适销性、适于特定途或侵权性的任何担保，和任何
提案、规格或样品在他处提到的任何担保。本档不负任何责任，包括使本档内信息产的侵犯任
何专利权为的责任。本档在此未以禁反或其他式授予任何知识产权使许可，不管是明许
可还是暗许可。
Wi-Fi联盟成员标志归Wi-Fi联盟所有。
中提到的所有商标名称、商标和注册商标均属其各所有者的财产，特此声明。
版权归© 2015 乐鑫信息科技（上海）有限公司所有。保留所有权利。
Espressif Systems Confidential / Friday, June 12, 2015 2 14
!
" " !"
Espressif Systems
ESP8266 SSL User Manual
Table of Contents
1. 前!4"...................................................................................................................
2. ESP8266 作为 SSL server!5"............................................................................
2.1. 证书制作!5"........................................................................................
3. ESP8266 作为 SSL client!9".............................................................................
3.1. 证书制作!9"........................................................................................
3.2. CA 认证流程!9"..................................................................................
4. 软件接!10".....................................................................................................
4.1. espconn_secure_ca_disable!10".......................................................
4.2. espconn_secure_ca_enable!11"........................................................
4.3. espconn_secure_accept!11".............................................................
4.4. espconn_secure_set_size!12"...........................................................
4.5. espconn_secure_get_size!13"...........................................................
4.6. espconn_secure_connect!13"...........................................................
4.7. espconn_secure_sent!14".................................................................
4.8. espconn_secure_disconnect!14......................................................
Espressif Systems Confidential / Friday, June 12, 2015 3 14
!
" " !"
Espressif Systems
ESP8266 SSL User Manual
1. 前
本主要介绍基于 ESP8266 物联模块的 SDK SSL 加密使法，将分别介绍 ESP8266 作为
SSL server 和 ESP8266 作为 SSL client 的使法。
更多 ESP8266 的信息，请访问：http://bbs.espressif.com/
Espressif Systems Confidential / Friday, June 12, 2015 4 14
!
" " !"
Espressif Systems
ESP8266 SSL User Manual
2. ESP8266 作为 SSL server
ESP8266 作为 SSL server 时，提供加密证书的制作脚本，成 SSL 加密所需的头件。户可
以参考 IOT_Demo 中 #define SERVER_SSL_ENABLE 宏定义的代码，实现 SSL server 功能。
CA 认证功能默认关闭，户可调接 espconn_secure_ca_enable 使能 CA 认证。
2.1. 证书制作
(1) 户可向 Espressif Systems 申请 ESP8266 SSL server 证书制作脚本 “makefile.sh”，将脚本拷到
lubuntu 虚拟机共享路径下。 lubuntu 虚拟机编译环境可在 Espressif BBS 下载，
•下载链接： http://bbs.espressif.com/viewtopic.php?f=21&t=86
(2) 挂载共享路径。
•打开虚拟机桌的 “LXTerminal”
Espressif Systems Confidential / Friday, June 12, 2015 5 14
!
" " !"
Espressif Systems
ESP8266 SSL User Manual
•输指令 ./mount.sh ，回
•输密码 espressif ，回
(3) 在虚拟机打开共享件夹，看到证书制作脚本，挂载成功。
Espressif Systems Confidential / Friday, June 12, 2015 6 14
!
" " !"
Espressif Systems
ESP8266 SSL User Manual
Espressif Systems Confidential / Friday, June 12, 2015 7 14
!
" " !"
Espressif Systems
ESP8266 SSL User Manual
•证书制作脚本 makefile.sh 默认为 1024 的加密算法位数度；如需使 512 的加密算法位数，
请修改 makefile.sh 件中的 1024 改为 512 ：
•证书制作脚本 makefile.sh 成的默认 SSL server 证书由 Espressif Systems 颁发，并由 CA 颁
发。如果户需要 CA 认证，有以下两种式：
‣户将脚本 makefile.sh 运成的 TLS . ca_x509.cer 导 SSL client，并参考后 3.1 证书
制作 使脚本 “make_cert.py” 将 CA 件成 esp_ca_cert.bin 烧写到 flash 对应的地址；
‣户使签发的证书，参考脚本 makefile.sh，成对应的 cert.h 和 private_key.h，并参
考后 3.1 证书制作 使脚本 “make_cert.py” 将 CA 件成 “esp_ca_cert.bin” 烧写到
flash 对应的地址。
Espressif Systems Confidential / Friday, June 12, 2015 8 14
!
" " !"
Espressif Systems
ESP8266 SSL User Manual
3. ESP8266 作为 SSL client
户可以参考 IOT_Demo 中 #define CLIENT_SSL_ENABLE 宏定义的代码，实现 SSL client 功
能。ESP8266 作为 SSL client 时，可持 CA 认证。
CA 认证功能默认关闭，户可调接 espconn_secure_ca_enable 使能 CA 认证。
3.1. 证书制作
(1) 户可向 Espressif Systems 申请 ESP8266 SSL client 证书合成脚本 “make_cert.py”，将合成脚本与
CA 件放在同录下。
(2) 运脚本 “make_cert.py” 将合成同录下的 CA 件（前持最多 2 个 CA 证书）成
esp_ca_cert.bin， esp_ca_cert.bin 的烧录位置由接 espconn_secure_ca_enable 设置，户可
定义。
3.2. CA 认证流程
(1) ESP8266 作为 client 发起 TCP 连接，成功建，读取 flash 中的 esp_ca_cert.bin (CA 证书)，加载
到对应的 SSL ctx，前限定的 CA 最持数为 2 个。
(2) ESP8266 发起 TLS handshake，获取 SSL server 签发的证书，与 ESP8266 持的 CA 进验证：
•若失败，则断开当前连接；
•若成功，完成验证。
Espressif Systems Confidential / Friday, June 12, 2015 9 14
!
" " !"
Espressif Systems
ESP8266 SSL User Manual
4. 软件接
SSL 系列软件接与普通 TCP 软件接，在 SDK 底层是两套不同的处理流程，因此，请不要混
两种软件接。SSL 连接时，仅持使：
• espconn_secure_XXX 系列接；
• espconn_regist_XXX 系列注册回调的接；
• espconn_port 获得个空闲端。
本仅介绍 espconn_secure_XXX 系列接，更多的软件接介绍，请参考 ESP8266 编程册
“2C-ESP8266__SDK__Programming Guide”
SSL 连接，户可参考 BBS 提供的 Demo http://bbs.espressif.com/viewtopic.php?f=21&t=389
4.1. espconn_secure_ca_disable
功能: !
关闭 SSL CA 认证功能
注意：
• C A 认证功能，默认关闭
•如需调本接，请在加密（SSL）连接建前调：
在 espconn_secure_accept (ESP8266 作为 TCP SSL server) 之前调；
或者 espconn_secure_connect (ESP8266 作为 TCP SSL client) 之前调
函数定义: !
bool espconn_secure_ca_disable (uint8 level)
参数: !
uint8 level : 设置 ESP8266 SSL server/client：
0x01 SSL client；
0x02 SSL server；
0x03 SSL client 和 SSL server
返回: !
true : 成功!
false : 失败"
Espressif Systems Confidential / Friday, June 12, 2015 10 14
!
" " !"
Espressif Systems
ESP8266 SSL User Manual
4.2. espconn_secure_ca_enable
功能: !
开启 SSL CA 认证功能
注意：
• C A 认证功能，默认关闭
•如需调本接，请在加密（SSL）连接建前调：
在 espconn_secure_accept (ESP8266 作为 TCP SSL server) 之前调；
或者 espconn_secure_connect (ESP8266 作为 TCP SSL client) 之前调
函数定义: !
bool espconn_secure_ca_enable (uint8 level, uint16 flash_sector)
参数: !
uint8 level : 设置 ESP8266 SSL server/client：
0x01 SSL client；
0x02 SSL server；
0x03 SSL client 和 SSL server
uint16 flash_sector : 设置 CA 证书 (esp_ca_cert.bin) 烧录到 flash 的位
置，例如，参数传 0x3B，则对应烧录到 flash 0x3B000
返回: !
true : 成功!
false : 失败
4.3. espconn_secure_accept
功能: !
创建 SSL TCP server，侦听 SSL 握。
注意：
•本接只能调次
•仅持建个 SSL server，并且仅持连个 SSL client。
•如果 SSL 加密包数据于 espconn_secure_set_size 设置的缓存空间，
ESP8266 法处理，SSL 连接断开，进 espconn_reconnect_callback
Espressif Systems Confidential / Friday, June 12, 2015 11 14
!
" " !"
Espressif Systems
ESP8266 SSL User Manual
函数定义: !
sint8 espconn_secure_accept(struct espconn *espconn)
参数: !
struct espconn *espconn : 对应络连接的结构体
返回: !
0 : 成功!
Non-0 : 失败，返回错误码 !
ESPCONN_ARG - 未找到参数 espconn 对应的 TCP 连接
ESPCONN_MEM - 空间不
ESPCONN_ISCONN - 连接已经建
4.4. espconn_secure_set_size
功能: !
设置加密 (SSL) 数据缓存空间的
注意：
• 默认缓存为 2KBytes；如需更改，请在加密（SSL）连接建前调：
‣在 espconn_secure_accept (ESP8266 作为 TCP SSL server) 之前调；
‣或 espconn_secure_connect (ESP8266 作为 TCP SSL client) 之前调
函数定义: !
bool espconn_secure_set_size (uint8 level, uint16 size)
参数: !
uint8 level : 设置 ESP8266 SSL server/client：
0x01 SSL client；
0x02 SSL server；
0x03 SSL client 和 SSL server
uint16 size : 加密数据缓存的空间，取值范围：1 ~ 8192，单位：字节
默认值为 2048
返回: !
true : 成功!
false : 失败
Espressif Systems Confidential / Friday, June 12, 2015 12 14
!
" " !"
Espressif Systems
ESP8266 SSL User Manual
4.5. espconn_secure_get_size
功能: !
查询加密 (SSL) 数据缓存空间的
函数定义: !
sint16 espconn_secure_get_size (uint8 level)
参数: !
uint8 level : 设置 ESP8266 SSL server/client：
0x01 SSL client；
0x02 SSL server；
0x03 SSL client 和 SSL server
返回: !
加密 (SSL) 数据缓存空间的
4.6. espconn_secure_connect
功能: !
加密 (SSL) 连接到 TCP SSL server (ESP8266 作为 TCP SSL client)
注意：
•前 ESP8266 作为 SSL client 仅持个连接，本接如需多次调，请先调
espconn_secure_disconnect 断开前次连接，再建下个 SSL 连接；
•如果 SSL 加密包数据于 espconn_secure_set_size 设置的缓存空间，
ESP8266 法处理，SSL 连接断开，进 espconn_reconnect_callback
函数定义: !
sint8 espconn_secure_connect (struct espconn *espconn)
参数: !
struct espconn *espconn : 对应络连接的结构体
返回: !
0 : 成功!
Non-0 : 失败，返回错误码
ESPCONN_ARG - 未找到参数 espconn 对应的 TCP 连接
ESPCONN_MEM - 空间不
ESPCONN_ISCONN - 传输已经建
Espressif Systems Confidential / Friday, June 12, 2015 13 14
!
" " !"
Espressif Systems
ESP8266 SSL User Manual
4.7. espconn_secure_sent
功能:
发送加密数据 (SSL)
函数定义: !
sint8 espconn_secure_sent (!
struct espconn *espconn, !
uint8 *psent, !
uint16 length!
)
参数: !
struct espconn *espconn : 对应络连接的结构体!
uint8 *psent : 发送的数据!
uint16 length : 发送的数据度
返回: !
0 : 成功!
Non-0 : 失败，返回错误码 ESPCONN_ARG - 未找到参数 espconn 对应的 TCP 连接
4.8. espconn_secure_disconnect
功能:
断开加密 TCP 连接(SSL)
函数定义: !
sint8 espconn_secure_disconnect(struct espconn *espconn)
参数: !
struct espconn *espconn : 对应络连接的结构体
返回: !
0 : 成功!
Non-0 : 失败，返回错误码 ESPCONN_ARG - 未找到参数 espconn 对应的 TCP 连接
Espressif Systems Confidential / Friday, June 12, 2015 14 14

Navigation menu