Small changes because things have become clearer

auth.capnp

@@ -25,32 +25,17 @@
 using Rust = import "rust.capnp";
 $Rust.parentModule("auth");
 
-# ==============================================================================
-# SASL Notes:
-#
-# - TLS and SASL security layers may not be both installed
-# - A SASL security layer takes effect on the first octet following the outcome
-#   message in data being sent by the server and on the first octet sent after
-#   receipt of the outcome message in data being sent by the client.
-# - Multiple authentication is currently NOT supported.
-# ==============================================================================
-
 struct AuthMessage {
     union {
-        discover @0 :Void;
+        mechanisms @0 :List(Text);
-        # Message sent by a client to discover the list of available mechanisms.
+        # Message sent by a server supplying the list of available mechanisms.
-        # MUST NOT be sent during an ongoing authentication exchange.
 
-        mechanisms @1 :List(Text);
+        request @1 :Request;    # Authentication initiation sent by the client.
-        # Message sent by a server as reply to a `Discover` message supplying
+        challenge @2 :Data;     # Challenge sent by the server to the client
-        # the list of available mechanisms in the current context.
+        response @3 :Data;      # Response sent by the client to the server
+        outcome @4 :Outcome;    # Final outcome sent by the server
 
-        request @2 :Request;    # Authentication initiation sent by the client.
+        abort @5 :Void;
-        challenge @3 :Data;     # Challenge sent by the server to the client
-        response @4 :Data;      # Response sent by the client to the server
-        outcome @5 :Outcome;    # Final outcome sent by the server
-
-        abort @6 :Void;
         # Abort the current exchange. This may be sent by both client and server
         # at any point during the exchange. It MUST not be sent by a server
         # after sending an outcome or by a client after receiving an outcome.
@@ -64,7 +49,7 @@ struct Request {
 
     initialResponse :union {
         # A client may send some intial data when requesting an auth exchange.
-        # According to RFC4422 section 4.3a an implementation MUST to be able to
+        # According to RFC4422 section 4.3a an implementation MUST be able to
         # distinguish between an empty initial reponse and no initial response.
 
         none @1 :Void; 
@@ -83,27 +68,30 @@ struct Outcome {
         # Result code of the outcome
         successful @0;
 
-        unwilling @1;
+        badMechanism @1;
+        # The server does not support this mechanism in this context.
+
+        unwilling @2;
         # Generic "I'm sorry dave, I can't do that" response. MAY be set for any
         # reason, all reasons or no reason at all. 
         # A server SHOULD set the `action` and `helpText` fields as appropiate.
         # This code SHOULD only be sent if no other value is more fitting.
 
-        invalidCredentials @2;
+        invalidCredentials @3;
         # The exchange was valid, but the provided credentials are invalid. This
         # may mean that the authcid is not known to the server or that the
         # password/certificate/key/etc.  is not correct.
 
-        unauthorized @3;
+        unauthorized @4;
         # The given authcid is not authorized to act as the requested authzid.
         # This MAY also be returned for the cases `authzid == NULL` or 
         # `authzid == authcid`, for example because login is disabled for that
         # authcid.
 
-        malformedAuthZid @4;
+        malformedAuthZid @5;
         # The provided authzid is malformed in some way.
 
-        failed @5;
+        failed @6;
         # A generic failed result. A server sending this result MUST set the
         # `action` field to indicate whether this is a temporary or permanent
         # failure and SHOULD set `helpText` to a human-readable error message.

connection.capnp

@@ -30,13 +30,13 @@ struct Message {
         greet @0 :Greeting;
         # Be polite and say hello to the other end
 
-        auth @1 :Auth.AuthMessage;
+        leave @1 :Leave;
+
+        auth @2 :Auth.AuthMessage;
         # Start an authenticaion exchange
 
-        starttls @2 :Void;
-        # Start a tls handshake
-
         # TODO: RPC bootstrapping
+
     }
 }
 
@@ -55,3 +55,22 @@ struct Greeting {
     major @2 :UInt32; # The major part of the API version
     minor @3 :UInt32; # The minor part of the API version
 }
+
+struct Leave {
+    # Be nice and tell the other side before aborting a connection
+    enum Reason {
+        other @0;
+        # None of the more specific reasons.  An implementation SHOULD provide
+        # more (human-readable) information in the `message` field.
+
+        incompatible @1;
+        # The API versions are in some way incompatible.  Doesn't need much of
+        # an explanation so an implementation MAY leave the message field
+        # empty.
+    }
+
+    reason @0 :Reason;
+    message @1 :Text;   
+    # An implementation SHOULD send a human-readable message along, with the
+    # exception of reasons that are self-explanatory (e.g. incompatible versions)
+}