chromeos/dbus/easy_unlock_client.h

   1 // Copyright 2014 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 CHROMEOS_DBUS_EASY_UNLOCK_CLIENT_H_
   6 #define CHROMEOS_DBUS_EASY_UNLOCK_CLIENT_H_
   7
   8 #include <string>
   9
  10 #include "base/basictypes.h"
  11 #include "base/callback.h"
  12 #include "chromeos/chromeos_export.h"
  13 #include "chromeos/dbus/dbus_client.h"
  14
  15 namespace chromeos {
  16
  17 // Client for calling EasyUnlock dbus service. The service provides
  18 // methods used by Easy Unlock for establishing secure communication channel
  19 // over (unsecure) bluetooth with devices registered to unlock ChromeOS.
  20 // Ideally, this would be done in Chrome, but unfortunatelly, the library used
  21 // for wrapping and unwrapping messages sent over the communication channel
  22 // depends on OpenSSL for encryption, which is not currently available in
  23 // Chrome. To work around this, the message processing will be done in ChromeOS,
  24 // where OpenSSL is already supported.
  25 // TODO(tbarzic): Get rid of this client when Chrome switches from NSS to
  26 // OpenSSL (http://crbug.com/338888).
  27 class CHROMEOS_EXPORT EasyUnlockClient : public DBusClient {
  28  public:
  29   ~EasyUnlockClient() override;
  30
  31   typedef base::Callback<void(const std::string& data)> DataCallback;
  32
  33   // Callback for |GenerateEcP256KeyPair|. Carries the generated keys.
  34   typedef base::Callback<void(const std::string& private_key,
  35                               const std::string& public_key)>
  36       KeyPairCallback;
  37
  38   // Parameters used to create a secure message.
  39   struct CreateSecureMessageOptions {
  40     CreateSecureMessageOptions();
  41     ~CreateSecureMessageOptions();
  42
  43     // The key used to sign, and if needed, encrypt the message. If encryption
  44     // is required, the key must be symetric.
  45     std::string key;
  46
  47     // Data associated with the message. The data will not actually be added to
  48     // the message, but it will be used while signing the message (the receiver
  49     // will use the same data to authenticate the signature).
  50     std::string associated_data;
  51
  52     // Metadata added to the message header.
  53     std::string public_metadata;
  54
  55     // The key id added to the message header. Has to be set if the message is
  56     // signed with private asymetric key. This value is used by the receiver to
  57     // identify the key that should be used to verify the signature.
  58     std::string verification_key_id;
  59
  60     // Key id added to the message header. Used by the message receiver to
  61     // identify the key that should be used to decrypt the message.
  62     std::string decryption_key_id;
  63
  64     // The encryption algorithm to use for encrypting the message.
  65     std::string encryption_type;
  66
  67     // The algorithm to use to sign the message.
  68     std::string signature_type;
  69
  70    private:
  71     DISALLOW_COPY_AND_ASSIGN(CreateSecureMessageOptions);
  72   };
  73
  74   // Parameters used to unwrap a securemessage.
  75   struct UnwrapSecureMessageOptions {
  76     UnwrapSecureMessageOptions();
  77     ~UnwrapSecureMessageOptions();
  78
  79     // The key used to authenticate message signature and, if needed, decrypt
  80     // the message. If the message is encrypted, only symetric key can be used.
  81     std::string key;
  82
  83     // Data associated with the message. Message authentication will succeed
  84     // only if the message was created with the same associated data.
  85     std::string associated_data;
  86
  87     // The encryption algorithm to use for decrypting the message.
  88     std::string encryption_type;
  89
  90     // The algorithm that should be used to verify the message signature.
  91     std::string signature_type;
  92
  93    private:
  94     DISALLOW_COPY_AND_ASSIGN(UnwrapSecureMessageOptions);
  95   };
  96
  97   // Generates ECDSA key pair using P256 curve.
  98   // The created keys should only be used with this client.
  99   virtual void GenerateEcP256KeyPair(const KeyPairCallback& callback) = 0;
 100
 101   // Converts public key bytes to format used by Easy Unlock.
 102   // |key_algorithm|: The asymmetric encryption algorithm with which the key is
 103   //     used.
 104   // |public_key|: The key that should be wrapped.
 105   // |callback|: The callback carrying the wrapped key.
 106   virtual void WrapPublicKey(const std::string& key_algorithm,
 107                              const std::string& public_key,
 108                              const DataCallback& callback) = 0;
 109
 110   // Given a private and a public key, creates a symetric secret key using
 111   // EC Diffe-Hellman key exchange. The provided keys come from different
 112   // asymetric key pairs, and are expected to be in the same format as the ones
 113   // returned by |GenerateEcP256KeyAgreement|. Reversing key pairs from which
 114   // private and public key come generates the same secret key.
 115   virtual void PerformECDHKeyAgreement(const std::string& private_key,
 116                                        const std::string& public_key,
 117                                        const DataCallback& callback) = 0;
 118
 119   // Creates signed and, if specified, encrypted message in format used by Easy
 120   // Unlock.
 121   // |payload|: The cleartext message body.
 122   // |options|: The message parameters used for creating the secure message.
 123   // |callback|: Called with the created message. On failure, the message will
 124   //     be empty.
 125   virtual void CreateSecureMessage(const std::string& payload,
 126                                    const CreateSecureMessageOptions& options,
 127                                    const DataCallback& callback) = 0;
 128
 129   // Authenticates and, if specified, decrypts a secure message.
 130   // |message|: The message to unwrap. It is in the same format as the message
 131   //     returned by |CreateSecureMessage|.
 132   // |options|: The parameters that should be used to unwrap the message.
 133   // |callback|: Called with the cleartext message header and body in a signle
 134   //     protobuf. If the message could not be authenticated or decrypted, it
 135   //     will be called with an empty string.
 136   virtual void UnwrapSecureMessage(const std::string& message,
 137                                    const UnwrapSecureMessageOptions& options,
 138                                    const DataCallback& callback) = 0;
 139
 140   // Factory function, creates a new instance and returns ownership.
 141   // For normal usage, access the singleton via DBusThreadManager::Get().
 142   static EasyUnlockClient* Create();
 143
 144  protected:
 145   // Create() should be used instead.
 146   EasyUnlockClient();
 147
 148  private:
 149   DISALLOW_COPY_AND_ASSIGN(EasyUnlockClient);
 150 };
 151
 152 }  // namespace chromeos
 153
 154 #endif  // CHROMEOS_DBUS_EASY_UNLOCK_CLIENT_H_