summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--docs/sphinx/client.rst45
-rw-r--r--docs/sphinx/common.rst6
-rw-r--r--docs/sphinx/conf.py6
-rw-r--r--docs/sphinx/index.rst12
-rw-r--r--docs/sphinx/server.rst90
-rw-r--r--docs/sphinx/sync.rst39
-rw-r--r--server/src/leap/soledad/server/__init__.py65
7 files changed, 101 insertions, 162 deletions
diff --git a/docs/sphinx/client.rst b/docs/sphinx/client.rst
index 0c608c31..ed813634 100644
--- a/docs/sphinx/client.rst
+++ b/docs/sphinx/client.rst
@@ -1,44 +1,9 @@
-Soledad Client documentation
-============================
+Soledad Client API
+==================
-.. automodule:: leap.soledad.client
- :members:
- :undoc-members:
- :private-members:
- :show-inheritance:
-
-.. automodule:: leap.soledad.client.auth
- :members:
- :undoc-members:
- :private-members:
- :show-inheritance:
-
-.. automodule:: leap.soledad.client.crypto
- :members:
- :undoc-members:
- :private-members:
- :show-inheritance:
-
-.. automodule:: leap.soledad.client.shared_db
- :members:
- :undoc-members:
- :private-members:
- :show-inheritance:
-
-.. automodule:: leap.soledad.client.soledad_db
- :members:
- :undoc-members:
- :private-members:
- :show-inheritance:
-
-.. automodule:: leap.soledad.client.sqlcipher
- :members:
- :undoc-members:
- :private-members:
- :show-inheritance:
+.. toctree::
+ :maxdepth: 2
-.. automodule:: leap.soledad.client.target
+.. autoclass:: leap.soledad.client.Soledad
:members:
:undoc-members:
- :private-members:
- :show-inheritance:
diff --git a/docs/sphinx/common.rst b/docs/sphinx/common.rst
index 8755b3bd..f7a3dfa8 100644
--- a/docs/sphinx/common.rst
+++ b/docs/sphinx/common.rst
@@ -19,12 +19,6 @@ Soledad Common documentation
:private-members:
:show-inheritance:
-.. automodule:: leap.soledad.common.ddocs
- :members:
- :undoc-members:
- :private-members:
- :show-inheritance:
-
.. automodule:: leap.soledad.common.document
:members:
:undoc-members:
diff --git a/docs/sphinx/conf.py b/docs/sphinx/conf.py
index 552e5f56..bad9da6e 100644
--- a/docs/sphinx/conf.py
+++ b/docs/sphinx/conf.py
@@ -34,7 +34,7 @@ extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.todo',
'sphinx.ext.coverage',
- 'sphinx.ext.pngmath',
+ 'sphinx.ext.imgmath',
'sphinx.ext.viewcode',
]
@@ -59,9 +59,9 @@ copyright = u'2014, LEAP Encryption Access Project'
# built documents.
#
# The short X.Y version.
-version = '0.4'
+#version = '0.4'
# The full version, including alpha/beta/rc tags.
-release = '0.4.0'
+#release = '0.4.0'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
diff --git a/docs/sphinx/index.rst b/docs/sphinx/index.rst
index 6298d034..c4ccffc9 100644
--- a/docs/sphinx/index.rst
+++ b/docs/sphinx/index.rst
@@ -6,22 +6,16 @@
Soledad documentation
=====================
-Contents:
+Soledad is an acronym for Synchronization of Locally Encrypted Data Among
+Devices. It is LEAP's solution for synchronizing client-encrypted data among
+all user's devices that access a LEAP provider.
.. toctree::
:maxdepth: 2
- common
client
server
-.. automodule:: leap.soledad.common
- :members:
- :undoc-members:
- :private-members:
- :show-inheritance:
-
-
Indices and tables
==================
diff --git a/docs/sphinx/server.rst b/docs/sphinx/server.rst
index f093adf4..4f99f266 100644
--- a/docs/sphinx/server.rst
+++ b/docs/sphinx/server.rst
@@ -1,27 +1,71 @@
Soledad Server documentation
============================
-.. automodule:: leap.soledad.server
- :members:
- :undoc-members:
- :private-members:
- :show-inheritance:
-
-.. automodule:: leap.soledad.server.auth
- :members:
- :undoc-members:
- :private-members:
- :show-inheritance:
-
-.. automodule:: leap.soledad.server.gzip_middleware
- :members:
- :undoc-members:
- :private-members:
- :show-inheritance:
-
-.. automodule:: leap.soledad.server.lock_resource
- :members:
- :undoc-members:
- :private-members:
- :show-inheritance:
+A U1DB server that stores data using CouchDB as its persistence layer.
+.. contents::
+ :local:
+
+General information
+-------------------
+
+This is written as a Twisted application and intended to be run using the
+twistd command. To start the soledad server, run:
+
+.. code-block:: bash
+
+ twistd -n web \
+ --class=leap.soledad.server.entrypoint.SoledadEntrypoint \
+ --port=X
+
+An systemd script is included and will be installed system wide to make it
+feasible to start and stop the Soledad server service using a standard
+interface.
+
+Server database organization
+----------------------------
+
+Soledad Server works with one database per user and one shared database in
+which user's encrypted secrets might be stored.
+
+User database
+~~~~~~~~~~~~~
+
+Users' databases in the server are named 'user-<uuid>' and Soledad Client
+may perform synchronization between its local replicas and the user's
+database in the server. Authorization for creating, updating, deleting and
+retrieving information about the user database as well as performing
+synchronization is handled by the `leap.soledad.server.auth` module.
+
+Shared database
+~~~~~~~~~~~~~~~
+
+Each user may store password-encrypted recovery data in the shared database.
+
+Recovery documents are stored in the database without any information that
+may identify the user. In order to achieve this, the doc_id of recovery
+documents are obtained as a hash of the user's uid and the user's password.
+User's must have a valid token to interact with recovery documents, but the
+server does not perform further authentication because it has no way to know
+which recovery document belongs to each user.
+
+This has some implications:
+
+ * The security of the recovery document doc_id, and thus of access to the
+ recovery document (encrypted) content, as well as tampering with the
+ stored data, all rely on the difficulty of obtaining the user's password
+ (supposing the user's uid is somewhat public) and the security of the hash
+ function used to calculate the doc_id.
+
+ * The security of the content of a recovery document relies on the
+ difficulty of obtaining the user's password.
+
+ * If the user looses his/her password, he/she will not be able to obtain the
+ recovery document.
+
+ * Because of the above, it is recommended that recovery documents expire
+ (not implemented yet) to prevent excess storage.
+
+The authorization for creating, updating, deleting and retrieving recovery
+documents on the shared database is handled by `leap.soledad.server.auth`
+module.
diff --git a/docs/sphinx/sync.rst b/docs/sphinx/sync.rst
index f243befb..b9d4c858 100644
--- a/docs/sphinx/sync.rst
+++ b/docs/sphinx/sync.rst
@@ -1,31 +1,34 @@
Soledad sync process
====================
+TODO: this documentation needs to be updated to account for new streaming encryption method.
+
Phases of sync:
-(1) client acquires knowledge about server state. http GET
-(2) client sends its documents to the server. http POSTs, or a single POST.
-(3) client downloads documents from the server.
-(4) client records its new state on the server.
+1. client acquires knowledge about server state.
+2. client sends its documents to the server.
+3. client downloads documents from the server.
+4. client records its new state on the server.
Originally in u1db:
-    (1) is a GET,
-    (2) and (3) are one POST (send in body, receive in response),
-    (4) is a PUT.
+
+* **1** is a GET,
+* **2** and **3** are one POST (send in body, receive in response),
+* **4** is a PUT.
In soledad:
-(1) is a GET.
-(2) is either 1 or a series of sequential POSTS.
-  (2.1) encrypt asynchronously
-  (2.2) store in temp sync db
-  (2.3) upload sequentially ***THIS IS SLOW***
-(3) is a series of concurrent POSTS, insert sequentially on local client db.
-  (3.1) download concurrently
-  (3.2) store in temp sync db
-  (3.3) decrypt asynchronously
-  (3.4) insert sequentially in local client db
-(4) is a PUT.
+* **1** is a GET.
+* **2** is either 1 or a series of sequential POSTS.
+ * **2.1** encrypt asynchronously
+ * **2.2** store in temp sync db
+  * **2.3** upload sequentially
+* **3** is a series of concurrent POSTS, insert sequentially on local client db.
+ * **3.1** download concurrently
+  * **3.2** store in temp sync db
+  * **3.3** decrypt asynchronously
+  * **3.4** insert sequentially in local client db
+* **4** is a PUT.
This difference between u1db and soledad was made in order to be able to gracefully interrupt the sync in the middle of the upload or the download.
diff --git a/server/src/leap/soledad/server/__init__.py b/server/src/leap/soledad/server/__init__.py
index 6640bab4..a4080f13 100644
--- a/server/src/leap/soledad/server/__init__.py
+++ b/server/src/leap/soledad/server/__init__.py
@@ -17,69 +17,8 @@
"""
-A U1DB server that stores data using CouchDB as its persistence layer.
-
-General information
-===================
-
-This is written as a Twisted application and intended to be run using the
-twistd command. To start the soledad server, run:
-
- twistd -n web \
- --wsgi=leap.soledad.server.application.wsgi_application \
- --port=X
-
-An initscript is included and will be installed system wide to make it
-feasible to start and stop the Soledad server service using a standard
-interface.
-
-Server database organization
-============================
-
-Soledad Server works with one database per user and one shared database in
-which user's encrypted secrets might be stored.
-
-User database
--------------
-
-Users' databases in the server are named 'user-<uuid>' and Soledad Client
-may perform synchronization between its local replicas and the user's
-database in the server. Authorization for creating, updating, deleting and
-retrieving information about the user database as well as performing
-synchronization is handled by the `leap.soledad.server.auth` module.
-
-Shared database
----------------
-
-Each user may store password-encrypted recovery data in the shared database.
-
-Recovery documents are stored in the database without any information that
-may identify the user. In order to achieve this, the doc_id of recovery
-documents are obtained as a hash of the user's uid and the user's password.
-User's must have a valid token to interact with recovery documents, but the
-server does not perform further authentication because it has no way to know
-which recovery document belongs to each user.
-
-This has some implications:
-
- * The security of the recovery document doc_id, and thus of access to the
- recovery document (encrypted) content, as well as tampering with the
- stored data, all rely on the difficulty of obtaining the user's password
- (supposing the user's uid is somewhat public) and the security of the hash
- function used to calculate the doc_id.
-
- * The security of the content of a recovery document relies on the
- difficulty of obtaining the user's password.
-
- * If the user looses his/her password, he/she will not be able to obtain the
- recovery document.
-
- * Because of the above, it is recommended that recovery documents expire
- (not implemented yet) to prevent excess storage.
-
-The authorization for creating, updating, deleting and retrieving recovery
-documents on the shared database is handled by `leap.soledad.server.auth`
-module.
+The Soledad Server allows for recovery document storage and database
+synchronization.
"""
import six.moves.urllib.parse as urlparse