sync/internal_api/public/sync_encryption_handler.h

   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 // Whether we clear server data when a user enables passphrase encryption.
  50 enum PassphraseTransitionClearDataOption {
  51   PASSPHRASE_TRANSITION_DO_NOT_CLEAR_DATA,
  52   PASSPHRASE_TRANSITION_CLEAR_DATA
  53 };
  54
  55 // Sync's encryption handler. Handles tracking encrypted types, ensuring the
  56 // cryptographer encrypts with the proper key and has the most recent keybag,
  57 // and keeps the nigori node up to date.
  58 // Implementations of this class must be assumed to be non-thread-safe. All
  59 // methods must be invoked on the sync thread.
  60 class SYNC_EXPORT SyncEncryptionHandler {
  61  public:
  62   class NigoriState;
  63
  64   // All Observer methods are done synchronously from within a transaction and
  65   // on the sync thread.
  66   class SYNC_EXPORT Observer {
  67    public:
  68     Observer();
  69
  70     // Called when user interaction is required to obtain a valid passphrase.
  71     // - If the passphrase is required for encryption, |reason| will be
  72     //   REASON_ENCRYPTION.
  73     // - If the passphrase is required for the decryption of data that has
  74     //   already been encrypted, |reason| will be REASON_DECRYPTION.
  75     // - If the passphrase is required because decryption failed, and a new
  76     //   passphrase is required, |reason| will be REASON_SET_PASSPHRASE_FAILED.
  77     //
  78     // |pending_keys| is a copy of the cryptographer's pending keys, that may be
  79     // cached by the frontend for subsequent use by the UI.
  80     virtual void OnPassphraseRequired(
  81         PassphraseRequiredReason reason,
  82         const sync_pb::EncryptedData& pending_keys) = 0;
  83     // Called when the passphrase provided by the user has been accepted and is
  84     // now used to encrypt sync data.
  85
  86     virtual void OnPassphraseAccepted() = 0;
  87     // |bootstrap_token| is an opaque base64 encoded representation of the key
  88     // generated by the current passphrase, and is provided to the observer for
  89     // persistence purposes and use in a future initialization of sync (e.g.
  90     // after restart). The boostrap token will always be derived from the most
  91     // recent GAIA password (for accounts with implicit passphrases), even if
  92     // the data is still encrypted with an older GAIA password. For accounts
  93     // with explicit passphrases, it will be the most recently seen custom
  94     // passphrase.
  95     virtual void OnBootstrapTokenUpdated(
  96         const std::string& bootstrap_token,
  97         BootstrapTokenType type) = 0;
  98
  99     // Called when the set of encrypted types or the encrypt
 100     // everything flag has been changed.  Note that encryption isn't
 101     // complete until the OnEncryptionComplete() notification has been
 102     // sent (see below).
 103     //
 104     // |encrypted_types| will always be a superset of
 105     // Cryptographer::SensitiveTypes().  If |encrypt_everything| is
 106     // true, |encrypted_types| will be the set of all known types.
 107     //
 108     // Until this function is called, observers can assume that the
 109     // set of encrypted types is Cryptographer::SensitiveTypes() and
 110     // that the encrypt everything flag is false.
 111     virtual void OnEncryptedTypesChanged(
 112         ModelTypeSet encrypted_types,
 113         bool encrypt_everything) = 0;
 114
 115     // Called after we finish encrypting the current set of encrypted
 116     // types.
 117     virtual void OnEncryptionComplete() = 0;
 118
 119     // The cryptographer has been updated. Listeners should check that their
 120     // own state matches the cryptographer.
 121     // Used primarily for debugging.
 122     virtual void OnCryptographerStateChanged(Cryptographer* cryptographer) = 0;
 123
 124     // The passphrase type has changed. |type| is the new type,
 125     // |passphrase_time| is the time the passphrase was set (unset if |type|
 126     // is KEYSTORE_PASSPHRASE or the passphrase was set before we started
 127     // recording the time).
 128     virtual void OnPassphraseTypeChanged(PassphraseType type,
 129                                          base::Time passphrase_time) = 0;
 130
 131     // The user has set a passphrase using this device.
 132     //
 133     // |nigori_state| can be used to restore nigori state across
 134     // SyncEncryptionHandlerImpl lifetimes. See also SyncEncryptionHandlerImpl's
 135     // RestoredNigori method.
 136     virtual void OnLocalSetPassphraseEncryption(
 137         const NigoriState& nigori_state) = 0;
 138
 139    protected:
 140     virtual ~Observer();
 141   };
 142
 143   class SYNC_EXPORT NigoriState {
 144    public:
 145     NigoriState() {}
 146     sync_pb::NigoriSpecifics nigori_specifics;
 147   };
 148
 149   SyncEncryptionHandler();
 150   virtual ~SyncEncryptionHandler();
 151
 152   // Add/Remove SyncEncryptionHandler::Observers.
 153   virtual void AddObserver(Observer* observer) = 0;
 154   virtual void RemoveObserver(Observer* observer) = 0;
 155
 156   // Reads the nigori node, updates internal state as needed, and, if an
 157   // empty/stale nigori node is detected, overwrites the existing
 158   // nigori node. Upon completion, if the cryptographer is still ready
 159   // attempts to re-encrypt all sync data.
 160   // Note: This method is expensive (it iterates through all encrypted types),
 161   // so should only be used sparingly (e.g. on startup).
 162   virtual void Init() = 0;
 163
 164   // Attempts to re-encrypt encrypted data types using the passphrase provided.
 165   // Notifies observers of the result of the operation via OnPassphraseAccepted
 166   // or OnPassphraseRequired, updates the nigori node, and does re-encryption as
 167   // appropriate. If an explicit password has been set previously, we drop
 168   // subsequent requests to set a passphrase. If the cryptographer has pending
 169   // keys, and a new implicit passphrase is provided, we try decrypting the
 170   // pending keys with it, and if that fails, we cache the passphrase for
 171   // re-encryption once the pending keys are decrypted.
 172   virtual void SetEncryptionPassphrase(const std::string& passphrase,
 173                                        bool is_explicit) = 0;
 174
 175   // Provides a passphrase for decrypting the user's existing sync data.
 176   // Notifies observers of the result of the operation via OnPassphraseAccepted
 177   // or OnPassphraseRequired, updates the nigori node, and does re-encryption as
 178   // appropriate if there is a previously cached encryption passphrase. It is an
 179   // error to call this when we don't have pending keys.
 180   virtual void SetDecryptionPassphrase(const std::string& passphrase) = 0;
 181
 182   // Enables encryption of all datatypes.
 183   virtual void EnableEncryptEverything() = 0;
 184
 185   // Whether encryption of all datatypes is enabled. If false, only sensitive
 186   // types are encrypted.
 187   virtual bool IsEncryptEverythingEnabled() const = 0;
 188
 189   // Returns the current state of the passphrase needed to decrypt the
 190   // bag of encryption keys in the nigori node.
 191   virtual PassphraseType GetPassphraseType() const = 0;
 192
 193   // The set of types that are always encrypted.
 194   static ModelTypeSet SensitiveTypes();
 195 };
 196
 197 }  // namespace syncer
 198
 199 #endif  // SYNC_INTERNAL_API_PUBLIC_SYNC_ENCRYPTION_HANDLER_H_