Federation_Details.md

@@ -19,7 +19,8 @@ But what is the data that is exchanged, and how do federated environments intera
 When needed we will use these abbreviations:
 * **AS**: Authentication Server
 * **S**: Service
-* **C**: Client
+* **A**: Application
+* **C**: Client Manager
 
 In our federated examples, the client from **example.org** will connect to **example.com** (note the different TLD)
 
@@ -28,8 +29,8 @@ In our federated examples, the client from **example.org** will connect to **exa
 each client must have:
 * authentication data (token or user/pass)
 * client id: 128bit, randomly generated by the client only once on its very first setup, then saved somewhere.
-* tokens: random 128 or 256bit, used to authenticate to other federated domains.
-* authorization types: one per token: 1 byte to limit actions of the users.
+* tokens: random 128bit, used for authentication and authorization.
+* authorization type: one per token: 1 byte to limit the users' privileges.
 
 ## The Authorization
 
@@ -37,11 +38,11 @@ Fenrir supports authentication, but how is authorization different?
 
 Authorization defines the set of privileges that a user can have.
 
-Usually when we login somewhere we have complete access to the action that user can do -- This is authentication without authorization.
+Usually when we login somewhere we have complete access to the action that user can do -- This is authentication without authorization, or just a binary authorization.
 
 In OAuth and other protocols the concept of authorization is introduced to limit what the user can do with that authenticated connection.
 
-If we apply the authorization to a scenario where the client can connect multiple times with multiple applications or devices, we can easily imagine that we might want one application to have some rights (example: read-only), while an other might have full access.
+If we apply the authorization to a scenario where the client can connect multiple times with multiple applications or devices, we can easily imagine that we might want one application to have some rights (example: read-only), while an other might have full access. Think about giving your bank account details to your phone.
 
 # Introducing the Authorization Lattice
 
@@ -49,13 +50,14 @@ The new concept introduced in Fenrir is that of an **authorization lattice**: we
 
 Take this authorization lattice for example:
 
-![LATTICE](https://www.fenrirproject.org/Fenrir/Fenrir_Project/uploads/cadbfd179b010a3e9510285f466fb8d1/LATTICE.png)
+![LATTICE](/uploads/628ebc3e3d38a3cb6956cd3cecdfef35/LATTICE.png)
 
-Recall that in a client device we find a Fenrir Client and the applications. The Fenrir Client manages the tokens, the applications only receive connection data.
+
+Recall that in a client device we find a Client Manager and the applications. The Client Manager manages the tokens, the applications only receive connection data.
 
 When a client is issued a token, each token is tied to an authorization. Let's consider a token which is tied to the "Modify" authorization in the lattice above.
 
-Since a token is bounded to the "modify" authorization, during authentication the client says he has this token for the "modify" authorization, but he wants a limited authorization a lower level of the lattice ("read or "bottom" in the example").
+Since a token is bounded to the "modify" authorization, during authentication the client says he has this token for the "modify" authorization, but he wants a limited authorization a lower level of the lattice ("read" or "bottom" in the example).
 
 After checking that the token is valid and the client isn't asking for more authorization that his token can grant, the Auth.Serv. simply proceeds with authentication.
 
@@ -67,16 +69,22 @@ The whole authentication works more or less like this:
 
 In a successful communication setup this happens:
 * **C** sends to **AS**:
-    * authentication data (token, user/pass, other...)
+    * authentication data (user/token)
     * client id
     * authorization type
 * **AS** verifies the information and sends to the Service:
-    * new client keys, id, ip
-    * new client authorization type
+    * user id, authorization type.
+* **S** sends back to the **AS**:
+    * encryption keys
+    * connection id
 * **AS** sends to the client:
-    * client keys
+    * encryption keys, connection id
+    * Service ip, port etc...
+* the **C** will give to the application:
+    * encryption keys
     * Service ip, port etc...
-* the client can now connect to the service.
+    * authorization type
+* the application can now connect to the service.
 
 ## different domain authentication
 
@@ -86,6 +94,7 @@ Assuming **C** and **AS** are in the same domain, and **AS2** and **S2** are in
 * **AS** gives back a token
 * **C** uses the token to authenticate with **AS2**, in the other domain, asking for service **S2**
 * **AS** and **AS2** verify the token, **AS2** might send the service lattice to **AS**
+* **AS2** informs **S2** of a new users, and gets back the encryption keys and connection information
 * **AS2** sends the service data to **C**
 * **C** can connect to the **S2**
 
@@ -93,7 +102,7 @@ Assuming **C** and **AS** are in the same domain, and **AS2** and **S2** are in
 
 This lattice management means that the service has to synchronize the authorization lattice with all the Authentication Servers that play a role in the authentication and with the client.
 
-While this is not a big problem intra-domain, it can be a little problem in intra-domain setups.
+While this is not a big problem inter-domain, it can be a little problem in intra-domain setups.
 
 ## Lattice size
 
@@ -101,9 +110,9 @@ The lattice will be transferred as a list of:
 * one byte: lattice version
 * one byte: number X of nodes (max:64)
 * X 64 bit bitmask to represent connections between nodes
-* X null-terminated strings (max: 25 char?) as node label
+* X null-terminated strings (max: 25 char) as node label
 
-This means that a full lattice weights 2+8**64+64**25 = 2114 bytes, which is 2 packets at maximum.
+This means that a full lattice weights 2+8**64+64**25 = 2114 bytes, which is 2 ethernet packets at maximum.
 
 ## Lattice synching