Added another overloaded WiFiSTAClass::begin() function that provides… (espressif#6398)

Summary

The examples demonstrate how to create a WPA2 Enterprise connection, but it requires using various direct esp_idf functions. This patch is intended to create another overloaded version of the WiFi.begin() function that allows a user to create a WPA2 Enterprise connection in much the same way as different kinds of connections.

My only question for the core maintainers is whether I should leave those #ifdef's in there. I added them so that it was easy to disable all the code I added via defines from my platformio.ini file, but they technically aren't necessary.

Impact

This should make it easier for novice users to create WPA2 Enterprise connections. For my university, I didn't need a root certificate or the client certificate or client key, so I haven't been able to debug those scenarios, but I built the begin functions to allow any one of those to be used, if needed.

I can confirm that eduroam-style WPA2 Enterprise networks that only require authentication with a username and password works as expected.

Author: jpswensen

libraries/WiFi/examples/WiFiClientEnterprise/WiFiClientEnterprise.ino

@@ -1,10 +1,22 @@
 #include <WiFi.h> //Wifi library
 #include "esp_wpa2.h" //wpa2 library for connections to Enterprise networks
 #define EAP_IDENTITY "login" //if connecting from another corporation, use identity@organisation.domain in Eduroam 
+#define EAP_USERNAME "login" //oftentimes just a repeat of the identity
 #define EAP_PASSWORD "password" //your Eduroam password
 const char* ssid = "eduroam"; // Eduroam SSID
 const char* host = "arduino.php5.sk"; //external server domain for HTTP connection after authentification
 int counter = 0;
+
+// NOTE: For some systems, various certification keys are required to connect to the wifi system.
+//       Usually you are provided these by the IT department of your organization when certs are required
+//       and you can't connect with just an identity and password.
+//       Most eduroam setups we have seen do not require this level of authentication, but you should contact
+//       your IT department to verify.
+//       You should uncomment these and populate with the contents of the files if this is required for your scenario (See Example 2 and Example 3 below).
+//const char *ca_pem = "insert your CA cert from your .pem file here";
+//const char *client_cert = "insert your client cert from your .crt file here";
+//const char *client_key = "insert your client key from your .key file here";
+
 void setup() {
   Serial.begin(115200);
   delay(10);
@@ -13,11 +25,17 @@ void setup() {
   Serial.println(ssid);
   WiFi.disconnect(true);  //disconnect form wifi to set new wifi connection
   WiFi.mode(WIFI_STA); //init wifi mode
-  esp_wifi_sta_wpa2_ent_set_identity((uint8_t *)EAP_IDENTITY, strlen(EAP_IDENTITY)); //provide identity
-  esp_wifi_sta_wpa2_ent_set_username((uint8_t *)EAP_IDENTITY, strlen(EAP_IDENTITY)); //provide username --> identity and username is same
-  esp_wifi_sta_wpa2_ent_set_password((uint8_t *)EAP_PASSWORD, strlen(EAP_PASSWORD)); //provide password
-  esp_wifi_sta_wpa2_ent_enable();
-  WiFi.begin(ssid); //connect to wifi
+  
+  // Example1 (most common): a cert-file-free eduroam with PEAP (or TTLS)
+  WiFi.begin(ssid, WPA2_AUTH_PEAP, EAP_IDENTITY, EAP_USERNAME, EAP_PASSWORD);
+
+  // Example 2: a cert-file WPA2 Enterprise with PEAP
+  //WiFi.begin(ssid, WPA2_AUTH_PEAP, EAP_IDENTITY, EAP_USERNAME, EAP_PASSWORD, ca_pem, client_cert, client_key);
+  
+  // Example 3: TLS with cert-files and no password
+  //WiFi.begin(ssid, WPA2_AUTH_TLS, EAP_IDENTITY, NULL, NULL, ca_pem, client_cert, client_key);
+  
+  
   while (WiFi.status() != WL_CONNECTED) {
     delay(500);
     Serial.print(".");

libraries/WiFi/src/WiFiSTA.cpp

@@ -42,6 +42,7 @@ extern "C" {
 #include "lwip/dns.h"
 #include <esp_smartconfig.h>
 #include <esp_netif.h>
+#include "esp_wpa2.h"
 }
 
 // -----------------------------------------------------------------------------------------------------------------------
@@ -145,6 +146,67 @@ wl_status_t WiFiSTAClass::status()
     return (wl_status_t)xEventGroupClearBits(_sta_status_group, 0);
 }
 
+/**
+ * Start Wifi connection with a WPA2 Enterprise AP
+ * if passphrase is set the most secure supported mode will be automatically selected
+ * @param ssid const char*          Pointer to the SSID string.
+ * @param method wpa2_method_t      The authentication method of WPA2 (WPA2_AUTH_TLS, WPA2_AUTH_PEAP, WPA2_AUTH_TTLS)
+ * @param wpa2_identity  const char*          Pointer to the entity
+ * @param wpa2_username  const char*          Pointer to the username
+ * @param password const char *     Pointer to the password.
+ * @param ca_pem const char*        Pointer to a string with the contents of a  .pem  file with CA cert
+ * @param client_crt const char*        Pointer to a string with the contents of a .crt file with client cert
+ * @param client_key const char*        Pointer to a string with the contants of a .key file with client key
+ * @param bssid uint8_t[6]          Optional. BSSID / MAC of AP
+ * @param channel                   Optional. Channel of AP
+ * @param connect                   Optional. call connect
+ * @return
+ */
+wl_status_t WiFiSTAClass::begin(const char* wpa2_ssid, wpa2_auth_method_t method, const char* wpa2_identity, const char* wpa2_username, const char *wpa2_password, const char* ca_pem, const char* client_crt, const char* client_key, int32_t channel, const uint8_t* bssid, bool connect)
+{
+    if(!WiFi.enableSTA(true)) {
+        log_e("STA enable failed!");
+        return WL_CONNECT_FAILED;
+    }
+
+    if(!wpa2_ssid || *wpa2_ssid == 0x00 || strlen(wpa2_ssid) > 32) {
+        log_e("SSID too long or missing!");
+        return WL_CONNECT_FAILED;
+    }
+
+    if(wpa2_identity && strlen(wpa2_identity) > 64) {
+        log_e("identity too long!");
+        return WL_CONNECT_FAILED;
+    }
+
+    if(wpa2_username && strlen(wpa2_username) > 64) {
+        log_e("username too long!");
+        return WL_CONNECT_FAILED;
+    }
+
+    if(wpa2_password && strlen(wpa2_password) > 64) {
+        log_e("password too long!");
+    }
+
+    if(ca_pem) {
+        esp_wifi_sta_wpa2_ent_set_ca_cert((uint8_t *)ca_pem, strlen(ca_pem));
+    }
+
+    if(client_crt) {
+        esp_wifi_sta_wpa2_ent_set_cert_key((uint8_t *)client_crt, strlen(client_crt), (uint8_t *)client_key, strlen(client_key), NULL, 0);
+    }
+
+    esp_wifi_sta_wpa2_ent_set_identity((uint8_t *)wpa2_identity, strlen(wpa2_identity));
+    if(method == WPA2_AUTH_PEAP || method == WPA2_AUTH_TTLS) {
+        esp_wifi_sta_wpa2_ent_set_username((uint8_t *)wpa2_username, strlen(wpa2_username));
+        esp_wifi_sta_wpa2_ent_set_password((uint8_t *)wpa2_password, strlen(wpa2_password));
+    }
+    esp_wifi_sta_wpa2_ent_enable(); //set config settings to enable function
+    WiFi.begin(wpa2_ssid); //connect to wifi
+
+    return status();
+}
+
 /**
  * Start Wifi connection
  * if passphrase is set the most secure supported mode will be automatically selected

libraries/WiFi/src/WiFiSTA.h

@@ -30,6 +30,11 @@
 #include "esp_event.h"
 #endif
 
+typedef enum {
+    WPA2_AUTH_TLS = 0,
+    WPA2_AUTH_PEAP = 1,
+    WPA2_AUTH_TTLS = 2
+} wpa2_auth_method_t;
 
 class WiFiSTAClass
 {
@@ -39,6 +44,7 @@ class WiFiSTAClass
 
 public:
 
+    wl_status_t begin(const char* wpa2_ssid, wpa2_auth_method_t method, const char* wpa2_identity=NULL, const char* wpa2_username=NULL, const char *wpa2_password=NULL, const char* ca_pem=NULL, const char* client_crt=NULL, const char* client_key=NULL, int32_t channel=0, const uint8_t* bssid=0, bool connect=true);
     wl_status_t begin(const char* ssid, const char *passphrase = NULL, int32_t channel = 0, const uint8_t* bssid = NULL, bool connect = true);
     wl_status_t begin(char* ssid, char *passphrase = NULL, int32_t channel = 0, const uint8_t* bssid = NULL, bool connect = true);
     wl_status_t begin();