From fceb5f7b22c6255515abafc69924c6f9ec38d993 Mon Sep 17 00:00:00 2001
From: Mark Haines <mark.haines@matrix.org>
Date: Thu, 18 Sep 2014 18:14:53 +0100
Subject: SYN-39: Add documentation explaining how to check a signature

---
 docs/server-server/signing.rst | 44 +++++++++++++++++++++++++++++++-----------
 1 file changed, 33 insertions(+), 11 deletions(-)

diff --git a/docs/server-server/signing.rst b/docs/server-server/signing.rst
index bf85443dfa..bcb89a79a0 100644
--- a/docs/server-server/signing.rst
+++ b/docs/server-server/signing.rst
@@ -39,18 +39,40 @@ and additional signatures.
 
 ::
 
-  def sign_json(value, signing_key, signing_name):
-      signatures = value.pop("signatures", {})
-      signatures_for_name = signatures.pop(signing_name, {})
-      meta = value.pop("meta", None)
-      signature = signing_key.sign(canonical_json(value))
-      key_identifier = "%s:%s" % (signing_key.algorithm, signing_key.version)
-      signatures_for_name[key_identifier] = encode_base64(signature.signature)
-      signatures[signing_name] = signatures_for_name
-      value["signatures"] = signatures
+  def sign_json(json_object, signing_key, signing_name):
+      signatures = json_object.pop("signatures", {})
+      meta = json_object.pop("meta", None)
+
+      signed = signing_key.sign(encode_canonical_json(json_object))
+      signature_base64 = encode_base64(signed.signature)
+
+      key_id = "%s:%s" % (signing_key.alg, signing_key.version)
+      signatures.setdefault(sigature_name, {})[key_id] = signature_base64
+
+      json_object["signatures"] = signatures
       if meta is not None:
-          value["meta"] = meta
-      return value
+          json_object["meta"] = meta
+
+      return json_object
+
+Checking for a Signature
+------------------------
+
+To check if an entity has signed a JSON object a server does the following
+
+1. Checks if the ``signatures`` object contains an entry with the name of the
+   entity. If the entry is missing then the check fails.
+2. Removes any *signing key identifiers* from the entry with algrothims it
+   doesn't understand. If there are no *signing key identifiers* left then the
+   check fails.
+3. Looks up *verification keys* for the remaining *signing key identifiers*
+   either from a local cache or by consulting a trusted key server. If it
+   cannot find a *verification key* then the check fails.
+4. Decodes the base64 encoded signature bytes. If base64 decoding fails then
+   the check fails.
+5. Checks the signature bytes using the *verification key*. If this fails then
+   the check fails. Otherwise the check succeeds.
+
 
 Canonical JSON
 --------------
-- 
cgit 1.4.1