ESP8266 SDK SSL User Manual CN V1.0

User Manual:

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

Download
Open PDF In Browser	View PDF

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

2/14

Friday, June 12, 2015

"

"

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

3/14

Friday, June 12, 2015

"

"

Espressif Systems

ESP8266 SSL User Manual
"

1.

前⾔言
本⽂文主要介绍基于 ESP8266 物联⺴⽹网模块的 SDK SSL 加密使⽤用⽅方法，将分别介绍 ESP8266 作为

SSL server 和 ESP8266 作为 SSL client 的使⽤用⽅方法。
更多 ESP8266 的信息，请访问：http://bbs.espressif.com/

Espressif Systems Confidential

4/14

Friday, June 12, 2015

"

"

Espressif Systems

2.

ESP8266 SSL User Manual
"

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

5/14

Friday, June 12, 2015

"

"

Espressif Systems

ESP8266 SSL User Manual
"

•

输⼊入指令 ./mount.sh ，回⻋车

•

输⼊入密码 espressif ，回⻋车

(3) 在虚拟机打开共享⽂文件夹，看到证书制作脚本，挂载成功。

Espressif Systems Confidential

6/14

Friday, June 12, 2015

"

"

Espressif Systems

ESP8266 SSL User Manual
"

(4) 在脚本所在路径，运⾏行脚本，指令 ./makefile.sh ，⽣生成 cert.h 和 private_key.h，参考
IOT_Demo 使⽤用这两个头⽂文件即可。

运⾏行成功，⽣生成如下：

注意事项
•

证书制作脚本 makefile.sh ⽂文件中的 IP 地址，请改为⽤用户实际的 server IP ，如下图：

Espressif Systems Confidential

7/14

Friday, June 12, 2015

"

"

•

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

8/14

Friday, June 12, 2015

"

"

Espressif Systems

3.

ESP8266 SSL User Manual
"

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

9/14

Friday, June 12, 2015

"

"

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 认证功能
注意：
•

CA 认证功能，默认关闭

•

如需调⽤用本接⼝口，请在加密（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

10/14

Friday, June 12, 2015

"

"

Espressif Systems

4.2.

ESP8266 SSL User Manual
"

espconn_secure_ca_enable

功能:
开启 SSL CA 认证功能
注意：
•

CA 认证功能，默认关闭

•

如需调⽤用本接⼝口，请在加密（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

11/14

Friday, June 12, 2015

"

"

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

12/14

Friday, June 12, 2015

"

"

Espressif Systems

4.5.

ESP8266 SSL User Manual
"

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

13/14

Friday, June 12, 2015

"

"

Espressif Systems

4.7.

ESP8266 SSL User Manual
"

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

14/14

Friday, June 12, 2015



---

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
Linearized                      : No
Page Count                      : 14
PDF Version                     : 1.4
Title                           : 2E-ESP8266__SDK__SSL_User_Manual__CN_v1.0
Producer                        : Mac OS X 10.10.3 Quartz PDFContext
Creator                         : Pages
Create Date                     : 2015:07:03 11:40:19Z
Modify Date                     : 2015:07:03 11:40:19Z

EXIF Metadata provided by EXIF.tools