diff options
| -rw-r--r-- | docs/sphinx/client.rst | 45 | ||||
| -rw-r--r-- | docs/sphinx/common.rst | 6 | ||||
| -rw-r--r-- | docs/sphinx/conf.py | 6 | ||||
| -rw-r--r-- | docs/sphinx/index.rst | 12 | ||||
| -rw-r--r-- | docs/sphinx/server.rst | 90 | ||||
| -rw-r--r-- | docs/sphinx/sync.rst | 39 | ||||
| -rw-r--r-- | server/src/leap/soledad/server/__init__.py | 65 |
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 |