OLD | NEW |
| (Empty) |
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_INTERNAL_API_PUBLIC_SYNC_ENCRYPTION_HANDLER_H_ | |
6 #define SYNC_INTERNAL_API_PUBLIC_SYNC_ENCRYPTION_HANDLER_H_ | |
7 | |
8 #include <string> | |
9 | |
10 #include "base/time/time.h" | |
11 #include "sync/base/sync_export.h" | |
12 #include "sync/internal_api/public/base/model_type.h" | |
13 #include "sync/protocol/sync.pb.h" | |
14 | |
15 namespace syncer { | |
16 | |
17 class Cryptographer; | |
18 | |
19 // Reasons due to which Cryptographer might require a passphrase. | |
20 enum PassphraseRequiredReason { | |
21 REASON_PASSPHRASE_NOT_REQUIRED = 0, // Initial value. | |
22 REASON_ENCRYPTION = 1, // The cryptographer requires a | |
23 // passphrase for its first attempt at | |
24 // encryption. Happens only during | |
25 // migration or upgrade. | |
26 REASON_DECRYPTION = 2, // The cryptographer requires a | |
27 // passphrase for its first attempt at | |
28 // decryption. | |
29 }; | |
30 | |
31 // The different states for the encryption passphrase. These control if and how | |
32 // the user should be prompted for a decryption passphrase. | |
33 // Do not re-order or delete these entries; they are used in a UMA histogram. | |
34 // Please edit SyncPassphraseType in histograms.xml if a value is added. | |
35 enum PassphraseType { | |
36 IMPLICIT_PASSPHRASE = 0, // GAIA-based passphrase (deprecated). | |
37 KEYSTORE_PASSPHRASE = 1, // Keystore passphrase. | |
38 FROZEN_IMPLICIT_PASSPHRASE = 2, // Frozen GAIA passphrase. | |
39 CUSTOM_PASSPHRASE = 3, // User-provided passphrase. | |
40 PASSPHRASE_TYPE_SIZE, // The size of this enum; keep last. | |
41 }; | |
42 | |
43 // Enum used to distinguish which bootstrap encryption token is being updated. | |
44 enum BootstrapTokenType { | |
45 PASSPHRASE_BOOTSTRAP_TOKEN, | |
46 KEYSTORE_BOOTSTRAP_TOKEN | |
47 }; | |
48 | |
49 // Sync's encryption handler. Handles tracking encrypted types, ensuring the | |
50 // cryptographer encrypts with the proper key and has the most recent keybag, | |
51 // and keeps the nigori node up to date. | |
52 // Implementations of this class must be assumed to be non-thread-safe. All | |
53 // methods must be invoked on the sync thread. | |
54 class SYNC_EXPORT SyncEncryptionHandler { | |
55 public: | |
56 class NigoriState; | |
57 | |
58 // All Observer methods are done synchronously from within a transaction and | |
59 // on the sync thread. | |
60 class SYNC_EXPORT Observer { | |
61 public: | |
62 Observer(); | |
63 | |
64 // Called when user interaction is required to obtain a valid passphrase. | |
65 // - If the passphrase is required for encryption, |reason| will be | |
66 // REASON_ENCRYPTION. | |
67 // - If the passphrase is required for the decryption of data that has | |
68 // already been encrypted, |reason| will be REASON_DECRYPTION. | |
69 // - If the passphrase is required because decryption failed, and a new | |
70 // passphrase is required, |reason| will be REASON_SET_PASSPHRASE_FAILED. | |
71 // | |
72 // |pending_keys| is a copy of the cryptographer's pending keys, that may be | |
73 // cached by the frontend for subsequent use by the UI. | |
74 virtual void OnPassphraseRequired( | |
75 PassphraseRequiredReason reason, | |
76 const sync_pb::EncryptedData& pending_keys) = 0; | |
77 // Called when the passphrase provided by the user has been accepted and is | |
78 // now used to encrypt sync data. | |
79 | |
80 virtual void OnPassphraseAccepted() = 0; | |
81 // |bootstrap_token| is an opaque base64 encoded representation of the key | |
82 // generated by the current passphrase, and is provided to the observer for | |
83 // persistence purposes and use in a future initialization of sync (e.g. | |
84 // after restart). The boostrap token will always be derived from the most | |
85 // recent GAIA password (for accounts with implicit passphrases), even if | |
86 // the data is still encrypted with an older GAIA password. For accounts | |
87 // with explicit passphrases, it will be the most recently seen custom | |
88 // passphrase. | |
89 virtual void OnBootstrapTokenUpdated( | |
90 const std::string& bootstrap_token, | |
91 BootstrapTokenType type) = 0; | |
92 | |
93 // Called when the set of encrypted types or the encrypt | |
94 // everything flag has been changed. Note that encryption isn't | |
95 // complete until the OnEncryptionComplete() notification has been | |
96 // sent (see below). | |
97 // | |
98 // |encrypted_types| will always be a superset of | |
99 // Cryptographer::SensitiveTypes(). If |encrypt_everything| is | |
100 // true, |encrypted_types| will be the set of all known types. | |
101 // | |
102 // Until this function is called, observers can assume that the | |
103 // set of encrypted types is Cryptographer::SensitiveTypes() and | |
104 // that the encrypt everything flag is false. | |
105 virtual void OnEncryptedTypesChanged( | |
106 ModelTypeSet encrypted_types, | |
107 bool encrypt_everything) = 0; | |
108 | |
109 // Called after we finish encrypting the current set of encrypted | |
110 // types. | |
111 virtual void OnEncryptionComplete() = 0; | |
112 | |
113 // The cryptographer has been updated. Listeners should check that their | |
114 // own state matches the cryptographer. | |
115 // Used primarily for debugging. | |
116 virtual void OnCryptographerStateChanged(Cryptographer* cryptographer) = 0; | |
117 | |
118 // The passphrase type has changed. |type| is the new type, | |
119 // |passphrase_time| is the time the passphrase was set (unset if |type| | |
120 // is KEYSTORE_PASSPHRASE or the passphrase was set before we started | |
121 // recording the time). | |
122 virtual void OnPassphraseTypeChanged(PassphraseType type, | |
123 base::Time passphrase_time) = 0; | |
124 | |
125 // The user has set a passphrase using this device. | |
126 // | |
127 // |nigori_state| can be used to restore nigori state across | |
128 // SyncEncryptionHandlerImpl lifetimes. See also SyncEncryptionHandlerImpl's | |
129 // RestoredNigori method. | |
130 virtual void OnLocalSetPassphraseEncryption( | |
131 const NigoriState& nigori_state) = 0; | |
132 | |
133 protected: | |
134 virtual ~Observer(); | |
135 }; | |
136 | |
137 class SYNC_EXPORT NigoriState { | |
138 public: | |
139 NigoriState() {} | |
140 sync_pb::NigoriSpecifics nigori_specifics; | |
141 }; | |
142 | |
143 SyncEncryptionHandler(); | |
144 virtual ~SyncEncryptionHandler(); | |
145 | |
146 // Add/Remove SyncEncryptionHandler::Observers. | |
147 virtual void AddObserver(Observer* observer) = 0; | |
148 virtual void RemoveObserver(Observer* observer) = 0; | |
149 | |
150 // Reads the nigori node, updates internal state as needed, and, if an | |
151 // empty/stale nigori node is detected, overwrites the existing | |
152 // nigori node. Upon completion, if the cryptographer is still ready | |
153 // attempts to re-encrypt all sync data. | |
154 // Note: This method is expensive (it iterates through all encrypted types), | |
155 // so should only be used sparingly (e.g. on startup). | |
156 virtual void Init() = 0; | |
157 | |
158 // Attempts to re-encrypt encrypted data types using the passphrase provided. | |
159 // Notifies observers of the result of the operation via OnPassphraseAccepted | |
160 // or OnPassphraseRequired, updates the nigori node, and does re-encryption as | |
161 // appropriate. If an explicit password has been set previously, we drop | |
162 // subsequent requests to set a passphrase. If the cryptographer has pending | |
163 // keys, and a new implicit passphrase is provided, we try decrypting the | |
164 // pending keys with it, and if that fails, we cache the passphrase for | |
165 // re-encryption once the pending keys are decrypted. | |
166 virtual void SetEncryptionPassphrase(const std::string& passphrase, | |
167 bool is_explicit) = 0; | |
168 | |
169 // Provides a passphrase for decrypting the user's existing sync data. | |
170 // Notifies observers of the result of the operation via OnPassphraseAccepted | |
171 // or OnPassphraseRequired, updates the nigori node, and does re-encryption as | |
172 // appropriate if there is a previously cached encryption passphrase. It is an | |
173 // error to call this when we don't have pending keys. | |
174 virtual void SetDecryptionPassphrase(const std::string& passphrase) = 0; | |
175 | |
176 // Enables encryption of all datatypes. | |
177 virtual void EnableEncryptEverything() = 0; | |
178 | |
179 // Whether encryption of all datatypes is enabled. If false, only sensitive | |
180 // types are encrypted. | |
181 virtual bool IsEncryptEverythingEnabled() const = 0; | |
182 | |
183 // Returns the current state of the passphrase needed to decrypt the | |
184 // bag of encryption keys in the nigori node. | |
185 virtual PassphraseType GetPassphraseType() const = 0; | |
186 | |
187 // The set of types that are always encrypted. | |
188 static ModelTypeSet SensitiveTypes(); | |
189 }; | |
190 | |
191 } // namespace syncer | |
192 | |
193 #endif // SYNC_INTERNAL_API_PUBLIC_SYNC_ENCRYPTION_HANDLER_H_ | |
OLD | NEW |