From 0268354426b29af53dd891cb99217b42e3f1b43e Mon Sep 17 00:00:00 2001
From: Jonathan Bennett <jbennett@incomsystems.biz>
Date: Tue, 27 May 2025 15:33:19 -0500
Subject: [PATCH] Key validation messages (#690)

* Add the transport messages for a key validation protocol
---
 meshtastic/admin.proto    | 57 ++++++++++++++++++++++++++++++++++++++-
 meshtastic/mesh.options   |  9 +++++++
 meshtastic/mesh.proto     | 44 ++++++++++++++++++++++++++++++
 meshtastic/portnums.proto |  5 ++++
 4 files changed, 114 insertions(+), 1 deletion(-)

diff --git a/meshtastic/admin.proto b/meshtastic/admin.proto
index b6fc552..91fbb2b 100644
--- a/meshtastic/admin.proto
+++ b/meshtastic/admin.proto
@@ -402,6 +402,11 @@ message AdminMessage {
      */
     SharedContact add_contact = 66;
 
+    /*
+     * Initiate or respond to a key verification request
+     */
+    KeyVerificationAdmin key_verification = 67;
+
     /*
      * Tell the node to factory reset config everything; all device state and configuration will be returned to factory defaults and BLE bonds will be cleared.
      */
@@ -488,4 +493,54 @@ message SharedContact {
    * The User of the contact
    */
   User user = 2;
-}
\ No newline at end of file
+}
+
+  /*
+   * This message is used by a client to initiate or complete a key verification
+   */
+message KeyVerificationAdmin {
+  /*
+   * Three stages of this request.
+   */
+  enum MessageType {
+
+    /*
+    * This is the first stage, where a client initiates
+    */
+    INITIATE_VERIFICATION = 0;
+
+    /*
+     * After the nonce has been returned over the mesh, the client prompts for the security number
+     * And uses this message to provide it to the node.
+     */
+    PROVIDE_SECURITY_NUMBER = 1;
+ 
+   /*
+    * Once the user has compared the verification message, this message notifies the node.
+    */
+    DO_VERIFY = 2;
+
+   /*
+    * This is the cancel path, can be taken at any point
+    */
+    DO_NOT_VERIFY = 3;
+
+  }
+
+  MessageType message_type = 1;
+
+   /*
+    * The nodenum we're requesting
+    */
+  uint32 remote_nodenum = 2;
+
+   /*
+    * The nonce is used to track the connection
+    */
+  uint64 nonce = 3;
+
+   /*
+    * The 4 digit code generated by the remote node, and communicated outside the mesh
+    */
+  optional uint32 security_number = 4;
+}
diff --git a/meshtastic/mesh.options b/meshtastic/mesh.options
index e2c905d..49dd597 100644
--- a/meshtastic/mesh.options
+++ b/meshtastic/mesh.options
@@ -58,6 +58,15 @@
 
 *ClientNotification.message max_size:400
 
+*KeyVerificationNumberInform.remote_longname max_size:40
+*KeyVerificationNumberRequest.remote_longname max_size:40
+*KeyVerificationFinal.remote_longname max_size:40
+*KeyVerificationFinal.verification_characters max_size:10
+
+*KeyVerification.hash1 max_size:32
+*KeyVerification.hash2 max_size:32
+
+
 # MyMessage.name         max_size:40 
 # or fixed_length or fixed_count, or max_count
 
diff --git a/meshtastic/mesh.proto b/meshtastic/mesh.proto
index 6d7798f..dffdf98 100644
--- a/meshtastic/mesh.proto
+++ b/meshtastic/mesh.proto
@@ -1011,6 +1011,28 @@ message Data {
   optional uint32 bitfield = 9;
 }
 
+/*
+ * The actual over-the-mesh message doing KeyVerification
+ */
+message KeyVerification {
+
+  /*
+   * random value Selected by the requesting node
+   */
+  uint64 nonce = 1;
+
+  /*
+   * The final authoritative hash, only to be sent by NodeA at the end of the handshake
+   */
+  bytes hash1 = 2;
+
+  /*
+   * The intermediary hash (actually derived from hash1),
+   * sent from NodeB to NodeA in response to the initial message.
+   */
+  bytes hash2 = 3;
+}
+
 /*
  * Waypoint message, used to share arbitrary locations across the mesh
  */
@@ -1800,6 +1822,28 @@ message ClientNotification {
    * The message body of the notification
    */
   string message = 4;
+
+  oneof payload_variant {
+    KeyVerificationNumberInform key_verification_number_inform = 11;
+    KeyVerificationNumberRequest key_verification_number_request = 12;
+    KeyVerificationFinal key_verification_final = 13;
+  }
+}
+
+message KeyVerificationNumberInform {
+  uint64 nonce = 1;
+  string remote_longname = 2;
+  uint32 security_number = 3;
+}
+message KeyVerificationNumberRequest {
+  uint64 nonce = 1;
+  string remote_longname = 2;
+}
+message KeyVerificationFinal {
+  uint64 nonce = 1;
+  string remote_longname = 2;
+  bool isSender = 3;
+  string verification_characters = 4;
 }
 
 /*
diff --git a/meshtastic/portnums.proto b/meshtastic/portnums.proto
index 76df5db..0203392 100644
--- a/meshtastic/portnums.proto
+++ b/meshtastic/portnums.proto
@@ -110,6 +110,11 @@ enum PortNum {
    */
   ALERT_APP = 11;
 
+  /*
+   * Module/port for handling key verification requests.
+   */
+  KEY_VERIFICATION_APP = 12;
+
   /*
    * Provides a 'ping' service that replies to any packet it receives.
    * Also serves as a small example module.