summaryrefslogtreecommitdiff
path: root/docs/sphinx/server.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/sphinx/server.rst')
-rw-r--r--docs/sphinx/server.rst90
1 files changed, 67 insertions, 23 deletions
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.