From 33e30feb2d7cedb1aecbde2f339b40f72128a585 Mon Sep 17 00:00:00 2001 From: drebs Date: Mon, 23 Oct 2017 10:21:21 -0200 Subject: [doc] small fixes in documentation --- docs/client.rst | 38 +++++++++++++++++++------------------- docs/reference/blobs.rst | 2 +- docs/reference/incoming_box.rst | 30 ++++++++++++++---------------- docs/reference/server-database.rst | 22 +++++++++++----------- 4 files changed, 45 insertions(+), 47 deletions(-) (limited to 'docs') diff --git a/docs/client.rst b/docs/client.rst index 0baba7e8..fbced197 100644 --- a/docs/client.rst +++ b/docs/client.rst @@ -7,34 +7,34 @@ The Soledad Client is a Python library aimed to provide access to a document store that can be synchronized securelly with other deviced through the Soledad Server. Key aspects of Soledad Client include: - * **Encrypted local storage:** All data cached locally is stored in an - encrypted database. +* **Encrypted local storage:** All data cached locally is stored in an + encrypted database. - * **Client-side encrypted sync:** Soledad puts very little trust in the - server by encrypting all data before it is synchronized to the server and - by limiting ways in which the server can modify the user's data. +* **Client-side encrypted sync:** Soledad puts very little trust in the + server by encrypting all data before it is synchronized to the server and + by limiting ways in which the server can modify the user's data. - * **Document database:** An application using the Soledad client library is - presented with a document-centric database API for storage and sync. - Documents may be indexed, searched, and versioned. +* **Document database:** An application using the Soledad client library is + presented with a document-centric database API for storage and sync. + Documents may be indexed, searched, and versioned. - * **Blobs storage:** The client and server API provide blobs storage, which - can be used both for data delivery in the server side (i.e. email) and - payload storage on the client side. +* **Blobs storage:** The client and server API provide blobs storage, which + can be used both for data delivery in the server side (i.e. email) and + payload storage on the client side. Setting-up ---------- The following information is needed in order to instantiate a soledad client: - * ``uuid``: the user's uuid. - * ``passphrase``: the user's passphrase. - * ``secrets_path``: a local path for secrets storage. - * ``local_db_path``: a local path for the documents database. - * ``server_url``: the Soledad Server's URL. - * ``cert_file``: a local path for the CA certificate. - * ``auth_token``: an authentication token obtained after logging into the - provider. +* ``uuid``: the user's uuid. +* ``passphrase``: the user's passphrase. +* ``secrets_path``: a local path for secrets storage. +* ``local_db_path``: a local path for the documents database. +* ``server_url``: the Soledad Server's URL. +* ``cert_file``: a local path for the CA certificate. +* ``auth_token``: an authentication token obtained after logging into the + provider. Once all pieces are in place, you can instantiate the client as following: diff --git a/docs/reference/blobs.rst b/docs/reference/blobs.rst index 5d480342..17880802 100644 --- a/docs/reference/blobs.rst +++ b/docs/reference/blobs.rst @@ -39,7 +39,7 @@ The public endpoint provides the following REST API for interacting with the =========================== ========== ================================= ============================================ path method action accepted query string fields =========================== ========== ================================= ============================================ -``/blobs/{uuid} ``GET`` Get a list of blobs. filtered by ``namespace``, ``filter_flag``, ``order_by`` +``/blobs/{uuid}`` ``GET`` Get a list of blobs. filtered by ``namespace``, ``filter_flag``, ``order_by`` a flag. ``/blobs/{uuid}/{blob_id}`` ``GET`` Get the contents of a blob. ``namespace`` ``/blobs/{uuid}/{blob_id}`` ``PUT`` Create a blob. The content of the ``namespace`` diff --git a/docs/reference/incoming_box.rst b/docs/reference/incoming_box.rst index 04d3084c..920d03bf 100644 --- a/docs/reference/incoming_box.rst +++ b/docs/reference/incoming_box.rst @@ -230,22 +230,20 @@ registered Trusted Application Consumers. process, attention SHOULD be payed to the callbacks not blocking the main event loop. -Example of a Trusted Application Client Consumer: - -```python -@implementer(interfaces.IIncomingBoxConsumer) -class MyConsumer(object): - def __init__(self): - self.name = 'My Consumer' - - def process(self, item, item_id, encrypted=True): - cleartext = my_custom_decrypt(item) if encrypted else item - processed_parts = my_custom_processing(item) - return defer.succeed(processed_parts) - - def save(self, parts, item_id): - return defer.gatherResults([db.save(part) for part in parts]) -``` +Example of a Trusted Application Client Consumer:: + + @implementer(interfaces.IIncomingBoxConsumer) + class MyConsumer(object): + def __init__(self): + self.name = 'My Consumer' + + def process(self, item, item_id, encrypted=True): + cleartext = my_custom_decrypt(item) if encrypted else item + processed_parts = my_custom_processing(item) + return defer.succeed(processed_parts) + + def save(self, parts, item_id): + return defer.gatherResults([db.save(part) for part in parts]) Future Features diff --git a/docs/reference/server-database.rst b/docs/reference/server-database.rst index d3dfdb5f..dba9d42c 100644 --- a/docs/reference/server-database.rst +++ b/docs/reference/server-database.rst @@ -29,20 +29,20 @@ 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 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. +* 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. +* 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. +* 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` -- cgit v1.2.3