Merge branch 'master' into signedupdates

Author: earlephilhower

doc/esp8266wifi/bearssl-client-secure-class.rst

@@ -0,0 +1,44 @@
+:orphan:
+
+BearSSL Secure Server Class
+---------------------------
+
+Implements a TLS encrypted server with optional client certificate validation.  See `Server Class <server-class.rst>`__ for general information and `BearSSL Secure Client Class <bearssl-secure-client-class.rst>`__ for basic server and BearSSL concepts.
+
+setBufferSizes(int recv, int xmit)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Similar to the `BearSSL::WiFiClientSecure` method, sets the receive and transmit buffer sizes.  Note that servers cannot request a buffer size from the client, so if these are shrunk and the client tries to send a chunk larger than the receive buffer, it will always fail.  This must be called before the server is 
+
+Setting Server Certificates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+TLS servers require a certificate identifying itself and containing its public key, and a private key they will use to encrypt information with.  The application author is responsible for generating this certificate and key, either using a self-signed generator or using a commercial certification authority.  **Do not re-use the certificates included in the examples provided.**
+
+This example command will generate a RSA 2048-bit key and certificate:
+
+.. code::
+
+    openssl req -x509 -nodes -newkey rsa:2048 -keyout key.pem -out cert.pem -days 4096
+
+Again, it is up to the application author to generate this certificate and key and keep the private key safe and **private.**
+
+setRSACert(const BearSSL::X509List *chain, const BearSSL::PrivateKey *sk)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Sets a RSA certificate and key to be used by the server when connections are received.  Needs to be called before `begin()`
+
+setECCert(const BearSSL::X509List *chain, unsigned cert_issuer_key_type, const BearSSL::PrivateKey *sk)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Sets an elliptic curve certificate and key for the server.  Needs to be called before `begin()`.
+
+Requiring Client Certificates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+TLS servers can request the client to identify itself by transmitting a certificate during handshake.  If the client cannot transmit the certificate, the connection will be dropped by the server.
+
+setClientTrustAnchor(const BearSSL::X509List *client_CA_ta)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Sets the trust anchor (normally a self-signing CA) that all received certificates will be verified against.  Needs to be called before `begin()`.

doc/esp8266wifi/bearssl-server-secure-class.rst

@@ -117,7 +117,7 @@ In the next steps we should execute GET command. This is done is similar way as
 
 After sending the request we should wait for a reply and then process received information.
 
-Out of received replay we can skip response header. This can be done by reading until an empty line ``"\r"`` that marks the end of the header:
+Out of received reply we can skip response header. This can be done by reading until an empty line ``"\r"`` that marks the end of the header:
 
 .. code:: cpp
 

doc/esp8266wifi/client-secure-examples.rst

@@ -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
 ~~~~~~
 

doc/esp8266wifi/readme.rst

@@ -50,8 +50,8 @@ The first parameter of this function is required, remaining four are optional.
 
 Meaning of all parameters is as follows:
 
-- ``ssid`` - character string containing network SSID (max. 63 characters) 
-- ``password`` - optional character string with a password. For WPA2-PSK network it should be at least 8 character long. If not specified, the access point will be open for anybody to connect. 
+- ``ssid`` - character string containing network SSID (max. 31 characters) 
+- ``password`` - optional character string with a password. For WPA2-PSK network it should be at least 8 character long. If not specified, the access point will be open for anybody to connect, (max. 63 characters). 
 - ``channel`` - optional parameter to set Wi-Fi channel, from 1 to 13. Default channel = 1. 
 - ``hidden`` - optional parameter, if set to ``true`` will hide SSID. 
 - ``max_connection`` - optional parameter to set max simultaneous connected stations, `from 0 to 8 <https://bbs.espressif.com/viewtopic.php?f=46&t=481&p=1832&hilit=max_connection#p1832>`__. Defaults to 4. Once the max number has been reached, any other station that wants to connect will be forced to wait until an already connected station disconnects.

doc/esp8266wifi/soft-access-point-class.rst

@@ -164,6 +164,7 @@ Libraries that don't rely on low-level access to AVR registers should work well.
 -  `DimSwitch <https://github.com/krzychb/DimSwitch>`__ - Control electronic dimmable ballasts for fluorescent light tubes remotely as if using a wall switch.
 -  `Encoder <https://github.com/PaulStoffregen/Encoder>`__ - Arduino library for rotary encoders. Version 1.4 supports ESP8266.
 -  `esp8266\_mdns <https://github.com/mrdunk/esp8266_mdns>`__ - mDNS queries and responses on esp8266. Or to describe it another way: An mDNS Client or Bonjour Client library for the esp8266.
+-  `ESP-NOW <https://github.com/yoursunny/WifiEspNow>`__ - Wrapper lib for ESP-NOW (See `#2227 <https://github.com/esp8266/Arduino/issues/2227>`__)
 -  `ESPAsyncTCP <https://github.com/me-no-dev/ESPAsyncTCP>`__ - Asynchronous TCP Library for ESP8266 and ESP32/31B
 -  `ESPAsyncWebServer <https://github.com/me-no-dev/ESPAsyncWebServer>`__ - Asynchronous Web Server Library for ESP8266 and ESP32/31B
 -  `Homie for ESP8266 <https://github.com/marvinroger/homie-esp8266>`__ - Arduino framework for ESP8266 implementing Homie, an MQTT convention for the IoT.

doc/libraries.rst

@@ -2,6 +2,11 @@
 #include <lwip/def.h>
 #include <Arduino.h>
 
+#ifdef DEBUG_ESP_PORT
+#define DEBUG_OUTPUT DEBUG_ESP_PORT
+#else
+#define DEBUG_OUTPUT Serial
+#endif
 
 DNSServer::DNSServer()
 {
@@ -165,7 +170,7 @@ void DNSServer::replyWithIP(uint8_t* buffer, size_t packetSize)
   _udp.endPacket();
 
   #ifdef DEBUG_ESP_DNS
-    DEBUG_ESP_PORT.printf("DNS responds: %s for %s\n",
+    DEBUG_OUTPUT.printf("DNS responds: %s for %s\n",
             IPAddress(_resolvedIP).toString().c_str(), getDomainNameWithoutWwwPrefix(buffer, packetSize).c_str() );
   #endif
 }

libraries/DNSServer/src/DNSServer.cpp

@@ -1036,7 +1036,7 @@ bool HTTPClient::connect(void)
     }
 
 #ifdef HTTPCLIENT_1_1_COMPATIBLE
-    if(!_client) {
+    if(!_client && _transportTraits) {
         _tcpDeprecated = _transportTraits->create();
         _client = _tcpDeprecated.get();
     }

libraries/ESP8266HTTPClient/src/ESP8266HTTPClient.cpp

@@ -101,7 +101,7 @@ void setup()
 
   MDNS.begin(host);
 
-  httpServer.setRSACert(new BearSSLX509List(serverCert), new BearSSLPrivateKey(serverKey));
+  httpServer.setRSACert(new BearSSL::X509List(serverCert), new BearSSL::PrivateKey(serverKey));
   httpUpdater.setup(&httpServer, update_path, update_username, update_password);
   httpServer.begin();
 

libraries/ESP8266HTTPUpdateServer/examples/SecureBearSSLUpdater/SecureBearSSLUpdater.ino

@@ -123,7 +123,7 @@ void setup(void){
     Serial.println("MDNS responder started");
   }
 
-  server.setRSACert(new BearSSLX509List(serverCert), new BearSSLPrivateKey(serverKey));
+  server.setRSACert(new BearSSL::X509List(serverCert), new BearSSL::PrivateKey(serverKey));
 
   server.on("/", handleRoot);
 

libraries/ESP8266WebServer/examples/HelloServerBearSSL/HelloServerBearSSL.ino

@@ -46,12 +46,12 @@ ESP8266WebServerSecure::ESP8266WebServerSecure(int port)
 {
 }
 
-void ESP8266WebServerSecure::setRSACert(const BearSSLX509List *chain, const BearSSLPrivateKey *sk)
+void ESP8266WebServerSecure::setRSACert(const X509List *chain, const PrivateKey *sk)
 {
   _serverSecure.setRSACert(chain, sk);
 }
 
-void ESP8266WebServerSecure::setECCert(const BearSSLX509List *chain, unsigned cert_issuer_key_type, const BearSSLPrivateKey *sk)
+void ESP8266WebServerSecure::setECCert(const X509List *chain, unsigned cert_issuer_key_type, const PrivateKey *sk)
 {
   _serverSecure.setECCert(chain, cert_issuer_key_type, sk);
 }
@@ -83,7 +83,7 @@ void ESP8266WebServerSecure::begin() {
 
 void ESP8266WebServerSecure::handleClient() {
   if (_currentStatus == HC_NONE) {
-    BearSSL::WiFiClientSecure client = _serverSecure.available();
+    WiFiClientSecure client = _serverSecure.available();
     if (!client) {
       return;
     }
@@ -136,7 +136,7 @@ void ESP8266WebServerSecure::handleClient() {
   }
 
   if (!keepCurrentClient) {
-    _currentClientSecure = BearSSL::WiFiClientSecure();
+    _currentClientSecure = WiFiClientSecure();
     _currentStatus = HC_NONE;
     _currentUpload.reset();
   }

libraries/ESP8266WebServer/src/ESP8266WebServerSecureBearSSL.cpp

@@ -37,8 +37,8 @@ class ESP8266WebServerSecure : public ESP8266WebServer
   virtual ~ESP8266WebServerSecure();
 
   void setBufferSizes(int recv, int xmit);
-  void setRSACert(const BearSSLX509List *chain, const BearSSLPrivateKey *sk);
-  void setECCert(const BearSSLX509List *chain, unsigned cert_issuer_key_type, const BearSSLPrivateKey *sk);
+  void setRSACert(const X509List *chain, const PrivateKey *sk);
+  void setECCert(const X509List *chain, unsigned cert_issuer_key_type, const PrivateKey *sk);
 
   WiFiClient client() override { return _currentClientSecure; }
 
@@ -61,8 +61,8 @@ class ESP8266WebServerSecure : public ESP8266WebServer
   size_t _currentClientWrite_P (PGM_P bytes, size_t len) override { return _currentClientSecure.write_P(bytes, len); }
 
 protected:
-  BearSSL::WiFiServerSecure _serverSecure;
-  BearSSL::WiFiClientSecure _currentClientSecure;
+  WiFiServerSecure _serverSecure;
+  WiFiClientSecure _currentClientSecure;
 };
 
 };

libraries/ESP8266WebServer/src/ESP8266WebServerSecureBearSSL.h

@@ -121,8 +121,8 @@ void setup() {
   Serial.println(WiFi.localIP());
 
   // Attach the server private cert/key combo
-  BearSSLX509List *serverCertList = new BearSSLX509List(server_cert);
-  BearSSLPrivateKey *serverPrivKey = new BearSSLPrivateKey(server_private_key);
+  BearSSL::X509List *serverCertList = new BearSSL::X509List(server_cert);
+  BearSSL::PrivateKey *serverPrivKey = new BearSSL::PrivateKey(server_private_key);
   server.setRSACert(serverCertList, serverPrivKey);
 
   // Actually start accepting connections

libraries/ESP8266WiFi/examples/BearSSL_Server/BearSSL_Server.ino

@@ -197,12 +197,12 @@ void setup() {
   setClock(); // Required for X.509 validation
 
   // Attach the server private cert/key combo
-  BearSSLX509List *serverCertList = new BearSSLX509List(server_cert);
-  BearSSLPrivateKey *serverPrivKey = new BearSSLPrivateKey(server_private_key);
+  BearSSL::X509List *serverCertList = new BearSSL::X509List(server_cert);
+  BearSSL::PrivateKey *serverPrivKey = new BearSSL::PrivateKey(server_private_key);
   server.setRSACert(serverCertList, serverPrivKey);
 
   // Require a certificate validated by the trusted CA
-  BearSSLX509List *serverTrustedCA = new BearSSLX509List(ca_cert);
+  BearSSL::X509List *serverTrustedCA = new BearSSL::X509List(ca_cert);
   server.setClientTrustAnchor(serverTrustedCA);
 
   // Actually start accepting connections

libraries/ESP8266WiFi/examples/BearSSL_ServerClientCert/BearSSL_ServerClientCert.ino

@@ -119,7 +119,7 @@ vEsXCS+0yx5DaMkHJ8HSXPfqIbloEpw8nL+e/IBcm2PN7EeqJSdnoDfzAIJ9VNep
 )EOF";
   uint32_t start, finish;
   BearSSL::WiFiClientSecure client;
-  BearSSLX509List cert(digicert);
+  BearSSL::X509List cert(digicert);
 
   Serial.printf("Connecting without sessions...");
   start = millis();
@@ -128,7 +128,7 @@ vEsXCS+0yx5DaMkHJ8HSXPfqIbloEpw8nL+e/IBcm2PN7EeqJSdnoDfzAIJ9VNep
   finish = millis();
   Serial.printf("Total time: %dms\n", finish - start);
 
-  BearSSLSession session;
+  BearSSL::Session session;
   client.setSession(&session);
   Serial.printf("Connecting with an unitialized session...");
   start = millis();

libraries/ESP8266WiFi/examples/BearSSL_Sessions/BearSSL_Sessions.ino

@@ -144,7 +144,7 @@ wQIDAQAB
 -----END PUBLIC KEY-----
 )KEY";
   BearSSL::WiFiClientSecure client;
-  BearSSLPublicKey key(pubkey);
+  BearSSL::PublicKey key(pubkey);
   client.setKnownKey(&key);
   fetchURL(&client, host, port, path);
 }
@@ -186,7 +186,7 @@ BearSSL does verify the notValidBefore/After fields.
 )EOF");
 
   BearSSL::WiFiClientSecure client;
-  BearSSLX509List cert(digicert);
+  BearSSL::X509List cert(digicert);
   client.setTrustAnchors(&cert);
   Serial.printf("Try validating without setting the time (should fail)\n");
   fetchURL(&client, host, port, path);

libraries/ESP8266WiFi/examples/BearSSL_Validation/BearSSL_Validation.ino

@@ -19,11 +19,14 @@ WiFiServerSecure	KEYWORD1
 WiFiUDP	KEYWORD1
 WiFiClientSecure	KEYWORD1
 ESP8266WiFiMulti	KEYWORD1
-BearSSLX509List	KEYWORD1
-BearSSLPrivateKey	KEYWORD1
-BearSSLPublicKey	KEYWORD1
+BearSSL	KEYWORD1
+X509List	KEYWORD1
+PrivateKey	KEYWORD1
+PublicKey	KEYWORD1
 CertStoreSPIFFSBearSSL	KEYWORD1
 CertStoreSDBearSSL	KEYWORD1
+Session	KEYWORD1
+
 
 #######################################
 # Methods and Functions (KEYWORD2)