diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/server-server/signing.rst | 28 |
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]] |