arduino/esp8266
1
0
Fork 0
mirror of https://github.com/esp8266/Arduino.git synced 2025-07-27 18:02:17 +03:00
Code Activity

Add BearSSL documentation (#5311)

Browse Source 
Document the BearSSL::WiFiClientSecure, ::WiFiServerSecure, and the
helper classes required to use them.
This commit is contained in:
Earle F. Philhower, III
2018-11-06 11:45:52 -08:00
committed by GitHub
parent 6e0c0e3dcc
commit feb86cd4ff
3 changed files with 279 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
doc/esp8266wifi/readme.rst
View File

@ -157,18 +157,32 @@ The Client class creates `clients <https://en.wikipedia.org/wiki/Client_(computi
Check out separate section with `examples <client-examples.rst>`__ / `list of functions <client-class.rst>`__
Client Secure
~~~~~~~~~~~~~
axTLS Client Secure - DEPRECATED
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Client Secure is an extension of `Client Class <#client>`__ where connection and data exchange with servers is done using a `secure protocol <https://en.wikipedia.org/wiki/Transport_Layer_Security>`__. It supports `TLS 1.1 <https://en.wikipedia.org/wiki/Transport_Layer_Security#TLS_1.1>`__. The `TLS 1.2 <https://en.wikipedia.org/wiki/Transport_Layer_Security#TLS_1.2>`__ is not supported.
The following section details axTLS, the older TLS library used by the project. It is still supported, but additional fixes and documentation will generally not be undertaken. See the following section for the updated TLS client object.
.. figure:: pictures/esp8266-client-secure.png
:alt: ESP8266 operating as the Client Secure
The axTLS Client Secure is an extension of `Client Class <#client>`__ where connection and data exchange with servers is done using a `secure protocol <https://en.wikipedia.org/wiki/Transport_Layer_Security>`__. It supports `TLS 1.1 <https://en.wikipedia.org/wiki/Transport_Layer_Security#TLS_1.1>`__. The `TLS 1.2 <https://en.wikipedia.org/wiki/Transport_Layer_Security#TLS_1.2>`__ is not supported.
Secure applications have additional memory (and processing) overhead due to the need to run cryptography algorithms. The stronger the certificate's key, the more overhead is needed. In practice it is not possible to run more than a single secure client at a time. The problem concerns RAM memory we can not add, the flash memory size is usually not the issue. If you like to learn how `client secure library <https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266WiFi/src/WiFiClientSecure.h>`__ has been developed, access to what servers have been tested, and how memory limitations have been overcame, read fascinating issue report `#43 <https://github.com/esp8266/Arduino/issues/43>`__.
Check out separate section with `examples <client-secure-examples.rst>`__ / `list of functions <client-secure-class.rst>`__
BearSSL Client Secure and Server Secure
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
`BearSSL::WiFiClientSecure` and `BearSSL::WiFiServerSecure` are extensions of the standard `Client <#client>`__ and `Server <#server>`__ classes where connection and data exchange with servers and clients using `secure protocol <https://en.wikipedia.org/wiki/Transport_Layer_Security>`__. It supports `TLS 1.2 <https://en.wikipedia.org/wiki/Transport_Layer_Security#TLS_1.2>`__ using a wide variety of modern ciphers, hashes, and key types.
.. figure:: pictures/esp8266-client-secure.png
:alt: ESP8266 operating as the Client Secure
Secure clients and servers require siginificant amounts of additional memory and processing to enable their cryptographic algorithms. In general only a single secure client or server connection at a time can be processed given the little RAM present on the ESP8266, but there are methods of reducing this RAM requirement detailed in the relevant sections.
`BearSSL::WiFiClientSecure <bearssl-client-secure-class.rst>`__ contains more information on using and configuring TLS connections.
`BearSSL::WiFiServerSecure <bearssl-server-secure-class.rst>`__ discusses the TLS server mode available. Please read and understand the `BearSSL::WiFiClientSecure <bearssl-client-secure-class.rst>`__ first as the server uses most of the same concepts.
Server
~~~~~~