[doc] add intro section with reviwed content from old doc

3 files changed, 109 insertions, 0 deletions

diff --git a/docs/intro/data-availability.rst b/docs/intro/data-availability.rst
new file mode 100644
index 00000000..cf65428e
--- /dev/null
+++ b/docs/intro/data-availability.rst
@@ -0,0 +1,21 @@
+The importance of data availability
+===================================
+
+Users today demand high data availability in their applications. As a user
+switches from device to device, the expectation is that each application will
+reflect the same state information across devices. Additionally, if all devices
+are lost or destroyed, the contemporary user expects to be able to restore her
+or his application data from the cloud.
+
+In many ways, data availability has become a necessary precondition for an
+application to be considered "user friendly". Unfortunately, most applications
+attempt to provide high data availability by rolling their own custom solution
+or relying on a third party API, such as Dropbox. This approach is has several
+drawbacks: the user has no control or access to the data should they wish to
+switch applications or data providers; custom data synchronizations schemes are
+often an afterthought, poorly designed, and vulnerable to attack and data
+breaches; and the user must place total trust in the provider to safeguard her
+or his information against requests by repressive governments.
+
+Soledad provides secure data availability in a way that is easy for application
+developers to incorporate into their code.
diff --git a/docs/intro/goals.rst b/docs/intro/goals.rst
new file mode 100644
index 00000000..0429e44b
--- /dev/null
+++ b/docs/intro/goals.rst
@@ -0,0 +1,72 @@
+Goals
+=====
+
+Security goals
+--------------
+
+* **Client-side encryption:** Before any data is synced to the cloud, it should
+  be encrypted on the client device.
+
+* **Encrypted local storage:** Any data cached in the client should be stored
+  in an encrypted format.
+
+* **Resistant to offline attacks:** Data stored on the server should be highly
+  resistant to offline attacks (i.e. an attacker with a static copy of data
+  stored on the server would have a very hard time discerning much from the
+  data).
+
+* **Resistant to online attacks:** Analysis of storing and retrieving data
+  should not leak potentially sensitive information.
+
+* **Resistance to data tampering:** The server should not be able to provide
+  the client with old or bogus data for a document.
+
+Synchronization goals
+---------------------
+
+* **Consistency:** multiple clients should all get sync'ed with the same data.
+
+* **Selective sync:** the ability to partially sync data. For example, so
+  a mobile device doesn’t need to sync all email attachments.
+
+* **Multi-platform:** supports both desktop and mobile clients.
+
+* **Quota:** the ability to identify how much storage space a user is taking up.
+
+* **Scalable cloud:** distributed master-less storage on the cloud side, with
+  no single point of failure.
+
+* **Conflict resolution:** conflicts are flagged and handed off to the
+  application logic to resolve.  Usability goals
+
+* **Availability:** the user should always be able to access their data.
+
+* **Recovery:** there should be a mechanism for a user to recover their data
+  should they forget their password.
+
+Known limitations
+-----------------
+
+These are currently known limitations:
+
+* The server knows when the contents of a document have changed.
+
+* There is no facility for sharing documents among multiple users.
+
+* Soledad is not able to prevent server from withholding new documents or new
+  revisions of a document.
+
+* Deleted documents are never deleted, just emptied. Useful for security reasons, but could lead to DB bloat.
+
+Non-goals
+---------
+
+* Soledad is not for filesystem synchronization, storage or backup. It provides
+  an API for application code to synchronize and store arbitrary schema-less
+  JSON documents in one big flat document database. One could model
+  a filesystem on top of Soledad, but it would be a bad fit.
+
+* Soledad is not intended for decentralized peer-to-peer synchronization,
+  although the underlying synchronization protocol does not require a server.
+  Soledad takes a cloud approach in order to ensure that a client has quick
+  access to an available copy of the data.
diff --git a/docs/intro/related.rst b/docs/intro/related.rst
new file mode 100644
index 00000000..16335e17
--- /dev/null
+++ b/docs/intro/related.rst
@@ -0,0 +1,16 @@
+Related projects
+================
+
+* `Crypton <https://github.com/SpiderOak/crypton>`_: Similar goals to Soledad,
+  but in javascript for HTML5 applications.
+
+* `Mylar <https://github.com/strikeout/mylar>`_: Like Crypton, Mylar can be
+  used to write secure HTML5 applications in javascript. Uniquely, it includes
+  support for homomorphic encryption to allow server-side searches.
+
+* `Firefox Sync <https://wiki.mozilla.org/Services/Sync>`_: A client-encrypted
+  data sync from Mozilla, designed to securely synchronize bookmarks and other
+  browser settings.
+
+* `U1DB <https://pythonhosted.org/u1db/>`_: Document synchronization API used
+  as a basis for Soledad, without encryption.