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
15namespace 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).
27class CHROMEOS_EXPORT EasyUnlockClient : public DBusClient {
28 public:
29  virtual ~EasyUnlockClient();
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  // Generates ECDSA key pair using P256 curve.
39  // The created keys should only be used with this client.
40  virtual void GenerateEcP256KeyPair(const KeyPairCallback& callback) = 0;
41
42  // Parameters used to create a secure message.
43  struct CreateSecureMessageOptions {
44    CreateSecureMessageOptions();
45    ~CreateSecureMessageOptions();
46
47    // The key used to sign, and if needed, encrypt the message. If encryption
48    // is required, the key must be symetric.
49    std::string key;
50
51    // Data associated with the message. The data will not actually be added to
52    // the message, but it will be used while signing the message (the receiver
53    // will use the same data to authenticate the signature).
54    std::string associated_data;
55
56    // Metadata added to the message header.
57    std::string public_metadata;
58
59    // The key id added to the message header. Has to be set if the message is
60    // signed with private asymetric key. This value is used by the receiver to
61    // identify the key that should be used to verify the signature.
62    std::string verification_key_id;
63
64    // Key id added to the message header. Used by the message receiver to
65    // identify the key that should be used to decrypt the message.
66    std::string decryption_key_id;
67
68    // The encryption algorithm to use for encrypting the message.
69    std::string encryption_type;
70
71    // The algorithm to use to sign the message.
72    std::string signature_type;
73
74   private:
75    DISALLOW_COPY_AND_ASSIGN(CreateSecureMessageOptions);
76  };
77
78  // Parameters used to unwrap a securemessage.
79  struct UnwrapSecureMessageOptions {
80    UnwrapSecureMessageOptions();
81    ~UnwrapSecureMessageOptions();
82
83    // The key used to authenticate message signature and, if needed, decrypt
84    // the message. If the message is encrypted, only symetric key can be used.
85    std::string key;
86
87    // Data associated with the message. Message authentication will succeed
88    // only if the message was created with the same associated data.
89    std::string associated_data;
90
91    // The encryption algorithm to use for decrypting the message.
92    std::string encryption_type;
93
94    // The algorithm that should be used to verify the message signature.
95    std::string signature_type;
96
97   private:
98    DISALLOW_COPY_AND_ASSIGN(UnwrapSecureMessageOptions);
99  };
100
101  // Given a private and a public key, creates a symetric secret key using
102  // EC Diffe-Hellman key exchange. The provided keys come from different
103  // asymetric key pairs, and are expected to be in the same format as the ones
104  // returned by |GenerateEcP256KeyAgreement|. Reversing key pairs from which
105  // private and public key come generates the same secret key.
106  virtual void PerformECDHKeyAgreement(const std::string& private_key,
107                                       const std::string& public_key,
108                                       const DataCallback& callback) = 0;
109
110  // Creates signed and, if specified, encrypted message in format used by Easy
111  // Unlock.
112  // |payload|: The cleartext message body.
113  // |options|: The message parameters used for creating the secure message.
114  // |callback|: Called with the created message. On failure, the message will
115  //     be empty.
116  virtual void CreateSecureMessage(const std::string& payload,
117                                   const CreateSecureMessageOptions& options,
118                                   const DataCallback& callback) = 0;
119
120  // Authenticates and, if specified, decrypts a secure message.
121  // |message|: The message to unwrap. It is in the same format as the message
122  //     returned by |CreateSecureMessage|.
123  // |options|: The parameters that should be used to unwrap the message.
124  // |callback|: Called with the cleartext message header and body in a signle
125  //     protobuf. If the message could not be authenticated or decrypted, it
126  //     will be called with an empty string.
127  virtual void UnwrapSecureMessage(const std::string& message,
128                                   const UnwrapSecureMessageOptions& options,
129                                   const DataCallback& callback) = 0;
130
131  // Factory function, creates a new instance and returns ownership.
132  // For normal usage, access the singleton via DBusThreadManager::Get().
133  static EasyUnlockClient* Create();
134
135 protected:
136  // Create() should be used instead.
137  EasyUnlockClient();
138
139 private:
140  DISALLOW_COPY_AND_ASSIGN(EasyUnlockClient);
141};
142
143}  // namespace chromeos
144
145#endif  // CHROMEOS_DBUS_EASY_UNLOCK_CLIENT_H_
146