summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--docs/index.rst1
-rw-r--r--docs/intro.rst41
-rw-r--r--docs/intro/data-availability.rst21
-rw-r--r--docs/intro/goals.rst72
-rw-r--r--docs/intro/related.rst16
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.