SYN-39: Add documentation explaining how to check a signature

This commit is contained in:
Mark Haines 2014-09-18 18:14:53 +01:00
parent e0fa4cf874
commit fceb5f7b22

View file

@ -39,18 +39,40 @@ and additional signatures.
:: ::
def sign_json(value, signing_key, signing_name): def sign_json(json_object, signing_key, signing_name):
signatures = value.pop("signatures", {}) signatures = json_object.pop("signatures", {})
signatures_for_name = signatures.pop(signing_name, {}) meta = json_object.pop("meta", None)
meta = value.pop("meta", None)
signature = signing_key.sign(canonical_json(value)) signed = signing_key.sign(encode_canonical_json(json_object))
key_identifier = "%s:%s" % (signing_key.algorithm, signing_key.version) signature_base64 = encode_base64(signed.signature)
signatures_for_name[key_identifier] = encode_base64(signature.signature)
signatures[signing_name] = signatures_for_name key_id = "%s:%s" % (signing_key.alg, signing_key.version)
value["signatures"] = signatures signatures.setdefault(sigature_name, {})[key_id] = signature_base64
json_object["signatures"] = signatures
if meta is not None: if meta is not None:
value["meta"] = meta json_object["meta"] = meta
return value
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 Canonical JSON
-------------- --------------