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.
5 #ifndef SYNC_INTERNAL_API_PUBLIC_SYNC_ENCRYPTION_HANDLER_H_
6 #define SYNC_INTERNAL_API_PUBLIC_SYNC_ENCRYPTION_HANDLER_H_
10 #include "base/time/time.h"
11 #include "sync/base/sync_export.h"
12 #include "sync/internal_api/public/base/model_type.h"
22 // Reasons due to which Cryptographer might require a passphrase.
23 enum PassphraseRequiredReason {
24 REASON_PASSPHRASE_NOT_REQUIRED = 0, // Initial value.
25 REASON_ENCRYPTION = 1, // The cryptographer requires a
26 // passphrase for its first attempt at
27 // encryption. Happens only during
28 // migration or upgrade.
29 REASON_DECRYPTION = 2, // The cryptographer requires a
30 // passphrase for its first attempt at
34 // The different states for the encryption passphrase. These control if and how
35 // the user should be prompted for a decryption passphrase.
37 IMPLICIT_PASSPHRASE = 0, // GAIA-based passphrase (deprecated).
38 KEYSTORE_PASSPHRASE = 1, // Keystore passphrase.
39 FROZEN_IMPLICIT_PASSPHRASE = 2, // Frozen GAIA passphrase.
40 CUSTOM_PASSPHRASE = 3, // User-provided passphrase.
43 // Enum used to distinguish which bootstrap encryption token is being updated.
44 enum BootstrapTokenType {
45 PASSPHRASE_BOOTSTRAP_TOKEN,
46 KEYSTORE_BOOTSTRAP_TOKEN
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 {
56 // All Observer methods are done synchronously from within a transaction and
57 // on the sync thread.
58 class SYNC_EXPORT Observer {
62 // Called when user interaction is required to obtain a valid passphrase.
63 // - If the passphrase is required for encryption, |reason| will be
65 // - If the passphrase is required for the decryption of data that has
66 // already been encrypted, |reason| will be REASON_DECRYPTION.
67 // - If the passphrase is required because decryption failed, and a new
68 // passphrase is required, |reason| will be REASON_SET_PASSPHRASE_FAILED.
70 // |pending_keys| is a copy of the cryptographer's pending keys, that may be
71 // cached by the frontend for subsequent use by the UI.
72 virtual void OnPassphraseRequired(
73 PassphraseRequiredReason reason,
74 const sync_pb::EncryptedData& pending_keys) = 0;
75 // Called when the passphrase provided by the user has been accepted and is
76 // now used to encrypt sync data.
78 virtual void OnPassphraseAccepted() = 0;
79 // |bootstrap_token| is an opaque base64 encoded representation of the key
80 // generated by the current passphrase, and is provided to the observer for
81 // persistence purposes and use in a future initialization of sync (e.g.
82 // after restart). The boostrap token will always be derived from the most
83 // recent GAIA password (for accounts with implicit passphrases), even if
84 // the data is still encrypted with an older GAIA password. For accounts
85 // with explicit passphrases, it will be the most recently seen custom
87 virtual void OnBootstrapTokenUpdated(
88 const std::string& bootstrap_token,
89 BootstrapTokenType type) = 0;
91 // Called when the set of encrypted types or the encrypt
92 // everything flag has been changed. Note that encryption isn't
93 // complete until the OnEncryptionComplete() notification has been
96 // |encrypted_types| will always be a superset of
97 // Cryptographer::SensitiveTypes(). If |encrypt_everything| is
98 // true, |encrypted_types| will be the set of all known types.
100 // Until this function is called, observers can assume that the
101 // set of encrypted types is Cryptographer::SensitiveTypes() and
102 // that the encrypt everything flag is false.
103 virtual void OnEncryptedTypesChanged(
104 ModelTypeSet encrypted_types,
105 bool encrypt_everything) = 0;
107 // Called after we finish encrypting the current set of encrypted
109 virtual void OnEncryptionComplete() = 0;
111 // The cryptographer has been updated. Listeners should check that their
112 // own state matches the cryptographer.
113 // Used primarily for debugging.
114 virtual void OnCryptographerStateChanged(Cryptographer* cryptographer) = 0;
116 // The passphrase type has changed. |type| is the new type,
117 // |passphrase_time| is the time the passphrase was set (unset if |type|
118 // is KEYSTORE_PASSPHRASE or the passphrase was set before we started
119 // recording the time).
120 virtual void OnPassphraseTypeChanged(PassphraseType type,
121 base::Time passphrase_time) = 0;
127 SyncEncryptionHandler();
128 virtual ~SyncEncryptionHandler();
130 // Add/Remove SyncEncryptionHandler::Observers.
131 virtual void AddObserver(Observer* observer) = 0;
132 virtual void RemoveObserver(Observer* observer) = 0;
134 // Reads the nigori node, updates internal state as needed, and, if an
135 // empty/stale nigori node is detected, overwrites the existing
136 // nigori node. Upon completion, if the cryptographer is still ready
137 // attempts to re-encrypt all sync data.
138 // Note: This method is expensive (it iterates through all encrypted types),
139 // so should only be used sparingly (e.g. on startup).
140 virtual void Init() = 0;
142 // Attempts to re-encrypt encrypted data types using the passphrase provided.
143 // Notifies observers of the result of the operation via OnPassphraseAccepted
144 // or OnPassphraseRequired, updates the nigori node, and does re-encryption as
145 // appropriate. If an explicit password has been set previously, we drop
146 // subsequent requests to set a passphrase. If the cryptographer has pending
147 // keys, and a new implicit passphrase is provided, we try decrypting the
148 // pending keys with it, and if that fails, we cache the passphrase for
149 // re-encryption once the pending keys are decrypted.
150 virtual void SetEncryptionPassphrase(const std::string& passphrase,
151 bool is_explicit) = 0;
153 // Provides a passphrase for decrypting the user's existing sync data.
154 // Notifies observers of the result of the operation via OnPassphraseAccepted
155 // or OnPassphraseRequired, updates the nigori node, and does re-encryption as
156 // appropriate if there is a previously cached encryption passphrase. It is an
157 // error to call this when we don't have pending keys.
158 virtual void SetDecryptionPassphrase(const std::string& passphrase) = 0;
160 // Enables encryption of all datatypes.
161 virtual void EnableEncryptEverything() = 0;
163 // Whether encryption of all datatypes is enabled. If false, only sensitive
164 // types are encrypted.
165 virtual bool EncryptEverythingEnabled() const = 0;
167 // Returns the current state of the passphrase needed to decrypt the
168 // bag of encryption keys in the nigori node.
169 virtual PassphraseType GetPassphraseType() const = 0;
171 // The set of types that are always encrypted.
172 static ModelTypeSet SensitiveTypes();
175 } // namespace syncer
177 #endif // SYNC_INTERNAL_API_PUBLIC_SYNC_ENCRYPTION_HANDLER_H_