doc/dev/msgr2.rst: update of the banner and authentication phases

Signed-off-by: Ricardo Dias <rdias@suse.com>

diff --git a/doc/dev/msgr2.rst b/doc/dev/msgr2.rst
index a3c17774cb7b168d9d570d122c4eb8e9ec25d357..bedb4e0fed50dc737759320cb0aca51bcbd30eb5 100644 (file)
--- a/doc/dev/msgr2.rst
+++ b/doc/dev/msgr2.rst
@@ -77,8 +77,20 @@ features are defined or required, so this will be "ceph 0 0\n".
 If the remote party advertises required features we don't support, we
 can disconnect.
 
-Frame format
-------------
+
+.. ditaa:: +---------+        +--------+
+           | Client  |        | Server |
+           +---------+        +--------+
+                | send banner     |
+                |----+       +----|
+                |    |       |    |
+                |    +-------+--->|
+                | send banner|    |
+                |<-----------+    |
+                |                 |
+
+Frame format and Stream establishment
+-------------------------------------
 
 All further data sent or received is contained by a frame.  Each frame has
 the form::
@@ -90,6 +102,8 @@ the form::
   [payload padding -- only present after stream auth phase]
   [signature -- only present after stream auth phase]
 
+* stream_id is generated by the client.
+
 * frame_len includes everything after the frame_len le32 up to the end of the
   frame (all payloads, signatures, and padding).
 
@@ -99,14 +113,24 @@ the form::
   authentication phase has completed (TAG_AUTH_DONE has been sent) and
   signatures are enabled.
 
+A new stream is created when the client sends a frame with the following tag
+message:
+
+* TAG_NEW_STREAM (client only): starts a new stream::
+
+    __u8   my_type (CEPH_ENTITY_TYPE_*)
 
-Authentication
---------------
 
-* TAG_AUTH_METHODS (server only): list authentication methods (none, cephx, ...)::
+.. ditaa:: +---------+          +--------+
+           | Client  |          | Server |
+           +---------+          +--------+
+                |  send new stream  |
+                |------------------>|
+                |                   |
 
-    __le32 num_methods;
-    __le32 methods[num_methods];   // CEPH_AUTH_{NONE, CEPHX}
+
+Authentication
+--------------
 
 * TAG_AUTH_SET_METHOD (client only): set auth method for this connection::
 
@@ -118,14 +142,29 @@ Authentication
 * TAG_AUTH_BAD_METHOD (server only): reject client-selected auth method::
 
     __le32 method
+    __le32 num_methods
+    __le32 allowed_methods[num_methods] // CEPH_AUTH_{NONE, CEPHX}
+
+  - Returns the unsupported/forbidden method along with the list of allowed
+    authentication methods.
+
+* TAG_AUTH_REQUEST: client->server::
+
+    __le32 len;
+    method specific payload
 
-* TAG_AUTH: client->server or server->client auth message::
+* TAG_AUTH_REPLY: server->client::
 
     __le32 len;
     method specific payload
 
+* TAG_AUTH_BAD_AUTH: server->client:
+
+  - Sent when the authentication fails
+
+
 * TAG_AUTH_DONE::
-    
+
     confounder (block_size bytes of random garbage)
     __le64 flags
       FLAG_ENCRYPTED  1
@@ -136,6 +175,53 @@ Authentication
     acknowledge it.
 
 
+Example of authentication phase interaction when the client uses an
+allowed authentication method:
+
+.. ditaa:: +---------+        +--------+
+           | Client  |        | Server |
+           +---------+        +--------+
+                | set method      |
+                |---------------->|
+                | auth request    |
+                |---------------->|
+                |<----------------|
+                |       auth reply|
+                |                 |
+                | auth done       |
+                |---------------->|
+                |<----------------|
+                |   auth done ack |
+
+
+Example of authentication phase interaction when the client uses a forbidden
+authentication method as the first attempt:
+
+.. ditaa:: +---------+        +--------+
+           | Client  |        | Server |
+           +---------+        +--------+
+                | set method      |
+                |---------------->|
+                |             +---|
+                | auth request|   |
+                |-------------+-->|
+                |             |   |
+                |<------------+   |
+                |   bad method    |
+                |                 |
+                | set method      |
+                |---------------->|
+                | auth request    |
+                |---------------->|
+                |<----------------|
+                |       auth reply|
+                |                 |
+                | auth done       |
+                |---------------->|
+                |<----------------|
+                |   auth done ack |
+
+
 Message frame format
 --------------------
 
@@ -178,7 +264,7 @@ forms, depending on the AUTH_DONE flags:
   the auth method's block_size so that the message can be sent out over
   the wire without waiting for the next frame in the stream.
 
-    
+
 Message flow handshake
 ----------------------
 
@@ -267,3 +353,44 @@ Once a session is stablished, we can exchange messages.
   could just disconnect the TCP connection, although one could
   certainly use it creatively (e.g., reset the stream state and retry
   an authentication handshake).
+
+
+Example of protocol interaction (WIP)
+_____________________________________
+
+
+.. ditaa:: +---------+        +--------+
+           | Client  |        | Server |
+           +---------+        +--------+
+                | send banner       |
+                |----+       +------|
+                |    |       |      |
+                |    +-------+----->|
+                | send banner|      |
+                |<-----------+      |
+                |                   |
+                |  send new stream  |
+                |------------------>|
+                | set method        |
+                |------------------>|
+                |             +-----|
+                | auth request|     |
+                |-------------+---->|
+                |             |     |
+                |<------------+     |
+                |   bad method      |
+                |                   |
+                | set method        |
+                |------------------>|
+                | auth request      |
+                |------------------>|
+                |<------------------|
+                |       auth reply  |
+                |                   |
+                | auth done         |
+                |------------------>|
+                |<------------------|
+                |   auth done ack   |
+                |                   |
+
+