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

5 files changed, 151 insertions, 0 deletions

diff --git a/docs/index.rst b/docs/index.rst
index 275bad96..c9841903 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -37,6 +37,7 @@ Soledad documentation
 .. toctree::
    :maxdepth: 2
 
+   intro
    server
    client
    reference
diff --git a/docs/intro.rst b/docs/intro.rst
new file mode 100644
index 00000000..90ae6cf3
--- /dev/null
+++ b/docs/intro.rst
@@ -0,0 +1,41 @@
+Introduction
+============
+
+Soledad consists of a client library and server daemon that allows applications
+to securely share a common state among devices. The local application is
+presented with a simple, document-centric searchable database API. Any data
+saved to the database by the application is client-encrypted, backed up in the
+cloud, and synchronized among a user’s devices. Soledad is cross-platform, open
+source, scalable, and features a highly efficient synchronization algorithm.
+
+Key aspects of Soledad include:
+
+* **Client and server:** Soledad includes a :ref:`server daemon
+  <soledad-server>` and a :ref:`client application library <soledad-client>`.
+
+* **Client-side encrypted sync:** Soledad puts very little trust in the server
+  by :ref:`encrypting all data <document-encryption>` before it is
+  :ref:`synchronized <document-sync>` to the server and by limiting ways in
+  which the server can modify the user’s data.
+
+* **Encrypted local storage:** All data cached locally is :ref:`stored in an
+  encrypted database <client-databases>`.
+
+* **Document database:** An application using the Soledad client library is
+  presented with a :ref:`document-centric database API <soledad-client-api>`
+  for storage and sync. Documents may be indexed, searched, and versioned.
+
+* **Encrypted attachments:** storage and synchronization of :ref:`blobs` is
+  supported.
+
+Soledad is an acronym of “Synchronization of Locally Encrypted Documents Among
+Devices” and means “solitude” in Spanish.
+
+See also:
+
+.. toctree::
+   :maxdepth: 1
+
+   intro/data-availability
+   intro/goals
+   intro/related
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.