From 9dd3ebe6bad0bfe05840782c805e961cf4a96c6a Mon Sep 17 00:00:00 2001 From: drebs Date: Tue, 6 Jun 2017 15:12:56 -0300 Subject: [doc] move sphinx up to root of docs dir --- docs/server.rst | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 docs/server.rst (limited to 'docs/server.rst') diff --git a/docs/server.rst b/docs/server.rst new file mode 100644 index 00000000..4f99f266 --- /dev/null +++ b/docs/server.rst @@ -0,0 +1,71 @@ +Soledad Server documentation +============================ + +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-' 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. -- cgit v1.2.3