1 // Copyright 2012 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 SYNC_UTIL_CRYPTOGRAPHER_H_ 6 #define SYNC_UTIL_CRYPTOGRAPHER_H_ 7 8 #include <map> 9 #include <string> 10 11 #include "base/gtest_prod_util.h" 12 #include "base/memory/linked_ptr.h" 13 #include "base/memory/scoped_ptr.h" 14 #include "sync/base/sync_export.h" 15 #include "sync/protocol/encryption.pb.h" 16 #include "sync/util/nigori.h" 17 18 namespace sync_pb { 19 class NigoriKeyBag; 20 class NigoriSpecifics; 21 } 22 23 namespace syncer { 24 25 class Encryptor; 26 27 SYNC_EXPORT_PRIVATE extern const char kNigoriTag[]; 28 29 // The parameters used to initialize a Nigori instance. 30 struct KeyParams { 31 std::string hostname; 32 std::string username; 33 std::string password; 34 }; 35 36 // This class manages the Nigori objects used to encrypt and decrypt sensitive 37 // sync data (eg. passwords). Each Nigori object knows how to handle data 38 // protected with a particular passphrase. 39 // 40 // Whenever an update to the Nigori sync node is received from the server, 41 // SetPendingKeys should be called with the encrypted contents of that node. 42 // Most likely, an updated Nigori node means that a new passphrase has been set 43 // and that future node updates won't be decryptable. To remedy this, the user 44 // should be prompted for the new passphrase and DecryptPendingKeys be called. 45 // 46 // Whenever a update to an encrypted node is received from the server, 47 // CanDecrypt should be used to verify whether the Cryptographer can decrypt 48 // that node. If it cannot, then the application of that update should be 49 // delayed until after it can be decrypted. 50 class SYNC_EXPORT Cryptographer { 51 public: 52 // Does not take ownership of |encryptor|. 53 explicit Cryptographer(Encryptor* encryptor); 54 explicit Cryptographer(const Cryptographer& other); 55 ~Cryptographer(); 56 57 // |restored_bootstrap_token| can be provided via this method to bootstrap 58 // Cryptographer instance into the ready state (is_ready will be true). 59 // It must be a string that was previously built by the 60 // GetSerializedBootstrapToken function. It is possible that the token is no 61 // longer valid (due to server key change), in which case the normal 62 // decryption code paths will fail and the user will need to provide a new 63 // passphrase. 64 // It is an error to call this if is_ready() == true, though it is fair to 65 // never call Bootstrap at all. 66 void Bootstrap(const std::string& restored_bootstrap_token); 67 68 // Returns whether we can decrypt |encrypted| using the keys we currently know 69 // about. 70 bool CanDecrypt(const sync_pb::EncryptedData& encrypted) const; 71 72 // Returns whether |encrypted| can be decrypted using the default encryption 73 // key. 74 bool CanDecryptUsingDefaultKey(const sync_pb::EncryptedData& encrypted) const; 75 76 // Encrypts |message| into |encrypted|. Does not overwrite |encrypted| if 77 // |message| already matches the decrypted data within |encrypted| and 78 // |encrypted| was encrypted with the current default key. This avoids 79 // unnecessarily modifying |encrypted| if the change had no practical effect. 80 // Returns true unless encryption fails or |message| isn't valid (e.g. a 81 // required field isn't set). 82 bool Encrypt(const ::google::protobuf::MessageLite& message, 83 sync_pb::EncryptedData* encrypted) const; 84 85 // Encrypted |serialized| into |encrypted|. Does not overwrite |encrypted| if 86 // |message| already matches the decrypted data within |encrypted| and 87 // |encrypted| was encrypted with the current default key. This avoids 88 // unnecessarily modifying |encrypted| if the change had no practical effect. 89 // Returns true unless encryption fails or |message| isn't valid (e.g. a 90 // required field isn't set). 91 bool EncryptString(const std::string& serialized, 92 sync_pb::EncryptedData* encrypted) const; 93 94 // Decrypts |encrypted| into |message|. Returns true unless decryption fails, 95 // or |message| fails to parse the decrypted data. 96 bool Decrypt(const sync_pb::EncryptedData& encrypted, 97 ::google::protobuf::MessageLite* message) const; 98 99 // Decrypts |encrypted| and returns plaintext decrypted data. If decryption 100 // fails, returns empty string. 101 std::string DecryptToString(const sync_pb::EncryptedData& encrypted) const; 102 103 // Encrypts the set of currently known keys into |encrypted|. Returns true if 104 // successful. 105 bool GetKeys(sync_pb::EncryptedData* encrypted) const; 106 107 // Creates a new Nigori instance using |params|. If successful, |params| will 108 // become the default encryption key and be used for all future calls to 109 // Encrypt. 110 // Will decrypt the pending keys and install them if possible (pending key 111 // will not overwrite default). 112 bool AddKey(const KeyParams& params); 113 114 // Same as AddKey(..), but builds the new Nigori from a previously persisted 115 // bootstrap token. This can be useful when consuming a bootstrap token 116 // with a cryptographer that has already been initialized. 117 // Updates the default key. 118 // Will decrypt the pending keys and install them if possible (pending key 119 // will not overwrite default). 120 bool AddKeyFromBootstrapToken(const std::string restored_bootstrap_token); 121 122 // Creates a new Nigori instance using |params|. If successful, |params| 123 // will be added to the nigori keybag, but will not be the default encryption 124 // key (default_nigori_ will remain the same). 125 // Prereq: is_initialized() must be true. 126 // Will decrypt the pending keys and install them if possible (pending key 127 // will become the new default). 128 bool AddNonDefaultKey(const KeyParams& params); 129 130 // Decrypts |encrypted| and uses its contents to initialize Nigori instances. 131 // Returns true unless decryption of |encrypted| fails. The caller is 132 // responsible for checking that CanDecrypt(encrypted) == true. 133 // Does not modify the default key. 134 void InstallKeys(const sync_pb::EncryptedData& encrypted); 135 136 // Makes a local copy of |encrypted| to later be decrypted by 137 // DecryptPendingKeys. This should only be used if CanDecrypt(encrypted) == 138 // false. 139 void SetPendingKeys(const sync_pb::EncryptedData& encrypted); 140 141 // Makes |pending_keys_| available to callers that may want to cache its 142 // value for later use on the UI thread. It is illegal to call this if the 143 // cryptographer has no pending keys. Like other calls that access the 144 // cryptographer, this method must be called from within a transaction. 145 const sync_pb::EncryptedData& GetPendingKeys() const; 146 147 // Attempts to decrypt the set of keys that was copied in the previous call to 148 // SetPendingKeys using |params|. Returns true if the pending keys were 149 // successfully decrypted and installed. If successful, the default key 150 // is updated. 151 bool DecryptPendingKeys(const KeyParams& params); 152 153 // Sets the default key to the nigori with name |key_name|. |key_name| must 154 // correspond to a nigori that has already been installed into the keybag. 155 void SetDefaultKey(const std::string& key_name); 156 157 bool is_initialized() const { 158 return !nigoris_.empty() && !default_nigori_name_.empty(); 159 } 160 161 // Returns whether this Cryptographer is ready to encrypt and decrypt data. 162 bool is_ready() const { 163 return is_initialized() && !has_pending_keys(); 164 } 165 166 // Returns whether there is a pending set of keys that needs to be decrypted. 167 bool has_pending_keys() const { return NULL != pending_keys_.get(); } 168 169 // Obtain a token that can be provided on construction to a future 170 // Cryptographer instance to bootstrap itself. Returns false if such a token 171 // can't be created (i.e. if this Cryptograhper doesn't have valid keys). 172 bool GetBootstrapToken(std::string* token) const; 173 174 Encryptor* encryptor() const { return encryptor_; } 175 176 // Returns true if |keybag| is decryptable and either is a subset of nigoris_ 177 // and/or has a different default key. 178 bool KeybagIsStale(const sync_pb::EncryptedData& keybag) const; 179 180 // Returns the name of the Nigori key currently used for encryption. 181 std::string GetDefaultNigoriKeyName() const; 182 183 // Returns a serialized sync_pb::NigoriKey version of current default 184 // encryption key. 185 std::string GetDefaultNigoriKeyData() const; 186 187 // Generates a new Nigori from |serialized_nigori_key|, and if successful 188 // installs the new nigori as the default key. 189 bool ImportNigoriKey(const std::string serialized_nigori_key); 190 191 private: 192 typedef std::map<std::string, linked_ptr<const Nigori> > NigoriMap; 193 194 // Helper method to instantiate Nigori instances for each set of key 195 // parameters in |bag|. 196 // Does not update the default nigori. 197 void InstallKeyBag(const sync_pb::NigoriKeyBag& bag); 198 199 // Helper method to add a nigori to the keybag, optionally making it the 200 // default as well. 201 bool AddKeyImpl(scoped_ptr<Nigori> nigori, bool set_as_default); 202 203 // Helper to unencrypt a bootstrap token into a serialized sync_pb::NigoriKey. 204 std::string UnpackBootstrapToken(const std::string& token) const; 205 206 Encryptor* const encryptor_; 207 208 // The Nigoris we know about, mapped by key name. 209 NigoriMap nigoris_; 210 211 // The key name associated with the default nigori. If non-empty, must 212 // correspond to a nigori within |nigoris_|. 213 std::string default_nigori_name_; 214 215 scoped_ptr<sync_pb::EncryptedData> pending_keys_; 216 217 DISALLOW_ASSIGN(Cryptographer); 218 }; 219 220 } // namespace syncer 221 222 #endif // SYNC_UTIL_CRYPTOGRAPHER_H_ 223