Browse files

[Sync] Storage format 6 and Mozilla-specific docs

  • Loading branch information...
1 parent a6dd19f commit 3f8a6ed06876022f7861229ef68281104ecab2f4 @indygreg indygreg committed Apr 11, 2012
Showing with 105 additions and 8 deletions.
  1. +89 −0 source/sync/mozilla.rst
  2. +16 −8 source/sync/storageformat6.rst
@@ -0,0 +1,89 @@
+.. _sync_mozilla:
+Mozilla's Sync Service
+This document describes how Sync is deployed at Mozilla.
+.. attention::
+ This document is not complete. Consult the Services team for authoritative
+ information.
+Mozilla's Sync service is comprised of the following services:
+- :ref:`Storage Service 1.1 <server_storage_api_11>`
+- :ref:`User Registration Service <reg>`
+- :ref:`Secure-Registration Service <sreg>`
+- :ref:`Easy Setup Key Exchange Service <ezsetup>`
+Mozilla operates many instances of the Storage Service. We call these nodes.
+Each node is independent from the others and has no knowledge that other
+nodes exist.
+When a new account is provisioned, the Registration Service assigns a user to
+a node. The node is chosen based on which nodes have capacity, etc. After node
+assignment, clients connect directly to that specific node. All Sync operations
+are performed against that client's assigned Sync node.
+The user registration service is hosted on
+If you download Firefox from Mozilla and set up Sync, this is where it will
+connect by default.
+Easy Setup Service
+Mozilla hosts an instance of the :ref:`Easy Setup <ezsetup>` service at
+ When you pair two devices by entering
+codes, they communicate through this service.
+Crypto Record Semantics
+:ref:`Storage Format 6<sync_storageformat6>` does not explicitly define
+semantics for how **crypto records** are managed, leaving it up to the clients
+to agree on behavior. This section documents the behavior in Mozilla clients.
+Clients and Key Management
+Sync clients can differ in their abilities to manage keys and their associated
+crypto records on the server. There exist 2 tiers of clients:
+- Tier 1 Client - Supports key generation and management.
+- Tier 2 Client - Supports key consumption only.
+Tier 1 clients are full Sync clients. They can provision accounts from empty
+servers, reset server data, change keys around, etc. Tier 2 clients are simpler
+clients that only support reading of keys (no writing).
+The main reason why different tiers of clients exist is that cryptography,
+security, and the management of keys is hard and that these problems should
+be left to professionals. It is extremely easy for a client to introduce subtle
+differences that could compromise the integrity of data security. By providing
+a facility for clients that don't modify keys, we are reducing the surface area
+on which a new client may error as well as decreasing the number of clients
+which need to be validated for proper behavior.
+Mozilla provides the following Tier 1 Clients:
+- Firefox (on desktop)
+- Firefox (on mobile - aka Fennec)
+Tier 2 Client Behavior
+Tier 2 clients **never** perform updates to the *crypto* collection. Instead,
+they read records and get the data they need. If the data they need is
+unavailable (i.e. the record it wants isn't found), it gives up and tries again
+Tier 2 clients do support creating new collections on the server. When a Tier 2
+client wishes to create a new collection, it will need to use a **Collection
+Key Bundle** for that collection. Normally, a new **Collection Key Bundle**
+would be created and uploaded. However, since Tier 2 clients must not modify
+the *crypto* collection, they resort to other means.
@@ -6,7 +6,7 @@ Global Storage Version 6
.. attention::
- This document is an unofficial proposal. It will likely change.
+ This document is a proposal. It will likely change.
This document describes version 6 of Sync's global storage format. This
describes not only the technical details of the storage format, but also some
@@ -32,13 +32,15 @@ Bundle**. A single **Collection Key Bundle** is used to perform cryptographic
operations on every record in the collection to which it is associated.
It is recommended, but not technically required, that each **Collection Key Bundle**
-be associated with a single collection.
+be associated with at most a single collection.
Special records on the server hold mappings of collection names to their
respective **Collection Key Bundles**. The **Collection Key Bundles** are
encrypted using another higher-level **Key Bundle** before they are stored
-on the server. We refer to these higher-level **Key Bundles** as
-**Key-Encrypting Key Bundles**.
+on the server. We refer to these higher-level **Key Bundles** as
+**Key-Encrypting Key Bundles**. And, the entity that holds the mapping to
+**Collection Key Bundles** is referred to as a **crypto record** (because it
+is a record stored in the *crypto* collection).
In the simple case, we have a single **Key-Encrypting Key Bundle** used to
encrypt the collection of all **Collection Key Bundles**. Each **Collection
@@ -65,6 +67,12 @@ In graph form:
HISTORY -> "History 2";
+This specification establishes no rules for which **crypto records** exist
+or for how **Key-Encrypting Key Bundles** are managed. This is entirely up to
+the client. In other words, key management is a convention between clients.
+If you are interested in interoperating with Firefox Sync, see
+:ref:`Mozilla's Sync Service<sync_mozilla>`.
This is the essence of the cryptographic model. More details are explained
@@ -222,8 +230,8 @@ crypto Collection
There exists a special collection on the server named **crypto**. This
-collection holds records that contain mappings of collections to **Key
+collection holds records that contain mappings of collections to **Collection
+Key Bundles**.
Each record in the *crypto* collection has associated with it specific
semantics. This specification is intentionally vague as to what records and
@@ -286,8 +294,8 @@ Cons:
* Server data reveals which encrypting keys can be used to unlock which
-Options 2
+Option 2
This is similar to Option 1 except that the mapping info is itself encrypted.

0 comments on commit 3f8a6ed

Please sign in to comment.