Commit ad9f3bdb authored by Nathaniel Wesley Filardo's avatar Nathaniel Wesley Filardo Committed by Marcel Stör
Browse files

Be more assertive in the TLS documentation (#2874)

We just don't have the memory to be a real TLS client on the 8266.  Put
that in a big box and point at it from the http and mqtt modules; others
may also wish to give reference.
parent 7d02e5a7
...@@ -20,7 +20,10 @@ to make it easy to access. If there are multiple headers of the same name, then ...@@ -20,7 +20,10 @@ to make it easy to access. If there are multiple headers of the same name, then
**SSL/TLS support** **SSL/TLS support**
Take note of constraints documented in the [net module](net.md). !!! attention
Secure (`https`) connections come with quite a few limitations. Please see
the warnings in the [tls module](tls.md)'s documentation.
## http.delete() ## http.delete()
......
...@@ -132,6 +132,11 @@ Connects to the broker specified by the given host, port, and secure options. ...@@ -132,6 +132,11 @@ Connects to the broker specified by the given host, port, and secure options.
- `function(client)` callback function for when the connection was established - `function(client)` callback function for when the connection was established
- `function(client, reason)` callback function for when the connection could not be established. No further callbacks should be called. - `function(client, reason)` callback function for when the connection could not be established. No further callbacks should be called.
!!! attention
Secure (`https`) connections come with quite a few limitations. Please see
the warnings in the [tls module](tls.md)'s documentation.
#### Returns #### Returns
`true` on success, `false` otherwise `true` on success, `false` otherwise
......
...@@ -20,20 +20,29 @@ most common features supported. Specifically, it provides: ...@@ -20,20 +20,29 @@ most common features supported. Specifically, it provides:
- key exchange algorithms: DHE and ECDHE - key exchange algorithms: DHE and ECDHE
- elliptic curves: secp{256,384}r1, secp256k1, bp{256,384}. - elliptic curves: secp{256,384}r1, secp256k1, bp{256,384}.
!!! tip !!! warning
If possible, you will likely be much better served by using the ECDSA
signature and key exchange algorithms than by using RSA. An
increasingly large fraction of the Internet understands ECDSA, and most
server software can speak it as well. The much smaller key size (at
equivalent security!) is beneficial for NodeMCU's limited RAM.
https://wiki.openssl.org/index.php/Command_Line_Elliptic_Curve_Operations
details how to create ECDSA keys and certificates.
!!! tip The severe memory constraints of the ESP8266 mean that the `tls` module
The complete configuration is stored in [user_mbedtls.h](../../app/include/user_mbedtls.h). This is the file to edit if you build your own firmware and want to change mbed TLS behavior. is by far better suited for communication with custom, purpose-built
endpoints with small certificate chains (ideally, even self-signed)
than it is with the Internet at large. By default, our mbedTLS
configuration requests TLS fragments of at most 4KiB and is unwilling
to process fragmented messages, meaning that the entire ServerHello,
which includes the server's certificate chain, must conform to this
limit. We do not believe it useful or easy to be fully compliant with
the TLS specification, which requires a 16KiB recieve buffer and,
therefore, 32KiB of heap within mbedTLS, even in the steady-state.
While it is possible to slightly raise the buffer sizes with custom
nodeMCU builds, connecting to endpoints out of your control will remain
a precarious position, and so we strongly suggest that TLS connections
be made only to endpoints under your control, whose TLS configurations
can ensure that their ServerHello messages are small. A reasonable
compromise is to have a "real" computer do TLS proxying for you; the
[socat](http://www.dest-unreach.org/socat/) program is one possible
mechanism of achieving such a "bent pipe" with TLS on both halves.
!!! warning !!! warning
The TLS glue provided by Espressif provides no interface to TLS SNI. The TLS glue provided by Espressif provides no interface to TLS SNI.
As such, NodeMCU TLS should not be expected to function with endpoints As such, NodeMCU TLS should not be expected to function with endpoints
requiring the use of SNI, which is a growing fraction of the Internet requiring the use of SNI, which is a growing fraction of the Internet
...@@ -43,15 +52,38 @@ most common features supported. Specifically, it provides: ...@@ -43,15 +52,38 @@ most common features supported. Specifically, it provides:
pair. pair.
!!! warning !!! warning
The TLS handshake is very heap intensive, requiring between 25 and 30 The TLS handshake is very heap intensive, requiring between 25 and 30
**kilobytes** of heap. Some, but not all, of that is made available **kilobytes** of heap, even with our reduced buffer sizes. Some, but
again once the handshake has completed and the connection is open. not all, of that is made available again once the handshake has
Because of this, we have disabled mbedTLS's support for connection completed and the connection is open. Because of this, we have
renegotiation. You may find it necessary to restructure your disabled mbedTLS's support for connection renegotiation. You may find
application so that connections happen early in boot when heap is it necessary to restructure your application so that connections happen
relatively plentiful, with connection failures inducing reboots. early in boot when heap is relatively plentiful, with connection
failures inducing reboots. LFS may also be of utility in freeing up
For a list of features have a look at the [mbed TLS features page](https://tls.mbed.org/core-features). heap space, should you wish to attempt re-establishing connections
without rebooting.
!!! tip
If possible, you will likely be much better served by using the ECDSA
signature and key exchange algorithms than by using RSA. An
increasingly large fraction of the Internet understands ECDSA, and most
server software can speak it as well. The much smaller key size (at
equivalent security!) is beneficial for NodeMCU's limited RAM.
https://wiki.openssl.org/index.php/Command_Line_Elliptic_Curve_Operations
details how to create ECDSA keys and certificates.
!!! tip
The complete configuration is stored in
[user_mbedtls.h](../../app/include/user_mbedtls.h). This is the file to
edit if you build your own firmware and want to change mbed TLS
behavior.
For a list of possible features have a look at the
[mbed TLS features page](https://tls.mbed.org/core-features).
This module handles certificate verification when SSL/TLS is in use. This module handles certificate verification when SSL/TLS is in use.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment