Protocol / client plugin changes to support interactively asking for a PIN

remoting/protocol/negotiating_authenticator.h

Index: remoting/protocol/negotiating_authenticator.h
diff --git a/remoting/protocol/negotiating_authenticator.h b/remoting/protocol/negotiating_authenticator.h
index a87d543e3ca98606ea4265013c0e39cff0056f50..146a412884778a871d08ee7f09bbfd4f2b04ec7a 100644
--- a/remoting/protocol/negotiating_authenticator.h
+++ b/remoting/protocol/negotiating_authenticator.h
@@ -20,16 +20,55 @@ class RsaKeyPair;
 
 namespace protocol {
 
+class PinFetcherFactory;
+
+// This class provides a meta-authenticator that allows clients and hosts that
+// support multiple authentication methods to negotiate a method to use.
+//
+// The typical flow is:
+//  * Client sends a message to host with its supported methods.
+//      (clients may also pick a method and send its first message here).
+//  * Host picks a method and sends its first message (if any).
+//      (if a supported method/message was sent by a client, it is processed).
+//  * Client creates the authenticator selected by the host. If the method
+//      starts with a message from the host, it is processed.
+//  * Client and host exchange messages until the authentication is ACCEPTED or
+//      REJECTED.
+//
+// The details:
+//  * The underlying message processing may be asynchronous (i.e. require user
+//      interaction based on the message contents), so it receives a callback to
+//      resume processing when done.
+//  * Creating an authenticator may also be asynchronous (i.e. require user
+//      interaction to determine initial parameters, like PIN), so it also
+//      receives a callback.  If the authenticator has received a message to
+//      process, the message processing code must also be on that callback.
+//  * Some authentication methods may have a specific starting direction (e.g.
+//      host always sends the first message), while others are versatile (e.g.
+//      SPAKE, where either side can send the first message). So when an
+//      authenticator is created, it is given a "preferred" (context-dependent)
+//      initial state, but it may ignore it, and the negotiating authenticator
+//      must deal with that, by sending a blank message if the method has none
+//      to send, and ignoring such blank message on the receiving end. This
+//      relies on the assumption that each method must either be versatile on
+//      both ends, or name an explicit direction to start.
+//  * The client may pick a method on its first message (assuming it doesn't
+//      require user interaction to start), and the host may not support that
+//      method, in which case it must discard that message and create an
+//      authenticator for a mutually supported method.
+//  * The host never sends its own supported methods back to the client, so once
+//      the host picks a method from the client's list, it's final.
+//  * Any change in this class must maintain compatibility between any version
+//      mix of webapp, client plugin and host, for both Me2Me and IT2Me.
 class NegotiatingAuthenticator : public Authenticator {
  public:
   virtual ~NegotiatingAuthenticator();
 
-  static bool IsNegotiableMessage(const buzz::XmlElement* message);
-
   // Creates a client authenticator for the given methods.
   static scoped_ptr<Authenticator> CreateForClient(
       const std::string& authentication_tag,
       const std::string& shared_secret,
+      PinFetcherFactory* pin_fetcher_factory,
       const std::vector<AuthenticationMethod>& methods);
 
   // Creates a host authenticator, using a fixed shared secret/PIN hash.
@@ -49,10 +88,22 @@ class NegotiatingAuthenticator : public Authenticator {
       CreateChannelAuthenticator() const OVERRIDE;
 
  private:
-  NegotiatingAuthenticator(Authenticator::State initial_state);
+  explicit NegotiatingAuthenticator(Authenticator::State initial_state);
 
   void AddMethod(const AuthenticationMethod& method);
-  void CreateAuthenticator(State initial_state);
+
+  // (Asynchronously) creates an authenticator. Authenticators that can be
+  // started in either state will be created in |preferred_initial_state|.
+  // |resume_callback| is called when the authenticator is ready.
+  void CreateAuthenticator(Authenticator::State preferred_initial_state,
+                           const base::Closure& resume_callback);
+
+  // Processes a message in the current authenticator. |message| and
+  // |resume_callback| are passed to the underlying ProcessMessage call.
+  void ProcessMessageInternal(const buzz::XmlElement* message,
+                              const base::Closure& resume_callback);
+
+  // Updates |state_| to reflect the current underlying authenticator state.
   void UpdateState(const base::Closure& resume_callback);
 
   bool is_host_side() const;
@@ -65,6 +116,7 @@ class NegotiatingAuthenticator : public Authenticator {
   // Used only for client authenticators.
   std::string authentication_tag_;
   std::string shared_secret_;
+  PinFetcherFactory* pin_fetcher_factory_;
 
   // Used for both host and client authenticators.
   std::vector<AuthenticationMethod> methods_;