From 63de4681299428db8be68bab64b969e0c1229273 Mon Sep 17 00:00:00 2001 From: Kristian Høgsberg Date: Wed, 2 Jun 2004 14:03:58 +0000 Subject: 2004-06-02 Kristian Høgsberg MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * dbus/dbus-auth.c: Rewrite auth protocol handling to use a state machine approach. A state is implemented as a function that handles incoming events as specified for that state. * doc/dbus-specification.xml: Update auth protocol state machine specification to match implementation. Remove some leftover base64 examples. --- doc/dbus-specification.xml | 461 +++++++++++++++++++++++++++++++++------------ 1 file changed, 345 insertions(+), 116 deletions(-) (limited to 'doc') diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index aacb480a..94f72bf8 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -822,7 +822,7 @@ AUTH [mechanism] [initial-response] CANCEL BEGIN - DATA <data in base 64 encoding> + DATA <data in hex encoding> ERROR [human-readable error explanation] @@ -831,7 +831,7 @@ REJECTED <space-separated list of mechanism names> OK - DATA <data in base 64 encoding> + DATA <data in hex encoding> ERROR @@ -994,7 +994,7 @@ (MAGIC_COOKIE is a made up mechanism) - C: AUTH MAGIC_COOKIE BsAY3g4gBNo= + C: AUTH MAGIC_COOKIE 3138363935333137393635383634 S: OK C: BEGIN @@ -1004,9 +1004,9 @@ C: AUTH S: REJECTED KERBEROS_V4 SKEY - C: AUTH SKEY bW9yZ2Fu - S: DATA OTUgUWE1ODMwOA== - C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA== + C: AUTH SKEY 7ab83f32ee + S: DATA 8799cabb2ea93e + C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f S: OK C: BEGIN @@ -1016,7 +1016,7 @@ C: FOOBAR S: ERROR - C: AUTH MAGIC_COOKIE BsAY3g4gBNo= + C: AUTH MAGIC_COOKIE 3736343435313230333039 S: OK C: BEGIN @@ -1024,11 +1024,11 @@
Example of server doesn't support initial auth mechanism - C: AUTH MAGIC_COOKIE BsAY3g4gBNo= + C: AUTH MAGIC_COOKIE 3736343435313230333039 S: REJECTED KERBEROS_V4 SKEY - C: AUTH SKEY bW9yZ2Fu - S: DATA OTUgUWE1ODMwOA== - C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA== + C: AUTH SKEY 7ab83f32ee + S: DATA 8799cabb2ea93e + C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f S: OK C: BEGIN @@ -1036,15 +1036,15 @@
Example of wrong password or the like followed by successful retry - C: AUTH MAGIC_COOKIE BsAY3g4gBNo= + C: AUTH MAGIC_COOKIE 3736343435313230333039 S: REJECTED KERBEROS_V4 SKEY - C: AUTH SKEY bW9yZ2Fu - S: DATA OTUgUWE1ODMwOA== - C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA== + C: AUTH SKEY 7ab83f32ee + S: DATA 8799cabb2ea93e + C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f S: REJECTED - C: AUTH SKEY bW9yZ2Fu - S: DATA OTUgUWE1ODMwOA== - C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA== + C: AUTH SKEY 7ab83f32ee + S: DATA 8799cabb2ea93e + C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f S: OK C: BEGIN @@ -1052,15 +1052,15 @@
Example of skey cancelled and restarted - C: AUTH MAGIC_COOKIE BsAY3g4gBNo= + C: AUTH MAGIC_COOKIE 3736343435313230333039 S: REJECTED KERBEROS_V4 SKEY - C: AUTH SKEY bW9yZ2Fu - S: DATA OTUgUWE1ODMwOA== + C: AUTH SKEY 7ab83f32ee + S: DATA 8799cabb2ea93e C: CANCEL S: REJECTED - C: AUTH SKEY bW9yZ2Fu - S: DATA OTUgUWE1ODMwOA== - C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA== + C: AUTH SKEY 7ab83f32ee + S: DATA 8799cabb2ea93e + C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f S: OK C: BEGIN @@ -1079,73 +1079,178 @@ Client states - - <emphasis>Start</emphasis> - - - send AUTH with initial data -> WaitingForData - send AUTH with no initial data -> WaitingForData or NeedSendData (depends on mechanism) - - The Start state is stateful (it has a list of - available mechanisms and those it has already attempted). This list - is used to decide which AUTH command to send. When the list is - exhausted, the client should give up and close the connection. - - + + To more precisely describe the interaction between the + protocol state machine and the authentication mechanisms the + following notation is used: MECH(CHALL) means that the + server challenge CHALL was fed to the mechanism MECH, which + returns one of + + + + + CONTINUE(RESP) means continue the auth conversation + and send RESP as the response to the server; + + + + + + OK(RESP) means that after sending RESP to the server + the client side of the auth conversation is finished + and the server should return "OK"; + + + + + + ERROR means that CHALL was invalid and could not be + processed. + + + + + Both RESP and CHALL may be empty. + + + + The Client starts by getting an initial response from the + default mechanism and sends AUTH MECH RESP, or AUTH MECH if + the mechanism did not provide an initial response. If the + mechanism returns CONTINUE, the client starts in state + WaitingForData, if the mechanism + returns OK the client starts in state + WaitingForOK. + + + + The client should keep track of available mechanisms and + which it mechanisms it has already attempted. This list is + used to decide which AUTH command to send. When the list is + exhausted, the client should give up and close the + connection. + <emphasis>WaitingForData</emphasis> - - receive OK -> NeedSendBegin - receive REJECTED -> Start - receive ERROR -> Start - receive DATA -> NeedSendData - receive anything else -> NeedSendError - - When going back to Start, the mechanism in - progress should be marked as failed and not retried (at least not - with the same parameters). When receiving REJECTED with a list of - mechanisms, the list should be recorded and used to select - a mechanism. - - + + + Receive DATA CHALL + + + MECH(CHALL) returns CONTINUE(RESP) → send + DATA RESP, goto + WaitingForData + + + + MECH(CHALL) returns OK(RESP) → send DATA + RESP, goto WaitingForOK + + + + MECH(CHALL) returns ERROR → send ERROR + [msg], goto WaitingForData + + + + - - <emphasis>NeedSendData</emphasis> - - - send DATA -> WaitingForData - send CANCEL -> Start + + + Receive REJECTED [mechs] → + send AUTH [next mech], goto + WaitingForData or WaitingForOK + + + + + Receive ERROR → send + CANCEL, goto + WaitingForReject + + + + + Receive OK → send + BEGIN, terminate auth + conversation, authenticated + + + + + Receive anything else → send + ERROR, goto + WaitingForData + + - <emphasis>NeedSendError</emphasis> + <emphasis>WaitingForOK</emphasis> - - send ERROR -> return to previous state + + + Receive OK → send BEGIN, terminate auth + conversation, authenticated + + + + + Receive REJECT [mechs] → send AUTH [next mech], + goto WaitingForData or + WaitingForOK + + + + + + Receive DATA → send CANCEL, goto + WaitingForReject + + + + + + Receive ERROR → send CANCEL, goto + WaitingForReject + + + + + + Receive anything else → send ERROR, goto + WaitingForOK + + - <emphasis>NeedSendBegin</emphasis> + <emphasis>WaitingForReject</emphasis> - - send BEGIN -> Authorized - - - + + + Receive REJECT [mechs] → send AUTH [next mech], + goto WaitingForData or + WaitingForOK + + - - <emphasis>Authorized</emphasis> - - This is the end state, flow of messages begins. + + + Receive anything else → terminate auth + conversation, disconnect + + + @@ -1153,57 +1258,164 @@ Server states - + + + For the server MECH(RESP) means that the client response + RESP was fed to the the mechanism MECH, which returns one of + + + + + CONTINUE(CHALL) means continue the auth conversation and + send CHALL as the challenge to the client; + + + + + + OK means that the client has been successfully + authenticated; + + + + + + REJECT means that the client failed to authenticate or + there was an error in RESP. + + + + + The server starts out in state + WaitingForAuth. If the client is + rejected too many times the server must disconnect the + client. + + <emphasis>WaitingForAuth</emphasis> - receive AUTH with initial response -> NeedSendData - receive AUTH without initial response -> NeedSendData or WaitingForData depending on mechanism - - - - - <emphasis>NeedSendData</emphasis> - - - send DATA -> WaitingForData - send ERROR -> WaitingForData - send REJECTED -> WaitingForAuth - send OK -> WaitingForBegin + + + Receive AUTH → send REJECTED [mechs], goto + WaitingForAuth + + + + + + Receive AUTH MECH RESP + + + + MECH not valid mechanism → send REJECTED + [mechs], goto + WaitingForAuth + + + + MECH(RESP) returns CONTINUE(CHALL) → send + DATA CHALL, goto + WaitingForData + + + + MECH(RESP) returns OK → send OK, goto + WaitingForBegin + + + + MECH(RESP) returns REJECT → send REJECTED + [mechs], goto + WaitingForAuth + + + + + + + + Receive BEGIN → terminate + auth conversation, disconnect + + + + + + Receive ERROR → send REJECTED [mechs], goto + WaitingForAuth + + + + + + Receive anything else → send + ERROR, goto + WaitingForAuth + + + <emphasis>WaitingForData</emphasis> - receive DATA -> NeedSendData - receive CANCEL -> NeedSendRejected - receive ERROR -> NeedSendRejected - receive anything else -> NeedSendError - - - + + + Receive DATA RESP + + + MECH(RESP) returns CONTINUE(CHALL) → send + DATA CHALL, goto + WaitingForData + + + + MECH(RESP) returns OK → send OK, goto + WaitingForBegin + + + + MECH(RESP) returns REJECT → send REJECTED + [mechs], goto + WaitingForAuth + + + + - - <emphasis>NeedSendError</emphasis> - - - - send ERROR -> return to previous state - - - + + + Receive BEGIN → terminate auth conversation, + disconnect + + - - <emphasis>NeedSendRejected</emphasis> - - - - send REJECTED -> WaitingForAuth + + + Receive CANCEL → send REJECTED [mechs], goto + WaitingForAuth + + + + + + Receive ERROR → send REJECTED [mechs], goto + WaitingForAuth + + + + + + Receive anything else → send ERROR, goto + WaitingForData + + @@ -1211,18 +1423,35 @@ <emphasis>WaitingForBegin</emphasis> - - receive BEGIN -> Authorized - receive anything else -> NeedSendError - - - + + + Receive BEGIN → terminate auth conversation, + client authenticated + + - - <emphasis>Authorized</emphasis> - - This is the end state, flow of messages begins. + + + Receive CANCEL → send REJECTED [mechs], goto + WaitingForAuth + + + + + + Receive ERROR → send REJECTED [mechs], goto + WaitingForAuth + + + + + + Receive anything else → send ERROR, goto + WaitingForBegin + + + -- cgit