- Generalize CryptoInterface.

- Add more HMAC and hash functions to CryptoInterface.

- Add MeshCryptoInterface as a holder of mesh specific crypto functionality.

- Rename broadcastMetadataDelimiter to metadataDelimiter in FloodingMesh since it is not just used for broadcasts, and to save some typing.

Author: aerlon

libraries/ESP8266WiFiMesh/examples/HelloMesh/HelloMesh.ino

@@ -55,7 +55,7 @@ bool useLED = false; // Change this to true if you wish the onboard LED to mark
    @return True if this node should forward the received message to other nodes. False otherwise.
 */
 bool meshMessageHandler(String &message, FloodingMesh &meshInstance) {
-  int32_t delimiterIndex = message.indexOf(meshInstance.broadcastMetadataDelimiter());
+  int32_t delimiterIndex = message.indexOf(meshInstance.metadataDelimiter());
   if (delimiterIndex == 0) {
     Serial.print("Message received from STA MAC " + meshInstance.getEspnowMeshBackend().getSenderMac() + ": ");
     Serial.println(message.substring(2, 102));
@@ -172,7 +172,7 @@ void loop() {
       ledState = ledState ^ bool(benchmarkCount); // Make other nodes' LEDs alternate between on and off once benchmarking begins.
 
       // Note: The maximum length of an unencrypted broadcast message is given by floodingMesh.maxUnencryptedMessageSize(). It is around 670 bytes by default.
-      floodingMesh.broadcast(String(floodingMesh.broadcastMetadataDelimiter()) + String(ledState) + theOneMac + " is The One.");
+      floodingMesh.broadcast(String(floodingMesh.metadataDelimiter()) + String(ledState) + theOneMac + " is The One.");
       Serial.println("Proclamation broadcast done in " + String(millis() - startTime) + " ms.");
 
       timeOfLastProclamation = millis();
@@ -181,7 +181,7 @@ void loop() {
 
     if (millis() - loopStart > 23000) { // Start benchmarking the mesh once three proclamations have been made
       uint32_t startTime = millis();
-      floodingMesh.broadcast(String(benchmarkCount++) + String(floodingMesh.broadcastMetadataDelimiter()) + ": Not a spoon in sight.");
+      floodingMesh.broadcast(String(benchmarkCount++) + String(floodingMesh.metadataDelimiter()) + ": Not a spoon in sight.");
       Serial.println("Benchmark broadcast done in " + String(millis() - startTime) + " ms.");
       floodingMeshDelay(20);
     }

libraries/ESP8266WiFiMesh/src/CryptoInterface.cpp

@@ -26,7 +26,7 @@
 #include "UtilityFunctions.h"
 #include "TypeConversionFunctions.h"
 #include "JsonTranslator.h"
-#include "CryptoInterface.h"
+#include "MeshCryptoInterface.h"
 
 using EspnowProtocolInterpreter::espnowHashKeyLength;
 
@@ -128,7 +128,7 @@ uint64_t EncryptedConnectionData::getOwnSessionKey() const { return _ownSessionK
 
 uint64_t EncryptedConnectionData::incrementSessionKey(uint64_t sessionKey, const uint8_t *hashKey, uint8_t hashKeyLength)
 {
-  String hmac = CryptoInterface::createBearsslHmac(uint64ToString(sessionKey), hashKey, hashKeyLength);
+  String hmac = MeshCryptoInterface::createMeshHmac(uint64ToString(sessionKey), hashKey, hashKeyLength);
 
   /* HMAC truncation should be OK since hmac sha256 is a PRF and we are truncating to the leftmost (MSB) bits.
   PRF: https://crypto.stackexchange.com/questions/26410/whats-the-gcm-sha-256-of-a-tls-protocol/26434#26434

libraries/ESP8266WiFiMesh/src/CryptoInterface.h

@@ -28,7 +28,7 @@
 
 std::set<FloodingMesh *> FloodingMesh::availableFloodingMeshes = {};
 
-char FloodingMesh::_broadcastMetadataDelimiter = 23;
+char FloodingMesh::_metadataDelimiter = 23;
 
 void floodingMeshDelay(uint32_t durationMs)
 {
@@ -156,10 +156,10 @@ void FloodingMesh::broadcast(const String &message)
 
   String messageID = generateMessageID();
 
-  // Remove getEspnowMeshBackend().getMeshName() from the broadcastMetadata below to broadcast to all ESP-NOW nodes regardless of MeshName.
+  // Remove getEspnowMeshBackend().getMeshName() from the metadata below to broadcast to all ESP-NOW nodes regardless of MeshName.
   String targetMeshName = getEspnowMeshBackend().getMeshName();
 
-  broadcastKernel(targetMeshName + String(broadcastMetadataDelimiter()) + messageID + String(broadcastMetadataDelimiter()) + message);
+  broadcastKernel(targetMeshName + String(metadataDelimiter()) + messageID + String(metadataDelimiter()) + message);
 }
 
 void FloodingMesh::broadcastKernel(const String &message)
@@ -180,7 +180,7 @@ void FloodingMesh::encryptedBroadcast(const String &message)
 
   String messageID = generateMessageID();
 
-  encryptedBroadcastKernel(messageID + String(broadcastMetadataDelimiter()) + message);  
+  encryptedBroadcastKernel(messageID + String(metadataDelimiter()) + message);  
 }
 
 void FloodingMesh::encryptedBroadcastKernel(const String &message)
@@ -232,15 +232,15 @@ void FloodingMesh::setMessageLogSize(uint16_t messageLogSize)
 }
 uint16_t FloodingMesh::messageLogSize() { return _messageLogSize; }
 
-void FloodingMesh::setBroadcastMetadataDelimiter(char broadcastMetadataDelimiter) 
+void FloodingMesh::setMetadataDelimiter(char metadataDelimiter) 
 { 
   // Using HEX number characters as a delimiter is a bad idea regardless of broadcast type, since they are always in the broadcast metadata
-  assert(broadcastMetadataDelimiter < 48 || 57 < broadcastMetadataDelimiter);
-  assert(broadcastMetadataDelimiter < 65 || 70 < broadcastMetadataDelimiter);
+  assert(metadataDelimiter < 48 || 57 < metadataDelimiter);
+  assert(metadataDelimiter < 65 || 70 < metadataDelimiter);
 
-  _broadcastMetadataDelimiter = broadcastMetadataDelimiter; 
+  _metadataDelimiter = metadataDelimiter; 
 }
-char FloodingMesh::broadcastMetadataDelimiter() { return _broadcastMetadataDelimiter; }
+char FloodingMesh::metadataDelimiter() { return _metadataDelimiter; }
 
 EspnowMeshBackend &FloodingMesh::getEspnowMeshBackend()
 {
@@ -342,12 +342,12 @@ String FloodingMesh::_defaultRequestHandler(const String &request, MeshBackendBa
   String broadcastTarget = "";
   String remainingRequest = "";
 
-  if(request.charAt(0) == broadcastMetadataDelimiter())
+  if(request.charAt(0) == metadataDelimiter())
   {
-    int32_t broadcastTargetEndIndex = request.indexOf(broadcastMetadataDelimiter(), 1);
+    int32_t broadcastTargetEndIndex = request.indexOf(metadataDelimiter(), 1);
 
     if(broadcastTargetEndIndex == -1)
-      return ""; // broadcastMetadataDelimiter not found
+      return ""; // metadataDelimiter not found
 
     broadcastTarget = request.substring(1, broadcastTargetEndIndex + 1); // Include delimiter
     remainingRequest = request.substring(broadcastTargetEndIndex + 1);
@@ -357,10 +357,10 @@ String FloodingMesh::_defaultRequestHandler(const String &request, MeshBackendBa
     remainingRequest = request;
   }
 
-  int32_t messageIDEndIndex = remainingRequest.indexOf(broadcastMetadataDelimiter());
+  int32_t messageIDEndIndex = remainingRequest.indexOf(metadataDelimiter());
 
   if(messageIDEndIndex == -1)
-    return ""; // broadcastMetadataDelimiter not found
+    return ""; // metadataDelimiter not found
 
   uint64_t messageID = stringToUint64(remainingRequest.substring(0, messageIDEndIndex));
 
@@ -447,16 +447,16 @@ void FloodingMesh::_defaultNetworkFilter(int numberOfNetworks, MeshBackendBase &
  */
 bool FloodingMesh::_defaultBroadcastFilter(String &firstTransmission, EspnowMeshBackend &meshInstance)
 {
-  // This broadcastFilter will accept a transmission if it contains the broadcastMetadataDelimiter
+  // This broadcastFilter will accept a transmission if it contains the metadataDelimiter
   // and as metaData either no targetMeshName or a targetMeshName that matches the MeshName of meshInstance
   // and insertPreliminaryMessageID(messageID) returns true.
 
   // Broadcast firstTransmission String structure: targetMeshName+messageID+message.
 
-  int32_t metadataEndIndex = firstTransmission.indexOf(broadcastMetadataDelimiter());
+  int32_t metadataEndIndex = firstTransmission.indexOf(metadataDelimiter());
 
   if(metadataEndIndex == -1)
-    return false; // broadcastMetadataDelimiter not found
+    return false; // metadataDelimiter not found
 
   String targetMeshName = firstTransmission.substring(0, metadataEndIndex);
 
@@ -466,17 +466,17 @@ bool FloodingMesh::_defaultBroadcastFilter(String &firstTransmission, EspnowMesh
   }
   else 
   {
-    int32_t messageIDEndIndex = firstTransmission.indexOf(broadcastMetadataDelimiter(), metadataEndIndex + 1);
+    int32_t messageIDEndIndex = firstTransmission.indexOf(metadataDelimiter(), metadataEndIndex + 1);
 
     if(messageIDEndIndex == -1)
-      return false; // broadcastMetadataDelimiter not found
+      return false; // metadataDelimiter not found
 
     uint64_t messageID = stringToUint64(firstTransmission.substring(metadataEndIndex + 1, messageIDEndIndex));
 
     if(insertPreliminaryMessageID(messageID))
     {
       // Add broadcast identifier to stored message and mark as accepted broadcast.
-      firstTransmission = String(broadcastMetadataDelimiter()) + firstTransmission;
+      firstTransmission = String(metadataDelimiter()) + firstTransmission;
       return true;
     }
     else

libraries/ESP8266WiFiMesh/src/EncryptedConnectionData.cpp

@@ -217,11 +217,11 @@ class FloodingMesh {
    * Set the delimiter character used for metadata by every FloodingMesh instance. 
    * Using characters found in the mesh name or in HEX numbers is unwise, as is using ','.
    * 
-   * @param broadcastMetadataDelimiter The metadata delimiter character to use.
+   * @param metadataDelimiter The metadata delimiter character to use.
    *                                   Defaults to 23 = End-of-Transmission-Block (ETB) control character in ASCII
    */
-  static void setBroadcastMetadataDelimiter(char broadcastMetadataDelimiter);
-  static char broadcastMetadataDelimiter();
+  static void setMetadataDelimiter(char metadataDelimiter);
+  static char metadataDelimiter();
 
   /*
    * Gives you access to the EspnowMeshBackend used by the mesh node.
@@ -274,7 +274,7 @@ class FloodingMesh {
 
   uint8_t _broadcastReceptionRedundancy = 2;
 
-  static char _broadcastMetadataDelimiter; // Defaults to 23 = End-of-Transmission-Block (ETB) control character in ASCII
+  static char _metadataDelimiter; // Defaults to 23 = End-of-Transmission-Block (ETB) control character in ASCII
 
   uint8_t _originMac[6] = {0};
 

libraries/ESP8266WiFiMesh/src/FloodingMesh.cpp

@@ -25,7 +25,7 @@
 #include "JsonTranslator.h"
 #include "EspnowProtocolInterpreter.h"
 #include "TypeConversionFunctions.h"
-#include "CryptoInterface.h"
+#include "MeshCryptoInterface.h"
 
 namespace JsonTranslator
 {
@@ -69,14 +69,14 @@ namespace JsonTranslator
     uint8_t staMac[6] {0};
     uint8_t apMac[6] {0};
     String requesterStaApMac = macToString(WiFi.macAddress(staMac)) + macToString(WiFi.softAPmacAddress(apMac));
-    String hmac = CryptoInterface::createBearsslHmac(requesterStaApMac + mainMessage, hashKey, hashKeyLength);
+    String hmac = MeshCryptoInterface::createMeshHmac(requesterStaApMac + mainMessage, hashKey, hashKeyLength);
     return mainMessage + createJsonEndPair(jsonHmac, hmac);
   }
 
   bool verifyEncryptionRequestHmac(const String &encryptionRequestHmacMessage, const uint8_t *requesterStaMac, const uint8_t *requesterApMac, 
                                    const uint8_t *hashKey, uint8_t hashKeyLength)
   {
-    using namespace CryptoInterface;
+    using MeshCryptoInterface::verifyMeshHmac;
 
     String hmac = "";
     if(getHmac(encryptionRequestHmacMessage, hmac))
@@ -85,8 +85,8 @@ namespace JsonTranslator
       if(hmacStartIndex < 0)
         return false;
 
-      if(hmac.length() == 2*SHA256HMAC_NATURAL_LENGTH // We know that each HMAC byte should become 2 String characters due to uint8ArrayToHexString.
-         && verifyBearsslHmac(macToString(requesterStaMac) + macToString(requesterApMac) + encryptionRequestHmacMessage.substring(0, hmacStartIndex), hmac, hashKey, hashKeyLength))
+      if(hmac.length() == 2*CryptoInterface::SHA256_NATURAL_LENGTH // We know that each HMAC byte should become 2 String characters due to uint8ArrayToHexString.
+         && verifyMeshHmac(macToString(requesterStaMac) + macToString(requesterApMac) + encryptionRequestHmacMessage.substring(0, hmacStartIndex), hmac, hashKey, hashKeyLength))
       {
         return true;
       }

libraries/ESP8266WiFiMesh/src/FloodingMesh.h

@@ -0,0 +1,42 @@
+/*
+ * Copyright (C) 2019 Anders Löfgren
+ *
+ * License (MIT license):
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#include "MeshCryptoInterface.h"
+
+namespace MeshCryptoInterface 
+{
+  String createMeshHmac(const String &message, const void *hashKey, const size_t hashKeyLength, const size_t hmacLength)
+  {
+    return CryptoInterface::sha256Hmac(message, hashKey, hashKeyLength, hmacLength);
+  }
+
+  bool verifyMeshHmac(const String &message, const String &messageHmac, const uint8_t *hashKey, uint8_t hashKeyLength)
+  {
+    String generatedHmac = createMeshHmac(message, hashKey, hashKeyLength, messageHmac.length()/2); // We know that each HMAC byte should become 2 String characters due to uint8ArrayToHexString.
+    if(generatedHmac == messageHmac)
+      return true;
+    else
+      return false;
+  }
+}

libraries/ESP8266WiFiMesh/src/JsonTranslator.cpp

@@ -0,0 +1,72 @@
+/*
+ * Copyright (C) 2019 Anders Löfgren
+ *
+ * License (MIT license):
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#ifndef __MESHCRYPTOINTERFACE_H__
+#define __MESHCRYPTOINTERFACE_H__
+
+#include <Arduino.h>
+#include "CryptoInterface.h"
+
+namespace MeshCryptoInterface 
+{ 
+  /**
+   * There is a constant-time HMAC version available. More constant-time info here: https://www.bearssl.org/constanttime.html
+   * For small messages, it takes substantially longer time to complete than a normal HMAC (5 ms vs 2 ms in a quick benchmark, 
+   * determined by the difference between min and max allowed message length), and it also sets a maximum length that messages can be (1024 bytes by default).
+   * Making the fixed max length variable would defeat the whole purpose of using constant-time, and not making it variable would create the wrong HMAC if message size exceeds the maximum.
+   * 
+   * Also, HMAC is already partially constant-time. Quoting the link above: 
+   * "Hash functions implemented by BearSSL (MD5, SHA-1, SHA-224, SHA-256, SHA-384 and SHA-512) consist in bitwise logical operations and additions on 32-bit or 64-bit words, 
+   * naturally yielding constant-time operations. HMAC is naturally as constant-time as the underlying hash function. The size of the MACed data, and the size of the key, 
+   * may leak, though; only the contents are protected."
+   * 
+   * Thus the non constant-time version is used within the mesh framework instead.
+   */
+  
+  /**
+   * Create a SHA256 HMAC from the message, using the provided hashKey. The result will be hmacLength bytes long and returned as a String in HEX format.
+   * 
+   * @param message The string from which to create the HMAC.
+   * @param hashKey The hash key to use when creating the HMAC.
+   * @param hashKeyLength The length of the hash key in bytes.
+   * @param hmacLength The desired length of the generated HMAC, in bytes. Valid values are 1 to 32. Defaults to CryptoInterface::SHA256_NATURAL_LENGTH.
+   * 
+   * @return A String with the generated HMAC in HEX format.
+   */
+  String createMeshHmac(const String &message, const void *hashKey, const size_t hashKeyLength, const size_t hmacLength = CryptoInterface::SHA256_NATURAL_LENGTH);
+  
+  /**
+   * Verify a SHA256 HMAC which was created from the message using the provided hashKey.
+   * 
+   * @param message The string from which the HMAC was created.
+   * @param messageHmac A string with the generated HMAC in HEX format. Valid messageHmac.length() is 2 to 64.
+   * @param hashKey The hash key to use when creating the HMAC.
+   * @param hashKeyLength The length of the hash key in bytes.
+   * 
+   * @return True if the HMAC is correct. False otherwise.
+   */
+  bool verifyMeshHmac(const String &message, const String &messageHmac, const uint8_t *hashKey, uint8_t hashKeyLength);
+}
+
+#endif