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 COMPONENTS_SYNC_ENGINE_SYNC_ENCRYPTION_HANDLER_H_
6 #define COMPONENTS_SYNC_ENGINE_SYNC_ENCRYPTION_HANDLER_H_
7 
8 #include <string>
9 #include <vector>
10 
11 #include "base/time/time.h"
12 #include "components/sync/base/model_type.h"
13 #include "components/sync/base/passphrase_enums.h"
14 #include "components/sync/nigori/nigori.h"
15 #include "components/sync/protocol/sync.pb.h"
16 
17 namespace syncer {
18 
19 class Cryptographer;
20 class KeystoreKeysHandler;
21 enum class PassphraseType;
22 
23 // Enum used to distinguish which bootstrap encryption token is being updated.
24 enum BootstrapTokenType {
25   PASSPHRASE_BOOTSTRAP_TOKEN,
26   KEYSTORE_BOOTSTRAP_TOKEN
27 };
28 
29 // Sync's encryption handler. Handles tracking encrypted types, ensuring the
30 // cryptographer encrypts with the proper key and has the most recent keybag,
31 // and keeps the nigori node up to date.
32 // Implementations of this class must be assumed to be non-thread-safe. All
33 // methods must be invoked on the sync thread.
34 // TODO(crbug.com/1010397): Rename this class.
35 class SyncEncryptionHandler {
36  public:
37   static constexpr PassphraseType kInitialPassphraseType =
38       PassphraseType::kImplicitPassphrase;
39 
40   // All Observer methods are done synchronously from within a transaction and
41   // on the sync thread.
42   class Observer {
43    public:
44     Observer() = default;
45     virtual ~Observer() = default;
46 
47     // Called when user interaction is required to obtain a valid passphrase for
48     // decryption.
49     // |key_derivation_params| are the parameters that should be used to obtain
50     // the key from the passphrase.
51     // |pending_keys| is a copy of the cryptographer's pending keys, that may be
52     // cached by the frontend for subsequent use by the UI.
53     virtual void OnPassphraseRequired(
54         const KeyDerivationParams& key_derivation_params,
55         const sync_pb::EncryptedData& pending_keys) = 0;
56 
57     // Called when the passphrase provided by the user has been accepted and is
58     // now used to encrypt sync data.
59     virtual void OnPassphraseAccepted() = 0;
60 
61     // Called when decryption keys are required in order to decrypt pending
62     // Nigori keys and resume sync, for the TRUSTED_VAULT_PASSPHRASE case. This
63     // can be resolved by calling AddTrustedVaultDecryptionKeys() with the
64     // appropriate keys.
65     virtual void OnTrustedVaultKeyRequired() = 0;
66 
67     // Called when the keys provided via AddTrustedVaultDecryptionKeys have been
68     // accepted and there are no longer pending keys.
69     virtual void OnTrustedVaultKeyAccepted() = 0;
70 
71     // |bootstrap_token| is an opaque base64 encoded representation of the key
72     // generated by the current passphrase, and is provided to the observer for
73     // persistence purposes and use in a future initialization of sync (e.g.
74     // after restart). The boostrap token will always be derived from the most
75     // recent GAIA password (for accounts with implicit passphrases), even if
76     // the data is still encrypted with an older GAIA password. For accounts
77     // with explicit passphrases, it will be the most recently seen custom
78     // passphrase.
79     virtual void OnBootstrapTokenUpdated(const std::string& bootstrap_token,
80                                          BootstrapTokenType type) = 0;
81 
82     // Called when the set of encrypted types or the encrypt
83     // everything flag has been changed. Note that this doesn't imply the
84     // encryption is complete.
85     //
86     // |encrypted_types| will always be a superset of
87     // AlwaysEncryptedUserTypes().  If |encrypt_everything| is
88     // true, |encrypted_types| will be the set of all known types.
89     //
90     // Until this function is called, observers can assume that the
91     // set of encrypted types is AlwaysEncryptedUserTypes() and that the
92     // encrypt everything flag is false.
93     virtual void OnEncryptedTypesChanged(ModelTypeSet encrypted_types,
94                                          bool encrypt_everything) = 0;
95 
96     // The cryptographer has been updated and/or the presence of pending keys
97     // changed.
98     virtual void OnCryptographerStateChanged(Cryptographer* cryptographer,
99                                              bool has_pending_keys) = 0;
100 
101     // The passphrase type has changed. |type| is the new type,
102     // |passphrase_time| is the time the passphrase was set (unset if |type|
103     // is KEYSTORE_PASSPHRASE or the passphrase was set before we started
104     // recording the time).
105     virtual void OnPassphraseTypeChanged(PassphraseType type,
106                                          base::Time passphrase_time) = 0;
107   };
108 
109   SyncEncryptionHandler() = default;
110   virtual ~SyncEncryptionHandler() = default;
111 
112   // Add/Remove SyncEncryptionHandler::Observers.
113   virtual void AddObserver(Observer* observer) = 0;
114   virtual void RemoveObserver(Observer* observer) = 0;
115 
116   // Reads the nigori node, updates internal state as needed, and, if an
117   // empty/stale nigori node is detected, overwrites the existing
118   // nigori node. Upon completion, if the cryptographer is still ready
119   // attempts to re-encrypt all sync data. Returns false in case of error.
120   // Note: This method is expensive (it iterates through all encrypted types),
121   // so should only be used sparingly (e.g. on startup).
122   // TODO(crbug.com/): Rename to something like NotifyStateToObservers() or
123   // even delete this API altogether.
124   virtual bool Init() = 0;
125 
126   // Attempts to re-encrypt encrypted data types using the passphrase provided.
127   // Notifies observers of the result of the operation via OnPassphraseAccepted
128   // or OnPassphraseRequired, updates the nigori node, and does re-encryption as
129   // appropriate. If an explicit password has been set previously, we drop
130   // subsequent requests to set a passphrase. |passphrase| shouldn't be empty.
131   virtual void SetEncryptionPassphrase(const std::string& passphrase) = 0;
132 
133   // Provides a passphrase for decrypting the user's existing sync data.
134   // Notifies observers of the result of the operation via OnPassphraseAccepted
135   // or OnPassphraseRequired, updates the nigori node, and does re-encryption as
136   // appropriate if there is a previously cached encryption passphrase. It is an
137   // error to call this when we don't have pending keys. |passphrase| shouldn't
138   // be empty.
139   virtual void SetDecryptionPassphrase(const std::string& passphrase) = 0;
140 
141   // Analogous to SetDecryptionPassphrase but specifically for
142   // TRUSTED_VAULT_PASSPHRASE: it provides new decryption keys that could
143   // allow decrypting pending Nigori keys. Notifies observers of the result of
144   // the operation via OnTrustedVaultKeyAccepted if the provided keys
145   // successfully decrypted pending keys.
146   virtual void AddTrustedVaultDecryptionKeys(
147       const std::vector<std::vector<uint8_t>>& keys) = 0;
148 
149   // Returns the time when Nigori was migrated to keystore or when it was
150   // initialized in case it happens after migration was introduced. Returns
151   // base::Time() in case migration isn't completed.
152   virtual base::Time GetKeystoreMigrationTime() const = 0;
153 
154   // Returns KeystoreKeysHandler, allowing to pass new keystore keys and to
155   // check whether keystore keys need to be requested from the server.
156   virtual KeystoreKeysHandler* GetKeystoreKeysHandler() = 0;
157 };
158 
159 }  // namespace syncer
160 
161 #endif  // COMPONENTS_SYNC_ENGINE_SYNC_ENCRYPTION_HANDLER_H_
162