Add section to explain how to sign events such that we can redact message contents

1 files changed, 27 insertions, 1 deletions

diff --git a/docs/server-server/signing.rst b/docs/server-server/signing.rst
index bcb89a79a0..2489f36b0a 100644
--- a/docs/server-server/signing.rst
+++ b/docs/server-server/signing.rst
@@ -73,7 +73,6 @@ To check if an entity has signed a JSON object a server does the following
 5. Checks the signature bytes using the *verification key*. If this fails then
    the check fails. Otherwise the check succeeds.
 
-
 Canonical JSON
 --------------
 
@@ -123,3 +122,30 @@ insignificant whitespace, fractions, exponents and redundant character escapes
            / %x74 ; t    tab             U+0009
            / %x75.30.30.30 (%x30-37 / %x62 / %x65-66) ; u000X
            / %x75.30.30.31 (%x30-39 / %x61-66)        ; u001X
+
+Signing Events
+==============
+
+Signing events is a more complicated process since servers can choose to redact
+non-essential event contents. Before signing the event it is encoded as
+Canonical JSON and hashed using SHA-256. The resulting hash is then stored
+in the event JSON in a ``hash`` object under a ``sha256`` key. Then all
+non-essential keys are striped from the event object and the resulting object
+which included the ``hash`` key is signed using the JSON signing algorithm.
+
+Servers can then transmit the entire event or the event with the non-essential
+keys removed. Recieving servers can then check the entire event if it is
+present by computing the SHA-256 of the event excluding the ``hash`` object or
+by using the ``hash`` object including in the event if keys have been redacted.
+
+New hash functions can be introduced by adding additional keys to the ``hash``
+object. Since the ``hash`` object cannot be redacted a server shouldn't allow
+too many hashes to be listed, otherwise a server might embed illict data within
+the ``hash`` object. For similar reasons a server shouldn't allow hash values
+that are too long.
+
+[[TODO(markjh): We might want to specify a maximum number of keys for the
+``hash`` and we might want to specify the maximum output size of a hash]]
+
+[[TODO(markjh) We might want to allow the server to omit the output of well
+known hash functions like SHA-256 when none of the keys have been redacted]]