Reword introduction to federation API to mention event signing

specification/30_server_server_api.rst

@@ -1,40 +1,44 @@
 Federation API
 ===============
 
-Federation is the term used to describe how to communicate between Matrix home
+Matrix home servers use the Federation APIs to communicate with each other.
-servers. Federation is a mechanism by which two home servers can exchange
+Home servers use these APIs to push messages to each other in real-time, to
-Matrix event messages, both as a real-time push of current events, and as a
+request historic messages from each other, and to query profile and presence
-historic fetching mechanism to synchronise past history for clients to view. It
+information about users on each other's servers.
-uses HTTPS connections between each pair of servers involved as the underlying
+
-transport. Messages are exchanged between servers in real-time by active
+The API's are implemented using HTTPS GETs and PUTs between each of the
-pushing from each server's HTTP client into the server of the other. Queries to
+servers. These HTTPS requests are strongly authenticated using public key
-fetch historic data for the purpose of back-filling scrollback buffers and the
+signatures at the TLS transport layer and using public key signatures in
-like can also be performed. Currently routing of messages between homeservers
+HTTP Authorization headers at the HTTP layer.
-is full mesh (like email) - however, fan-out refinements to this design are
-currently under consideration.
 
 There are three main kinds of communication that occur between home servers:
 
-Queries:
+Persisted Data Units (PDUs):
-   These are single request/response interactions between a given pair of
+    These events are broadcast from one home server to any others that have
-   servers, initiated by one side sending an HTTPS GET request to obtain some
+    joined the same "context" (namely, a Room ID). They are persisted in
-   information, and responded by the other. They are not persisted and contain
+    long-term storage and record the history of messages and state for a
-   no long-term significant history. They simply request a snapshot state at
+    context.
-   the instant the query is made.
+
+    Like email, it is the responsibility of the originating server of a PDU
+    to deliver that event to its recepient servers. However PDUs are signed
+    using the originating server's public key so that it is possible to
+    deliver them through third-party servers.
 
 Ephemeral Data Units (EDUs):
-   These are notifications of events that are pushed from one home server to
+    These events are pushed between pairs of home servers. They are not
-   another. They are not persisted and contain no long-term significant
+    persisted and are not part of the history of a "context", nor does the
-   history, nor does the receiving home server have to reply to them.
+    receiving home server have to reply to them.
+
+Queries:
+    These are single request/response interactions between a given pair of
+    servers, initiated by one side sending an HTTPS GET request to obtain some
+    information, and responded by the other. They are not persisted and contain
+    no long-term significant history. They simply request a snapshot state at
+    the instant the query is made.
 
-Persisted Data Units (PDUs):
-   These are notifications of events that are broadcast from one home server to
-   any others that are interested in the same "context" (namely, a Room ID).
-   They are persisted to long-term storage and form the record of history for
-   that context.
 
 EDUs and PDUs are further wrapped in an envelope called a Transaction, which is
-transferred from the origin to the destination home server using an HTTP PUT
+transferred from the origin to the destination home server using an HTTPS PUT
 request.