From acfe776f00f10a4ad700796993eef1b989432e91 Mon Sep 17 00:00:00 2001 From: drebs Date: Tue, 3 Oct 2017 12:53:17 -0300 Subject: [doc] add intro section with reviwed content from old doc --- docs/index.rst | 1 + docs/intro.rst | 41 +++++++++++++++++++++++ docs/intro/data-availability.rst | 21 ++++++++++++ docs/intro/goals.rst | 72 ++++++++++++++++++++++++++++++++++++++++ docs/intro/related.rst | 16 +++++++++ 5 files changed, 151 insertions(+) create mode 100644 docs/intro.rst create mode 100644 docs/intro/data-availability.rst create mode 100644 docs/intro/goals.rst create mode 100644 docs/intro/related.rst (limited to 'docs') 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 + ` and a :ref:`client application library `. + +* **Client-side encrypted sync:** Soledad puts very little trust in the server + by :ref:`encrypting all data ` before it is + :ref:`synchronized ` 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 `. + +* **Document database:** An application using the Soledad client library is + presented with a :ref:`document-centric database 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 `_: Similar goals to Soledad, + but in javascript for HTML5 applications. + +* `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 `_: A client-encrypted + data sync from Mozilla, designed to securely synchronize bookmarks and other + browser settings. + +* `U1DB `_: Document synchronization API used + as a basis for Soledad, without encryption. -- cgit v1.2.3