diff --git a/docs/esp8266/general.rst b/docs/esp8266/general.rst index ce51f531b9..4999bc2e9b 100644 --- a/docs/esp8266/general.rst +++ b/docs/esp8266/general.rst @@ -163,25 +163,26 @@ SSL/TLS limitations ~~~~~~~~~~~~~~~~~~~ ESP8266 uses `axTLS `_ library, which is one -of the smallest TLS libraries with the compatible licensing. However, it +of the smallest TLS libraries with compatible licensing. However, it also has some known issues/limitations: 1. No support for Diffie-Hellman (DH) key exchange and Elliptic-curve - cryptography (ECC). This means it can't work with sites which force - the use of these features (it works ok with classic RSA certificates). + cryptography (ECC). This means it can't work with sites which require + the use of these features (it works ok with the typical sites that use + RSA certificates). 2. Half-duplex communication nature. axTLS uses a single buffer for both sending and receiving, which leads to considerable memory saving and works well with protocols like HTTP. But there may be problems with protocols which don't follow classic request-response model. -Besides axTLS own limitations, the configuration used for MicroPython is +Besides axTLS's own limitations, the configuration used for MicroPython is highly optimized for code size, which leads to additional limitations (these may be lifted in the future): 3. Optimized RSA algorithms are not enabled, which may lead to slow SSL handshakes. -4. Stored sessions are not supported (may allow faster repeated connections - to the same site in some circumstances). +4. Session Reuse is not enabled, which means every connection must undergo + the full, expensive SSL handshake. Besides axTLS specific limitations described above, there's another generic limitation with usage of TLS on the low-memory devices: @@ -195,13 +196,16 @@ limitation with usage of TLS on the low-memory devices: accessing various REST APIs, which usually require much smaller messages. The buffers size is on the order of 5KB, and is adjusted from time to time, taking as a reference being able to access https://google.com . - The smaller buffer hower means that some sites can't be accessed using - it, and it's not possible to stream large amounts of data. + The smaller buffer however means that some sites can't be accessed using + it, and it's not possible to stream large amounts of data. axTLS does + have support for TLS's Max Fragment Size extension, but no HTTPS website + does, so use of the extension is really only effective for local + communication with other devices. There are also some not implemented features specifically in MicroPython's ``ussl`` module based on axTLS: -6. Certificates are not validated (this may make connections susceptible +6. Certificates are not validated (this makes connections susceptible to man-in-the-middle attacks). 7. There is no support for client certificates (scheduled to be fixed in 1.9.4 release).