Verified Commit 6008e999 authored by drebs's avatar drebs
Browse files

[doc] cleanup old documentation

parent 486909fd
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:
......@@ -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:
......
......@@ -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.
......
......@@ -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
==================
......
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.
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.
......
......@@ -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
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment