components/proximity_auth/device_to_device_authenticator.h

   1 // Copyright 2015 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef COMPONENTS_PROXIMITY_DEVICE_TO_DEVICE_AUTHENTICATOR_H
   6 #define COMPONENTS_PROXIMITY_DEVICE_TO_DEVICE_AUTHENTICATOR_H
   7
   8 #include "base/callback.h"
   9 #include "base/macros.h"
  10 #include "base/memory/weak_ptr.h"
  11 #include "components/proximity_auth/authenticator.h"
  12 #include "components/proximity_auth/connection_observer.h"
  13
  14 namespace base {
  15 class Timer;
  16 };
  17
  18 namespace proximity_auth {
  19
  20 class Connection;
  21 class SecureMessageDelegate;
  22
  23 // Authenticator implementation using the "device to device" protocol, which is
  24 // in turn built on top of the SecureMessage library.
  25 // This protocol contains the following steps (local device is the initiator):
  26 //   1. Both initiator and responder devices generate a temporary key pair for
  27 //      the session.
  28 //   2. Initiator sends [Hello] message to responder device, which contains the
  29 //      initiator's session public key.
  30 //   3. Responder responds with a [Responder Auth] message, containing its
  31 //      session public key and data that allows the initiator to assert the
  32 //      identity of the responder.
  33 //   4. Initiator sends [Initiator Auth] message, containing data allowing the
  34 //      responder to assert the identity of the initiator.
  35 //   5. Both devices derive a symmetric key by running a key agreement protocol
  36 //      session public keys they obtain from from the messages above. This
  37 //      symmetric key is used in the subsequent SecureContext.
  38 // The authentication protocol fails if any of the steps above fail.
  39 // This protocol requires exclusive use of the connection. No other message
  40 // should be sent or received while authentication is in progress.
  41 class DeviceToDeviceAuthenticator : public Authenticator,
  42                                     public ConnectionObserver {
  43  public:
  44   // Creates the instance:
  45   // |connection|: The connection to the remote device, which must be in a
  46   //     connected state. Not owned.
  47   // |account_id|: The canonical account id of the user who is the owner of both
  48   //     the local and remote devices.
  49   // |secure_message_delegate|: Handles the SecureMessage crypto operations.
  50   DeviceToDeviceAuthenticator(
  51       Connection* connection,
  52       const std::string& account_id,
  53       scoped_ptr<SecureMessageDelegate> secure_message_delegate);
  54
  55   ~DeviceToDeviceAuthenticator() override;
  56
  57   // Authenticator:
  58   void Authenticate(const AuthenticationCallback& callback) override;
  59
  60  protected:
  61   // Creates a base::Timer instance. Exposed for testing.
  62   virtual scoped_ptr<base::Timer> CreateTimer();
  63
  64  private:
  65   // The current state of the authentication flow.
  66   enum class State {
  67     NOT_STARTED,
  68     GENERATING_SESSION_KEYS,
  69     SENDING_HELLO,
  70     SENT_HELLO,
  71     RECEIVED_RESPONDER_AUTH,
  72     VALIDATED_RESPONDER_AUTH,
  73     SENT_INITIATOR_AUTH,
  74     AUTHENTICATION_SUCCESS,
  75     AUTHENTICATION_FAILURE,
  76   };
  77
  78   // Callback when the session key pair is generated.
  79   void OnKeyPairGenerated(const std::string& public_key,
  80                           const std::string& private_key);
  81
  82   // Callback when [Hello] is created.
  83   void OnHelloMessageCreated(const std::string& message);
  84
  85   // Callback when waiting for [Remote Auth] times out.
  86   void OnResponderAuthTimedOut();
  87
  88   // Callback for validating the received [Remote Auth].
  89   void OnResponderAuthValidated(bool validated,
  90                                 const std::string& session_symmetric_key);
  91
  92   // Callback when [Initiator Auth] is created.
  93   void OnInitiatorAuthCreated(const std::string& message);
  94
  95   // Callback when the session symmetric key is derived.
  96   void OnKeyDerived(const std::string& session_symmetric_key);
  97
  98   // Called when the authentication flow fails, and logs |error_message|. The
  99   // overloaded version specifies the Result to be reported;
 100   // otherwise, a FAILURE result will be reported.
 101   void Fail(const std::string& error_message);
 102   void Fail(const std::string& error_message, Result result);
 103
 104   // Called when the authentication flow succeeds.
 105   void Succeed();
 106
 107   // ConnectionObserver:
 108   void OnConnectionStatusChanged(Connection* connection,
 109                                  Connection::Status old_status,
 110                                  Connection::Status new_status) override;
 111   void OnMessageReceived(const Connection& connection,
 112                          const WireMessage& message) override;
 113   void OnSendCompleted(const Connection& connection,
 114                        const WireMessage& message,
 115                        bool success) override;
 116
 117   // The connection to the remote device. It is expected to be in the CONNECTED
 118   // state at all times during authentication.
 119   // Not owned, and must outlive this instance.
 120   Connection* const connection_;
 121
 122   // The account id of the user who owns the local and remote devices. This is
 123   // normally an email address, and should be canonicalized.
 124   const std::string account_id_;
 125
 126   // Handles SecureMessage crypto operations.
 127   scoped_ptr<SecureMessageDelegate> secure_message_delegate_;
 128
 129   // The current state in the authentication flow.
 130   State state_;
 131
 132   // Callback to invoke when authentication completes.
 133   AuthenticationCallback callback_;
 134
 135   // Used for timing out when waiting for [Remote Auth] from the remote device.
 136   scoped_ptr<base::Timer> timer_;
 137
 138   // The bytes of the [Hello] message sent to the remote device.
 139   std::string hello_message_;
 140
 141   // The bytes of the [Responder Auth] message received from the remote device.
 142   std::string responder_auth_message_;
 143
 144   // The private key generated for the session.
 145   std::string local_session_private_key_;
 146
 147   // The derived symmetric key for the session.
 148   std::string session_symmetric_key_;
 149
 150   base::WeakPtrFactory<DeviceToDeviceAuthenticator> weak_ptr_factory_;
 151
 152   DISALLOW_COPY_AND_ASSIGN(DeviceToDeviceAuthenticator);
 153 };
 154
 155 }  // namespace proximity_auth
 156
 157 #endif  // COMPONENTS_PROXIMITY_DEVICE_TO_DEVICE_AUTHENTICATOR_H