WiFiServerSecure: Cache SSL sessions (#7774)

* WiFiServerSecure: Cache the SSL sessions

* Add SSL session caching to HTTPS server examples

* Document server SSL session caching

* Fix an incomplete sentence in the documentation

* Document BearSSL::Session

* Use the number of sessions instead of the buffer size in ServerSessions' constructors

libraries/ESP8266WiFi/src/BearSSLHelpers.h

@@ -133,6 +133,9 @@ class X509List {
 // significantly faster.  Completely optional.
 class WiFiClientSecure;
 
+// Cache for a TLS session with a server
+// Use with BearSSL::WiFiClientSecure::setSession
+// to accelerate the TLS handshake
 class Session {
   friend class WiFiClientSecureCtx;
 
@@ -140,10 +143,51 @@ class Session {
     Session() { memset(&_session, 0, sizeof(_session)); }
   private:
     br_ssl_session_parameters *getSession() { return &_session; }
-    // The actual BearSSL ession information
+    // The actual BearSSL session information
     br_ssl_session_parameters _session;
 };
 
+// Represents a single server session.
+// Use with BearSSL::ServerSessions.
+typedef uint8_t ServerSession[100];
+
+// Cache for the TLS sessions of multiple clients.
+// Use with BearSSL::WiFiServerSecure::setCache
+class ServerSessions {
+  friend class WiFiClientSecureCtx;
+
+  public:
+    // Uses the given buffer to cache the given number of sessions and initializes it.
+    ServerSessions(ServerSession *sessions, uint32_t size) : ServerSessions(sessions, size, false) {}
+
+    // Dynamically allocates a cache for the given number of sessions and initializes it.
+    // If the allocation of the buffer wasn't successfull, the value
+    // returned by size() will be 0.
+    ServerSessions(uint32_t size) : ServerSessions(size > 0 ? new ServerSession[size] : nullptr, size, true) {}
+
+    ~ServerSessions();
+
+    // Returns the number of sessions the cache can hold.
+    uint32_t size() { return _size; }
+
+  private:
+    ServerSessions(ServerSession *sessions, uint32_t size, bool isDynamic);
+
+    // Returns the cache's vtable or null if the cache has no capacity.
+    const br_ssl_session_cache_class **getCache();
+
+    // Size of the store in sessions.
+    uint32_t _size;
+    // Store where the informations for the sessions are stored.
+    ServerSession *_store;
+    // Whether the store is dynamically allocated.
+    // If this is true, the store needs to be freed in the destructor.
+    bool _isDynamic;
+
+    // Cache of the server using the _store.
+    br_ssl_session_cache_lru _cache;
+};
+
 // Updater SHA256 hash and signature verification
 class HashSHA256 : public UpdaterHashClass {
   public:
@@ -170,7 +214,7 @@ class SigningVerifier : public UpdaterVerifyClass {
   private:
     PublicKey *_pubKey;
 };
-  
+
 // Stack thunked versions of calls
 extern "C" {
 extern unsigned char *thunk_br_ssl_engine_recvapp_buf( const br_ssl_engine_context *cc, size_t *len);