Add a database for storing the server keys (#137)

* Add a database for storing the server keys

* Tweak wording, and comment on the resolution of the timestamp

* Update gomatrixserverlib

vendor/manifest

@@ -98,7 +98,7 @@
 		{
 			"importpath": "github.com/matrix-org/gomatrixserverlib",
 			"repository": "https://github.com/matrix-org/gomatrixserverlib",
-			"revision": "b1dfcb3b345cc8410f1a03fec0a1ffe6bd002dcd",
+			"revision": "0e1596ae7b0a034ec572cd1448aeaf7e96bff95a",
 			"branch": "master"
 		},
 		{

vendor/src/github.com/matrix-org/gomatrixserverlib/keyring.go

@@ -32,6 +32,12 @@ type KeyFetcher interface {
 type KeyDatabase interface {
 	KeyFetcher
 	// Add a block of public keys to the database.
+	// Returns an error if there was a problem storing the keys.
+	// A database is not required to rollback storing the all keys if some of
+	// the keys aren't stored, and an in-progess store may be partially visible
+	// to a concurrent FetchKeys(). This is acceptable since the database is
+	// only used as a cache for the keys, so if a FetchKeys() races with a
+	// StoreKeys() and some of the keys are missing they will be just be refetched.
 	StoreKeys(map[PublicKeyRequest]ServerKeys) error
 }
 

vendor/src/github.com/matrix-org/gomatrixserverlib/signing.go

@@ -30,15 +30,22 @@ type KeyID string
 // SignJSON signs a JSON object returning a copy signed with the given key.
 // https://matrix.org/docs/spec/server_server/unstable.html#signing-json
 func SignJSON(signingName string, keyID KeyID, privateKey ed25519.PrivateKey, message []byte) ([]byte, error) {
+	// Unpack the top-level key of the JSON object without unpacking the contents of the keys.
+	// This allows us to add and remove the top-level keys from the JSON object.
+	// It also ensures that the JSON is actually a valid JSON object.
 	var object map[string]*json.RawMessage
 	var signatures map[string]map[KeyID]Base64String
 	if err := json.Unmarshal(message, &object); err != nil {
 		return nil, err
 	}
 
+	// We don't sign the contents of the unsigned key so we remove it.
 	rawUnsigned, hasUnsigned := object["unsigned"]
 	delete(object, "unsigned")
 
+	// Parse the existing signatures if they exist.
+	// Signing a JSON object adds our signature to the existing
+	// signature rather than replacing it.
 	if rawSignatures := object["signatures"]; rawSignatures != nil {
 		if err := json.Unmarshal(*rawSignatures, &signatures); err != nil {
 			return nil, err
@@ -48,32 +55,35 @@ func SignJSON(signingName string, keyID KeyID, privateKey ed25519.PrivateKey, me
 		signatures = map[string]map[KeyID]Base64String{}
 	}
 
+	// Encode the JSON object without the "signatures" key or
+	// the "unsigned" key in the canonical format.
 	unsorted, err := json.Marshal(object)
 	if err != nil {
 		return nil, err
 	}
-
 	canonical, err := CanonicalJSON(unsorted)
 	if err != nil {
 		return nil, err
 	}
 
+	// Sign the canonical JSON with the ed25519 key.
 	signature := Base64String(ed25519.Sign(privateKey, canonical))
 
+	// Add the signature to the "signature" key.
 	signaturesForEntity := signatures[signingName]
 	if signaturesForEntity != nil {
 		signaturesForEntity[keyID] = signature
 	} else {
 		signatures[signingName] = map[KeyID]Base64String{keyID: signature}
 	}
-
 	var rawSignatures json.RawMessage
 	rawSignatures, err = json.Marshal(signatures)
 	if err != nil {
 		return nil, err
 	}
-
 	object["signatures"] = &rawSignatures
+
+	// Add the unsigned key back if it was present.
 	if hasUnsigned {
 		object["unsigned"] = rawUnsigned
 	}
@@ -98,41 +108,45 @@ func ListKeyIDs(signingName string, message []byte) ([]KeyID, error) {
 
 // VerifyJSON checks that the entity has signed the message using a particular key.
 func VerifyJSON(signingName string, keyID KeyID, publicKey ed25519.PublicKey, message []byte) error {
+	// Unpack the top-level key of the JSON object without unpacking the contents of the keys.
+	// This allows us to add and remove the top-level keys from the JSON object.
+	// It also ensures that the JSON is actually a valid JSON object.
 	var object map[string]*json.RawMessage
 	var signatures map[string]map[KeyID]Base64String
 	if err := json.Unmarshal(message, &object); err != nil {
 		return err
 	}
-	delete(object, "unsigned")
 
+	// Check that there is a signature from the entity that we are expecting a signature from.
 	if object["signatures"] == nil {
 		return fmt.Errorf("No signatures")
 	}
-
 	if err := json.Unmarshal(*object["signatures"], &signatures); err != nil {
 		return err
 	}
-	delete(object, "signatures")
-
 	signature, ok := signatures[signingName][keyID]
 	if !ok {
 		return fmt.Errorf("No signature from %q with ID %q", signingName, keyID)
 	}
-
 	if len(signature) != ed25519.SignatureSize {
 		return fmt.Errorf("Bad signature length from %q with ID %q", signingName, keyID)
 	}
 
+	// The "unsigned" key and "signatures" keys aren't covered by the signature so remove them.
+	delete(object, "unsigned")
+	delete(object, "signatures")
+
+	// Encode the JSON without the "unsigned" and "signatures" keys in the canonical format.
 	unsorted, err := json.Marshal(object)
 	if err != nil {
 		return err
 	}
-
 	canonical, err := CanonicalJSON(unsorted)
 	if err != nil {
 		return err
 	}
 
+	// Verify the ed25519 signature.
 	if !ed25519.Verify(publicKey, canonical, signature) {
 		return fmt.Errorf("Bad signature from %q with ID %q", signingName, keyID)
 	}