From 55731922e84c46c610bb8417fcfc3a9daffe7ff4 Mon Sep 17 00:00:00 2001
From: Denis Kasak <dkasak@termina.org.uk>
Date: Mon, 4 Oct 2021 12:49:16 +0200
Subject: [PATCH] Add decision tree model of the key sharing algorithm.

And a tool to render it.

Signed-off-by: Denis Kasak <dkasak@termina.org.uk>
---
 contrib/key-sharing-algorithm/Makefile        | 15 +++++++
 contrib/key-sharing-algorithm/README.md       | 11 +++++
 contrib/key-sharing-algorithm/model.dot       | 45 +++++++++++++++++++
 .../key-sharing-algorithm/setdotlabelwidth    | 37 +++++++++++++++
 4 files changed, 108 insertions(+)
 create mode 100644 contrib/key-sharing-algorithm/Makefile
 create mode 100644 contrib/key-sharing-algorithm/README.md
 create mode 100644 contrib/key-sharing-algorithm/model.dot
 create mode 100755 contrib/key-sharing-algorithm/setdotlabelwidth

diff --git a/contrib/key-sharing-algorithm/Makefile b/contrib/key-sharing-algorithm/Makefile
new file mode 100644
index 000000000..d09ba88b3
--- /dev/null
+++ b/contrib/key-sharing-algorithm/Makefile
@@ -0,0 +1,15 @@
+.PHONY: default clean png pdf
+
+default: model.png model.pdf
+
+clean:
+	rm -f model.png model.pdf
+
+pdf: model.pdf
+png: model.png
+
+model.pdf: model.dot
+	./setdotlabelwidth 45 <model.dot | dot -Tpdf -o model.pdf
+
+model.png: model.dot
+	./setdotlabelwidth 45 <model.dot | dot -Tpng -o model.png
diff --git a/contrib/key-sharing-algorithm/README.md b/contrib/key-sharing-algorithm/README.md
new file mode 100644
index 000000000..bbf7591e9
--- /dev/null
+++ b/contrib/key-sharing-algorithm/README.md
@@ -0,0 +1,11 @@
+This models the room key sharing algorithm as a decision tree and provides
+tooling to render it as a PDF or PNG.
+
+# Usage
+
+    make  # Render the decision tree both as a PDF and PNG
+
+    make pdf  # Renders the decision tree as a PDF
+    make png  # Renders the decision tree as a PNG
+
+    make clean  # Remove rendered artifacts
diff --git a/contrib/key-sharing-algorithm/model.dot b/contrib/key-sharing-algorithm/model.dot
new file mode 100644
index 000000000..9fe5b1e36
--- /dev/null
+++ b/contrib/key-sharing-algorithm/model.dot
@@ -0,0 +1,45 @@
+digraph {
+    label="Matrix room key sharing algorithm"
+    fontname="Fira Sans"
+    ratio=0.5
+
+    node [shape=box, colorscheme=paired6, style=filled, fillcolor=white, fontname="Fira Sans"]
+    edge [fontname="Fira Sans"]
+
+    /* Non-end states, additional checks needed. */
+    verified_device_check [label="START\n\nIs this our own, verified device?", labelfontname="Fira Sans"]
+    outbound_session_check [label="Outbound session exists?"]
+    outbound_exists [label="Session previously previously_shared with this user ID/device ID pair?"]
+    previously_shared [label="Requesting device sender (Curve25519) key matches the key we originally shared with?"]
+    own_device_check [label="Is this our own device?"]
+
+    /* End states */
+    allow_verified [label="Share the entire session from the earliest known index.\n\nOk(None)", color=4, fillcolor=3]
+    allow_limited [label="Share a limited session starting from index i, which is the index we previously shared at.\n\nOk(Some(i))", color=4, fillcolor=3]
+    refuse_device_key_changed [label="Sender key changed, refuse to share.\n\nErr(KeyForwardDecision::ChangedSenderKey)", color=6, fillcolor=5]
+    refuse_not_shared [label="Session was never shared with this device, refuse to share.\n\nErr(KeyForwardDecision::OutboundSessionNotShared)", color=6, fillcolor=5]
+    refuse_untrusted_own_device [label="Our own device, but it is untrusted and we haven't previously shared with it. Refuse to share.\n\nErr(KeyForwardDecision::UntrustedDevice)", color=6, fillcolor=5]
+    refuse_missing_outbound_session [label="Not our device and haven't previously shared with it. Refuse to share.\n\nErr(KeyForwardDecision::MissingOutboundSession)", color=6, fillcolor=5]
+
+    /* Checks */
+
+    /* Is this our own verified device? */
+    verified_device_check -> allow_verified [label="Yes"]
+    verified_device_check -> outbound_session_check [label="No"]
+
+    /* Does the outbound session exist? */
+    outbound_session_check -> outbound_exists [label="Yes"]
+    outbound_session_check -> own_device_check [label="No"]
+
+    /* Previously shared? */
+    outbound_exists -> previously_shared [label="Yes"]
+    outbound_exists -> refuse_not_shared [label="No"]
+
+    /* Requesting device sender key matches key it was shared with? */
+    previously_shared -> allow_limited [label="Yes"]
+    previously_shared -> refuse_device_key_changed [label="No"]
+
+    /* Is this our own device? */
+    own_device_check -> refuse_untrusted_own_device [label="Yes"]
+    own_device_check -> refuse_missing_outbound_session [label="No"]
+}
diff --git a/contrib/key-sharing-algorithm/setdotlabelwidth b/contrib/key-sharing-algorithm/setdotlabelwidth
new file mode 100755
index 000000000..c4c18cc00
--- /dev/null
+++ b/contrib/key-sharing-algorithm/setdotlabelwidth
@@ -0,0 +1,37 @@
+#!/usr/bin/perl
+#
+# Adapted from https://stackoverflow.com/a/68057031
+
+use strict;
+
+my $usage = "setdotlabelwidth [char-width] < [dotfile]";
+my $width = shift() or die("Usage: $usage $!");
+
+while(<STDIN>)
+{
+  if (m/label="(.*?)"/)
+  {
+    my $labeltext = $1;
+    my @words = split(/ +|(?=\\n)/, $labeltext);
+    my @newtext = ();
+    my $newline = "";
+    foreach my $word(@words)
+    {
+      if (length($newline) > 0 and
+          length($newline) + length($word) > $width)
+      {
+        push(@newtext, $newline);
+        $newline = "";
+      }
+
+      $newline .= " " if (length($newline) > 0);
+      $newline .= $word;
+    }
+
+    push(@newtext, $newline) if (length($newline) > 0);
+    my $newlabel = join("\\n", @newtext);
+    s/label=".*?"/label="$newlabel"/;
+  }
+
+  print;
+}