DIY - ESP8266：ESP8266 SDK ESPCONN SSL 網路介面函數（三十三）

DIY - ESP8266：ESP8266 SDK ESPCONN SSL 網路介面函數（三十三）：

Espressif（樂鑫）除了提供 TCP 和 UDP 的網路 ESPCONN 網路介面函數（ESPCONN Network API）外，還有提供安全鏈路層（Secure Sockets Layer， SSL）的網路介面函數（ESPCONN TCP SSL Network API），SSL（ Secure Sockets Layer ）是網景公司（ Netscape ）設計主要用於 Web 的安全傳輸協議，在網頁伺服器和瀏覽器之間以加解密方式溝通的安全技術標準，這種協議在 Web 上獲得了廣泛的應用。

ESP8266 SDK ESPCONN TCP SSL 網路介面函數

TCP SSL 網路介面運作

ESPCONN TCP SSL 網路介面函數（ESPCONN TCP SSL Network API）： 

1. espconn_secure_accept 
2. espconn_secure_delete 
3. espconn_secure_set_size 
4. espconn_secure_get_size 
5. espconn_secure_connect 
6. espconn_secure_send 
7. espconn_secure_sent 
8. espconn_secure_disconnect 
9. espconn_secure_ca_enable 
10. espconn_secure_ca_disable 
11. espconn_secure_cert_req_enable 
12. espconn_secure_cert_req_disable 
13. espconn_secure_set_default_certificate 
14. espconn_secure_set_default_private_key

espconn_secure_accept
功能	創建 SSL TCP server，加密偵聽 SSL 握手
函數定義	sint8 espconn_secure_accept(struct espconn *espconn)
輸入參數	struct espconn *espconn - 相應連接的控制塊結構
返回	0：成功 其他：失敗，返回錯誤碼 • ESPCONN_ARG：未找到參數 espconn 對應的 TCP 連接 • ESPCONN_MEM：空間不足 • ESPCONN_ISCONN：連接已經建立
注意	• 目前僅支持建立一個 SSL server，本接口只能調用一次，並且僅支持連入一個 SSL client。 • 如果 SSL 加密一包資料大於 espconn_secure_set_size 設置的緩存空間，ESP8266 無法處理，SSL 連接斷開，進入 espconn_reconnect_callback。 • SSL 相關接口與普通 TCP 接口底層處理不一致，請不要混用。SSL 連接時，僅支援使用 espconn_secure_XXX 系列接口和 espconn_regist_XXXcb 系列註冊回調函數的接口，以及espconn_port 獲得一個空閒端口。 • 如需創建 SSL server，必須先調用 espconn_secure_set_default_certificate 和espconn_secure_set_default_private_key 傳入證書和密鑰。

espconn_secure_delete
功能	刪除 ESP8266 作為 SSL server 的連接
函數定義	sint8 espconn_secure_delete(struct espconn *espconn)
輸入參數	struct espconn *espconn：對應網路連接的結構體
返回	0：成功 其他：失敗，返回錯誤碼 • ESPCONN_ARG：未找到參數 espconn 對應的 TCP 連接 • ESPCONN_INPROGRESS：參數 espconn 對應的 SSL 連接仍未斷開，請先調用 espconn_secure_disconnect 斷開連接，再進行刪除。

espconn_secure_set_size
功能	設置加密 (SSL) 資料緩存空間的大小
函數定義	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：失敗
注意	默認緩存大小為 2KB；如需更更改，請在加密 (SSL) 連接建立前調用： 在 espconn_secure_accept（ESP8266 作為 TCP SSL server）之前調用；或者 espconn_secure_connect（ESP8266 作為 TCP SSL client）之前調用

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) 資料緩存空間的大小

espconn_secure_connect
功能	加密 (SSL) 連接到 TCP SSL server（ESP8266 作為 TCP SSL client）
函數定義	sint8 espconn_secure_connect (struct espconn *espconn)
輸入參數	struct espconn *espconn：對應網路連接的結構體
返回	0：成功 其他：失敗，返回錯誤碼 • ESPCONN_ARG：未找到參數 espconn 對應的 TCP 連接 • ESPCONN_MEM：空間不足 • ESPCONN_ISCONN：連接已經建立
注意	• 如果 espconn_secure_connect 失敗，返回非零值，連接未建立，不會進入任何 espconn callback。 • 目前 ESP8266 作為 SSL client 僅支持一個連接，本接口只能調用一次，或者調用espconn_secure_disconnect 斷開前一次連接，才可以再次調用本接口建立 SSL 連接； • 如果 SSL 加密一包資料大於 espconn_secure_set_size 設置的緩存空間，ESP8266 無法處理，SSL 連接斷開，進入espconn_reconnect_callback • SSL 相關接口與普通 TCP 接口底層處理不一致，請不要混用。SSL 連接時，僅支援使用 espconn_secure_XXX 系列接口和 espconn_regist_XXXcb 系列註冊回調函數的接口，以及espconn_port 獲得一個空閒端口。

espconn_secure_send
功能	發送加密資料 (SSL)
函數定義	sint8 espconn_secure_send ( struct espconn *espconn, uint8 *psent, uint16 length )
輸入參數	struct espconn *espconn：對應網路連接的結構體 uint8 *psent：發送的資料 uint16 length：發送的資料長度
返回	0：成功 其他：失敗，返回錯誤碼 ESPCONN_ARG：未找到參數 espconn 對應的 TCP 連接
注意	• 請在上一包資料發送完成，進入 espconn_sent_callback 後，再發下一包數據。 • 每一包資料明文的上限值為 1024 位元組，加密後的報文上限值是 1460 位元組。

espconn_secure_sent
功能	發送加密資料 (SSL)
函數定義	sint8 espconn_secure_sent ( struct espconn *espconn, uint8 *psent, uint16 length )
輸入參數	struct espconn *espconn：對應網路連接的結構體 uint8 *psent：發送的資料 uint16 length：發送的資料長度
返回	0：成功 其他：失敗，返回錯誤碼 ESPCONN_ARG：未找到參數 espconn 對應的 TCP 連接
注意	本接口不建議使用，建議使用 espconn_secure_send 代替。 • 請在上一包資料發送完成，進入 espconn_sent_callback 後，再發下一包數據。 • 每一包資料明文的上限值為 1024 位元組，加密後的報文上限值是 1460 位元組。

espconn_secure_disconnect
功能	斷開加密 TCP 連接 (SSL)
函數定義	sint8 espconn_secure_disconnect(struct espconn *espconn)
輸入參數	struct espconn *espconn：對應網路連接的結構體
返回	0：成功 其他：失敗，返回錯誤碼 ESPCONN_ARG：未找到參數 espconn 對應的 TCP 連接
注意	請勿在 espconn 的任何 callback 中調用本接口斷開連接。如有需要，可以在 callback 中使用任務觸發調用本接口斷開連接。

espconn_secure_ca_enable
功能	開啟 SSL CA 認證功能
函數定義	bool espconn_secure_ca_enable (uint8 level, uint32 flash_sector)
輸入參數	• uint8 level：設置 ESP8266 SSL server/client - 0x01：SSL client - 0x02：SSL server - 0x03：SSL client 和 SSL server • uint32 flash_sector：設置 CA 證書 esp_ca_cert.bin 燒錄到 Flash 的位置。例如，參數傳入 0x3B，則對應燒錄到 Flash 0x3B000
返回	true：成功 false：失敗
注意	• CA 認證功能，默認關閉，詳細介紹可參考文檔 ESP8266 SSL 加密使用手冊。 • 如需調用本接口，請在加密 (SSL) 連接建立前調用： - 在 espconn_secure_accept（ESP8266 作為 TCP SSL server）之前調用； - 或者 espconn_secure_connect（ESP8266 作為 TCP SSL client）之前調用

espconn_secure_ca_disable
功能	關閉 SSL CA 認證功能
函數定義	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：失敗
注意	• CA 認證功能，默認關閉，詳細介紹可參考文檔 ESP8266 SSL 加密使用手冊。 • 如需調用本接口，請在加密 (SSL) 連接建立前調用： - 在 espconn_secure_accept（ESP8266 作為 TCP SSL server）之前調用； - 或者 espconn_secure_connect（ESP8266 作為 TCP SSL client）之前調用

espconn_secure_cert_req_enable
功能	使能 ESP8266 作為 SSL client 時的證書認證功能
函數定義	bool espconn_secure_cert_req_enable (uint8 level, uint32 flash_sector)
輸入參數	• uint8 level：僅支持設置為 0x01 ESP8266 作為 SSL client • uint32 flash_sector：設置密鑰 esp_cert_private_key.bin 燒錄到 Flash 的位置，例如，參數傳入 0x3A，則對應燒錄到 Flash 0x3A000。請注意，不要覆蓋了了代碼或系統參數區域。
返回	true：成功 false：失敗
注意	• 證書認證功能，默認關閉。如果伺服器端不要求認證證書，則無需調用本接口。 • 如需調用本接口，請在 espconn_secure_connect 之前調用。

espconn_secure_cert_req_disable
功能	關閉 ESP8266 作為 SSL client 時的證書認證功能
函數定義	bool espconn_secure_ca_disable (uint8 level)
輸入參數	uint8 level：僅支持設置為 0x01 ESP8266 作為 SSL client
返回	true：成功 false：失敗
注意	證書認證功能，默認關閉。

espconn_secure_set_default_certificate
功能	設置 ESP8266 作為 SSL server 時的證書
函數定義	bool espconn_secure_set_default_certificate (const uint8_t* certificate, uint16_t length)
輸入參數	const uint8_t* certificate：證書指針 uint16_t length：證書長度
返回	true：成功 false：失敗
注意	• ESP8266_NONOS_SDK/examples/IoT_Demo 中提供使用示例 • 本接口必須在 espconn_secure_accept 之前調用，傳入證書資訊

espconn_secure_set_default_private_key
功能	設置 ESP8266 作為 SSL server 時的密鑰
函數定義	bool espconn_secure_set_default_private_key (const uint8_t* key, uint16_t length)
輸入參數	const uint8_t* key：密鑰指針 uint16_t length：密鑰長度
返回	true：成功 false：失敗
注意	• ESP8266_NONOS_SDK/examples/IoT_Demo 中提供使用示例 • 本接口必須在 espconn_secure_accept 之前調用，傳入密鑰資訊

2017年 6月 9日 天氣報告

氣溫：30.2度 @ 19:50

相對濕度：百分之 79%

天氣：天色大致良好