From 50470993912b19d6d62f1aaa6a6539460a8f933c Mon Sep 17 00:00:00 2001 From: drebs Date: Thu, 28 Sep 2017 12:16:02 -0300 Subject: [doc] improve server doc --- docs/index.rst | 6 ++++ docs/server.rst | 86 ++++++++++++--------------------------------------------- 2 files changed, 24 insertions(+), 68 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index ea723307..9e992835 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,6 +10,12 @@ 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. +The application is written in Python and the `source code +`_ is available and licensed as free software. +Both client and server are `distributed through pypi +`_, and `Debian packages +`_ are also provided for the server-side component. + .. toctree:: :maxdepth: 2 diff --git a/docs/server.rst b/docs/server.rst index 88bf909f..a0eb8181 100644 --- a/docs/server.rst +++ b/docs/server.rst @@ -1,77 +1,13 @@ Soledad Server ============== -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 --python /path/to/leap/soledad/server/server.tac - -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-' 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 Server is a document store and a blobs server that can synchronize data +with a Soledad Client. .. _server-config-file: -Server Configuration File -------------------------- +Configuring +----------- Soledad Server looks for a configuration file in ``/etc/soledad/soledad-server.conf`` and will read the following configuration @@ -93,3 +29,17 @@ blobs_path The path for blobs storage in the server's file ``/var/lib/ services_tokens_file The file containing authentication tokens for ``/etc/soledad/services.tokens`` services provided through the Services API. ==================== =============================================== ================================ + +Running +------- + +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 --python /path/to/leap/soledad/server/server.tac + +An systemd script is included in the `Debian packages +`_ to make it feasible to start and stop the +Soledad server service using a standard interface. -- cgit v1.2.3