summaryrefslogtreecommitdiff
path: root/docs/sphinx
diff options
context:
space:
mode:
Diffstat (limited to 'docs/sphinx')
-rw-r--r--docs/sphinx/.gitignore1
-rw-r--r--docs/sphinx/Makefile20
-rw-r--r--docs/sphinx/attachments.rst77
-rw-r--r--docs/sphinx/client.rst9
-rw-r--r--docs/sphinx/common.rst32
-rw-r--r--docs/sphinx/conf.py267
-rw-r--r--docs/sphinx/index.rst26
-rw-r--r--docs/sphinx/requirements.pip2
-rw-r--r--docs/sphinx/server.rst71
-rw-r--r--docs/sphinx/sync.rst35
10 files changed, 0 insertions, 540 deletions
diff --git a/docs/sphinx/.gitignore b/docs/sphinx/.gitignore
deleted file mode 100644
index e35d8850..00000000
--- a/docs/sphinx/.gitignore
+++ /dev/null
@@ -1 +0,0 @@
-_build
diff --git a/docs/sphinx/Makefile b/docs/sphinx/Makefile
deleted file mode 100644
index dcc387ce..00000000
--- a/docs/sphinx/Makefile
+++ /dev/null
@@ -1,20 +0,0 @@
-# Minimal makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line.
-SPHINXOPTS =
-SPHINXBUILD = sphinx-build
-SPHINXPROJ = Soledad
-SOURCEDIR = .
-BUILDDIR = _build
-
-# Put it first so that "make" without argument is like "make help".
-help:
- @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-
-.PHONY: help Makefile
-
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
- @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/sphinx/attachments.rst b/docs/sphinx/attachments.rst
deleted file mode 100644
index 098f634f..00000000
--- a/docs/sphinx/attachments.rst
+++ /dev/null
@@ -1,77 +0,0 @@
-Document Attachments
-====================
-
-.. contents:: Contents:
- :local:
-
-The content of a Soledad document is assumed to be JSON. This is particularly
-bad for storing larger amounts of binary data, because:
-
-* the only way to store data in JSON is as unicode string, and this uses more
- space than needed for binary data storage.
-
-* the process of synchronization of Soledad documents depends on completing the
- transfer and decryption of the content of all new/updated documents before
- synchronized documents are available for use.
-
-Document attachments were introduced as a means to store large payloads of
-binary data and have them be synchronized separate from the usual Soledad
-document synchronization process.
-
-Example
--------
-
-The attachments API is currently available in the `Document` class, and the
-document needs to know about the store to be able to manage attachments. When
-you create a new document with soledad, that document will already know about
-the store that created it, and can put/get/delete an attachment:
-
-.. code-block:: python
-
- from twisted.internet.defer import inlineCallbacks
-
- @inlineCallbacks
- def attachment_example(soledad):
- doc = yield soledad.create_doc({})
-
- state = yield doc.get_attachment_state()
- dirty = yield doc.is_dirty()
- assert state == AttachmentStates.NONE
- assert dirty == False
-
- yield doc.put_attachment(open('hackers.txt'))
- state = yield doc.get_attachment_state()
- dirty = yield doc.is_dirty()
- assert state | AttachmentState.LOCAL
- assert dirty == True
-
- yield soledad.put_doc(doc)
- dirty = yield doc.is_dirty()
- assert dirty == False
-
- yield doc.upload_attachment()
- state = yield doc.get_attachment_state()
- assert state | AttachmentState.REMOTE
- assert state == AttachmentState.SYNCED
-
- fd = yield doc.get_attachment()
- assert fd.read() == open('hackers.txt').read()
-
-Implementation
---------------
-
-The current implementation of document attachments store data in a separate
-SQLCipher database in the client (using SQLite's BLOB type) and in the
-filesystem in the server. Encryption of data before it's sent to the server is
-the same used by normal Soledad synchronization process (AES-256 GCM mode).
-
-Document attachment API
------------------------
-
-.. autoclass:: leap.soledad.client._document.AttachmentStates
- :members:
- :undoc-members:
-
-.. autointerface:: leap.soledad.client._document.IDocumentWithAttachment
- :members:
- :undoc-members:
diff --git a/docs/sphinx/client.rst b/docs/sphinx/client.rst
deleted file mode 100644
index ed813634..00000000
--- a/docs/sphinx/client.rst
+++ /dev/null
@@ -1,9 +0,0 @@
-Soledad Client API
-==================
-
-.. toctree::
- :maxdepth: 2
-
-.. autoclass:: leap.soledad.client.Soledad
- :members:
- :undoc-members:
diff --git a/docs/sphinx/common.rst b/docs/sphinx/common.rst
deleted file mode 100644
index f7a3dfa8..00000000
--- a/docs/sphinx/common.rst
+++ /dev/null
@@ -1,32 +0,0 @@
-Soledad Common documentation
-============================
-
-.. automodule:: leap.soledad.common
- :members:
- :undoc-members:
- :private-members:
- :show-inheritance:
-
-.. automodule:: leap.soledad.common.couch
- :members:
- :undoc-members:
- :private-members:
- :show-inheritance:
-
-.. automodule:: leap.soledad.common.crypto
- :members:
- :undoc-members:
- :private-members:
- :show-inheritance:
-
-.. automodule:: leap.soledad.common.document
- :members:
- :undoc-members:
- :private-members:
- :show-inheritance:
-
-.. automodule:: leap.soledad.common.errors
- :members:
- :undoc-members:
- :private-members:
- :show-inheritance:
diff --git a/docs/sphinx/conf.py b/docs/sphinx/conf.py
deleted file mode 100644
index 38ff330f..00000000
--- a/docs/sphinx/conf.py
+++ /dev/null
@@ -1,267 +0,0 @@
-# -*- coding: utf-8 -*-
-#
-# Soledad documentation build configuration file, created by
-# sphinx-quickstart on Mon Feb 17 18:20:43 2014.
-#
-# This file is execfile()d with the current directory set to its
-# containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
-
-import sys
-import os
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath('../../common/src'))
-sys.path.insert(0, os.path.abspath('../../client/src'))
-sys.path.insert(0, os.path.abspath('../../server/src'))
-
-# -- General configuration ------------------------------------------------
-
-# If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
-extensions = [
- 'sphinx.ext.autodoc',
- 'sphinx.ext.todo',
- 'sphinx.ext.coverage',
- 'sphinx.ext.imgmath',
- 'sphinx.ext.viewcode',
- 'sphinxcontrib.zopeext.autointerface',
-]
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# The suffix of source filenames.
-source_suffix = '.rst'
-
-# The encoding of source files.
-#source_encoding = 'utf-8-sig'
-
-# The master toctree document.
-master_doc = 'index'
-
-# General information about the project.
-project = u'Soledad'
-copyright = u'2014, LEAP Encryption Access Project'
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-#version = '0.4'
-# The full version, including alpha/beta/rc tags.
-#release = '0.4.0'
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#language = None
-
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-#today = ''
-# Else, today_fmt is used as the format for a strftime call.
-#today_fmt = '%B %d, %Y'
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-exclude_patterns = ['_build']
-
-# The reST default role (used for this markup: `text`) to use for all
-# documents.
-#default_role = None
-
-# If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-#add_module_names = True
-
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-#show_authors = False
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
-
-# A list of ignored prefixes for module index sorting.
-#modindex_common_prefix = []
-
-# If true, keep warnings as "system message" paragraphs in the built documents.
-#keep_warnings = False
-
-
-# -- Options for HTML output ----------------------------------------------
-
-# The theme to use for HTML and HTML Help pages. See the documentation for
-# a list of builtin themes.
-html_theme = 'default'
-
-# Theme options are theme-specific and customize the look and feel of a theme
-# further. For a list of options available for each theme, see the
-# documentation.
-#html_theme_options = {}
-
-# Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
-
-# The name for this set of Sphinx documents. If None, it defaults to
-# "<project> v<release> documentation".
-#html_title = None
-
-# A shorter title for the navigation bar. Default is the same as html_title.
-#html_short_title = None
-
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
-#html_logo = None
-
-# The name of an image file (within the static path) to use as favicon of the
-# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
-#html_favicon = None
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
-
-# Add any extra paths that contain custom files (such as robots.txt or
-# .htaccess) here, relative to this directory. These files are copied
-# directly to the root of the documentation.
-#html_extra_path = []
-
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
-
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-#html_use_smartypants = True
-
-# Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
-
-# Additional templates that should be rendered to pages, maps page names to
-# template names.
-#html_additional_pages = {}
-
-# If false, no module index is generated.
-#html_domain_indices = True
-
-# If false, no index is generated.
-#html_use_index = True
-
-# If true, the index is split into individual pages for each letter.
-#html_split_index = False
-
-# If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
-
-# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-#html_show_sphinx = True
-
-# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-#html_show_copyright = True
-
-# If true, an OpenSearch description file will be output, and all pages will
-# contain a <link> tag referring to it. The value of this option must be the
-# base URL from which the finished HTML is served.
-#html_use_opensearch = ''
-
-# This is the file name suffix for HTML files (e.g. ".xhtml").
-#html_file_suffix = None
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'Soledaddoc'
-
-
-# -- Options for LaTeX output ---------------------------------------------
-
-latex_elements = {
-# The paper size ('letterpaper' or 'a4paper').
-#'papersize': 'letterpaper',
-
-# The font size ('10pt', '11pt' or '12pt').
-#'pointsize': '10pt',
-
-# Additional stuff for the LaTeX preamble.
-#'preamble': '',
-}
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-# author, documentclass [howto, manual, or own class]).
-latex_documents = [
- ('index', 'Soledad.tex', u'Soledad Documentation',
- u'LEAP Encryption Access Project', 'manual'),
-]
-
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-#latex_logo = None
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-#latex_use_parts = False
-
-# If true, show page references after internal links.
-#latex_show_pagerefs = False
-
-# If true, show URL addresses after external links.
-#latex_show_urls = False
-
-# Documents to append as an appendix to all manuals.
-#latex_appendices = []
-
-# If false, no module index is generated.
-#latex_domain_indices = True
-
-
-# -- Options for manual page output ---------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [
- ('index', 'soledad', u'Soledad Documentation',
- [u'LEAP Encryption Access Project'], 1)
-]
-
-# If true, show URL addresses after external links.
-#man_show_urls = False
-
-
-# -- Options for Texinfo output -------------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-# dir menu entry, description, category)
-texinfo_documents = [
- ('index', 'Soledad', u'Soledad Documentation',
- u'LEAP Encryption Access Project', 'Soledad', 'One line description of project.',
- 'Miscellaneous'),
-]
-
-# Documents to append as an appendix to all manuals.
-#texinfo_appendices = []
-
-# If false, no module index is generated.
-#texinfo_domain_indices = True
-
-# How to display URL addresses: 'footnote', 'no', or 'inline'.
-#texinfo_show_urls = 'footnote'
-
-# If true, do not generate a @detailmenu in the "Top" node's menu.
-#texinfo_no_detailmenu = False
diff --git a/docs/sphinx/index.rst b/docs/sphinx/index.rst
deleted file mode 100644
index 6800ee42..00000000
--- a/docs/sphinx/index.rst
+++ /dev/null
@@ -1,26 +0,0 @@
-.. Soledad documentation master file, created by
- sphinx-quickstart on Mon Feb 17 17:54:47 2014.
- You can adapt this file completely to your liking, but it should at least
- contain the root `toctree` directive.
-
-Soledad documentation
-=====================
-
-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
-
- client
- attachments
- server
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
diff --git a/docs/sphinx/requirements.pip b/docs/sphinx/requirements.pip
deleted file mode 100644
index 39055139..00000000
--- a/docs/sphinx/requirements.pip
+++ /dev/null
@@ -1,2 +0,0 @@
-sphinx
-sphinxcontrib-zopeext
diff --git a/docs/sphinx/server.rst b/docs/sphinx/server.rst
deleted file mode 100644
index 4f99f266..00000000
--- a/docs/sphinx/server.rst
+++ /dev/null
@@ -1,71 +0,0 @@
-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-<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.
diff --git a/docs/sphinx/sync.rst b/docs/sphinx/sync.rst
deleted file mode 100644
index b9d4c858..00000000
--- a/docs/sphinx/sync.rst
+++ /dev/null
@@ -1,35 +0,0 @@
-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.
-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.
-
-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
-* **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.
-
-it is essential that all the uploads and downloads are sequential: documents must be added in order. the download happens in parallel, but then locally they are added sequentially to the local db.