9 files changed, 427 insertions, 45 deletions

diff --git a/README.md b/README.md
index 7369cf0..de8ddf7 100644
--- a/README.md
+++ b/README.md
@@ -9,55 +9,12 @@ Simply install into the same environment as Mailman Core and follow configuratio
 ```
 pip install mailman-pgp
 ```
+For more, see [install.rst](docs/install.rst)
 
 ## Configuration
 
 See [mailman.cfg](src/mailman_pgp/config/mailman.cfg) for example configuration which enables the mailman-pgp plugin in Mailman Core and sets up the plugin configuration to the example [mailman_pgp.cfg](src/mailman_pgp/config/mailman_pgp.cfg).
-
-```ini
-[db]
-# db path the PGP plugin will use to store list/user configuration (not keys!).
-url = sqlite:////$DATA_DIR/pgp.db
-
-
-[keydirs]
-# Key directory used to store user public keys.
-user_keydir = $DATA_DIR/pgp/user_keydir/
-
-# Key directory used to store list keypairs.
-list_keydir = $DATA_DIR/pgp/list_keydir/
-
-# Key directory used to store archive public keys.
-archive_keydir = $DATA_DIR/pgp/archive_keydir/
-
-
-[keypairs]
-# Whether to autogenerate the list key on list creation.
-autogenerate = yes
-
-# Type of primary list key and its size.
-# Format: type:size
-# type is one of:
-#     RSA, DSA, ECDSA.
-# size is the key size or curve name for ECDSA, which can be one of:
-#     nistp256, nistp384, nistp521, brainpoolP256r1, brainpoolP384r1,
-#     brainpoolP512r1, secp256k1
-primary_key = RSA:4096
-
-# Type of list encryption subkey and its size.
-# Format: type:size
-# type is one of:
-#     RSA, ECDH
-# size is the key size or curve name for ECDH, which can be one of:
-#     nistp256, nistp384, nistp521, brainpoolP256r1, brainpoolP384r1,
-#     brainpoolP512r1, secp256k1
-sub_key = RSA:4096
-
-
-[queues]
-# The queue to which processed incoming messages are passed.
-in = in_default
-```
+For more, see [config.rst](docs/config.rst).
 
 ## License
     
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 0000000..17425b6
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = mailman-pgp
+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)
\ No newline at end of file
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..6c26935
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# mailman-pgp documentation build configuration file, created by
+# sphinx-quickstart on Mon Aug 21 23:41:37 2017.
+#
+# 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.
+
+# 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.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- 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.doctest',
+    'sphinx.ext.todo',
+    'sphinx.ext.viewcode']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = 'mailman-pgp'
+copyright = '2017, Jan Jancar'
+author = 'Jan Jancar'
+
+# 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.2.1'
+# The full version, including alpha/beta/rc tags.
+release = '0.2.1'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True
+
+
+# -- 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 = 'alabaster'
+
+# 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 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']
+
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'mailman-pgpdoc'
+
+
+# -- 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': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# 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 = [
+    (master_doc, 'mailman-pgp.tex', 'mailman-pgp Documentation',
+     'Jan Jancar', 'manual'),
+]
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'mailman-pgp', 'mailman-pgp Documentation',
+     [author], 1)
+]
+
+
+# -- 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 = [
+    (master_doc, 'mailman-pgp', 'mailman-pgp Documentation',
+     author, 'mailman-pgp', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+
+
diff --git a/docs/config.rst b/docs/config.rst
new file mode 100644
index 0000000..b56641e
--- /dev/null
+++ b/docs/config.rst
@@ -0,0 +1,133 @@
+=============
+Configuration
+=============
+
+To enable and configure the mailman-pgp plugin, both Mailman Core needs to be instructed to find the correct plugin
+package and class to find mailman-pgp and mailman-pgp needs to be configured to work correctly.
+
+Mailman
+=======
+
+Example additions to mailman.cfg to enable mailman-pgp::
+
+    # Setup the mailman-pgp plugin under the `pgp` name. To use the django-pgpmailman
+    # web UI. The `MAILMAN_PGP_PLUGIN_NAME` in its project settings.py must be set
+    # to the name of the plugin, as thats where Mailman roots the plugins REST api
+    # endpoint.
+    [plugin.pgp]
+    class: mailman_pgp.plugin.PGPMailman
+    path: mailman_pgp
+    enable: yes
+    configuration: python:mailman_pgp.config.mailman_pgp
+
+    # Use the custom PGP enabled deliver callable, performs the signing and encryption
+    # on PGP enabled lists which are configured to do so.
+    [mta]
+    outgoing: mailman_pgp.mta.deliver.deliver
+
+    # Use the custom PGP enabled runner on the default `in` queue.
+    [runner.in]
+    class: mailman_pgp.runners.incoming.PGPIncomingRunner
+
+    # This runners name needs to be the same as the `[queues].in` config option in
+    # the mailman-pgp config file. It runs the default IncomingRunner on a queue
+    # of a different name, so that messages come into the mailman-pgp incoming runner
+    # and can be then passed to the default incoming runner, defined here.
+    [runner.in_default]
+    class: mailman.runners.incoming.IncomingRunner
+
+
+Plugin
+======
+
+Default PGP config::
+
+    [db]
+    # db path the PGP plugin will use to store list/user configuration (not keys!).
+    url: sqlite:////$DATA_DIR/pgp.db
+
+
+    [archiving]
+    # The directory where the local mbox archiver will save messages.
+    mailbox_dir: $ARCHIVE_DIR/pgp/mbox
+
+    # The directory where the local maildir archiver will save messages.
+    maildir_dir: $ARCHIVE_DIR/pgp/maildir
+
+
+    [keydirs]
+    # Key directory used to store user public keys.
+    user_keydir: $DATA_DIR/pgp/user_keydir/
+
+    # Key directory used to store list keypairs.
+    list_keydir: $DATA_DIR/pgp/list_keydir/
+
+    # Key directory used to store archive public keys.
+    archive_keydir: $DATA_DIR/pgp/archive_keydir/
+
+
+    [keypairs]
+    # Whether to autogenerate the list key on list creation.
+    autogenerate: yes
+
+    # Type of primary list key and its size.
+    # Format: type:size
+    # type is one of:
+    #     RSA, DSA, ECDSA.
+    # size is the key size or curve name for ECDSA, which can be one of:
+    #     nistp256, nistp384, nistp521, brainpoolP256r1, brainpoolP384r1,
+    #     brainpoolP512r1, secp256k1
+    primary_key: RSA:4096
+
+    # Type of list encryption subkey and its size.
+    # Format: type:size
+    # type is one of:
+    #     RSA, ECDH
+    # size is the key size or curve name for ECDH, which can be one of:
+    #     nistp256, nistp384, nistp521, brainpoolP256r1, brainpoolP384r1,
+    #     brainpoolP512r1, secp256k1
+    sub_key: RSA:4096
+
+    # Shred keypair on list deletion? Shredding tries to securely erase the file
+    # by overwriting it with random data many times. Will be only performed if
+    # the `delete` option is also set to yes.
+    shred: yes
+
+    # A command, that is run when shredding the list key (if shred is set).
+    # It is passed the list key path as an argument.
+    # If empty, mailman-pgp will try to shred the listkey itself.
+    # Some Linux distributions provide the `shred` command from GNU coreutils, or
+    # similar.
+    shred_command:
+
+    # Delete list keypair on list deletion.
+    delete: yes
+
+    [queues]
+    # The queue to which processed incoming messages are passed. Must be a name of
+    # a queue which is managed by the Mailman IncomingRunner.
+    in: in_default
+
+
+    [misc]
+    # The lifetime for `key change` request confirmation.
+    change_request_lifetime: 1d
+
+    # Collect all signature hashes of successful postings to a PGP enabled mailing
+    # list for signature replay checking.
+    collect_sig_hashes: yes
+
+
+    [rest]
+    # Allow the accessing of a list private key through the REST API.
+    # This is necessary for the django-pgpmailman web ui to allow a list owner
+    # to export the list private key.
+    allow_read_private_key: yes
+
+    # Allow the modification of a list private key through the REST API.
+    # This is necessary for the django-pgpmailman web ui to allow a list owner
+    # to change the list private key.
+    allow_write_private_key: yes
+
+    # Allow the accessing of this plugin configuration through the REST API.
+    allow_read_config: yes
diff --git a/docs/encryption.rst b/docs/encryption.rst
new file mode 100644
index 0000000..96e8472
--- /dev/null
+++ b/docs/encryption.rst
@@ -0,0 +1,11 @@
+========================
+List encryption settings
+========================
+
+Mailman-pgp stores per-list encryption configuration. The defaults are listed
+in the parentheses after the attribute name.
+
+ - ``nonencrypted_msg_action(Action.reject)``, an action to take when a message
+ is received not encrypted.
+ - ``encrypt_outgoing(True)``, whether to encrypt the outgoing postings to the
+ subscribers keys.
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..d82a78e
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,21 @@
+Welcome to mailman-pgp's documentation!
+=======================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   install
+   config
+   keys
+   signatures
+   encryption
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/docs/install.rst b/docs/install.rst
new file mode 100644
index 0000000..152c92d
--- /dev/null
+++ b/docs/install.rst
@@ -0,0 +1,12 @@
+============
+Installation
+============
+
+Mailman-pgp currently depends on a development version of both `Mailman <https://gitlab.com/mailman/mailman>`_ and `PGPy <https://github.com/SecurityInnovation/PGPy>`_.
+However, the required changes are slowly getting merged into both. Until they are fully merged, doing::
+
+    pip install mailman-pgp
+
+pulls in those development versions from `J08nY/mailman/plugin <https://gitlab.com/J08nY/mailman/tree/plugin>`_, `J08nY/PGPy/dev <https://github.com/J08nY/PGPy/tree/dev>`_.
+
+See :doc:`config` for configuration which enables the mailman-pgp plugin after installation.
\ No newline at end of file
diff --git a/docs/keys.rst b/docs/keys.rst
new file mode 100644
index 0000000..8e07c62
--- /dev/null
+++ b/docs/keys.rst
@@ -0,0 +1,39 @@
+====
+Keys
+====
+
+Mailman-pgp stores PGP keys in ASCII-Armored files in directories.
+The ``[keydirs]`` section of the config specifies three directories, one for list
+keypairs, one for user public keys(per-address) and one for list archive public keys.
+
+List keypairs
+=============
+
+Mailman-pgp can be configured to generate the list keypair on PGP enabled list creation.
+This is done via the ``[keypairs].autogenerate`` option.
+
+The type and size of the key and subkey that is generated is also configurable,
+via the ``[keypairs].primary_key`` and ``.sub_key`` options. The options are listed
+in the `src/mailman_pgp/config/mailman_pgp.cfg` config file and also in
+the :doc:`config` docs.
+
+Mailman-pgp generates keys that look like so::
+
+    pub   secp256k1/0x651AD9483EB388DD 2017-08-21 [SC]
+          Key fingerprint = 2767 BEE0 E502 00DA 4A2F  131E 651A D948 3EB3 88DD
+    uid                             Name <name@example.com>
+    uid                             Name <name-request@example.com>
+    sub   secp256k1/0x5D972B21F6D1C7D7 2017-08-21 [E]
+
+
+For a list called ``name`` at the ``example.com`` domain, with the ``ECDSA`` and ``ECDH`` algorithms over secp256k1
+, respectively.
+
+As the list keypair is stored as an ASCII-Armored text file in the ``[keydirs].list_keydir``
+directory, named ``<list-id>.asc`` , replacing it with a custom keypair just works. However, doing so to
+an established mailing list with subscribers, might confuse them, and if they
+still encrypt to the old key, mailman-pgp will bounce their messages.
+
+Mailman-pgp can delete and or shred the list keypair on list deletion, this
+is also configured in the ``[keypairs]`` config section, via ``shred``, ``shred_command`` and
+``delete`` options.
\ No newline at end of file
diff --git a/docs/signatures.rst b/docs/signatures.rst
new file mode 100644
index 0000000..2de29b8
--- /dev/null
+++ b/docs/signatures.rst
@@ -0,0 +1,29 @@
+=======================
+List signature settings
+=======================
+
+Mailman-pgp stores a per-list signature handling configuration. Several actions
+and attributes are configurable. They are processed in order they are defined 
+here, if one matches and the action set is not ``Action.defer`` it is taken on
+the message. Defaults are listed in the parentheses after the attribute name.
+
+ - ``unsigned_msg_action(Action.reject)``, is taken if a message is not recognized
+   as PGP signed (PGP/MIME and inline PGP is tried).
+ - ``inline_pgp_action(Action.defer)``, is taken if the message is Inline PGP
+   signed.
+ - ``expired_sig_action(Action.reject)``, is taken if the message signature or
+   key its made by is expired at the moment of verification.
+ - ``revoked_sig_action(Action.reject)``, is taken if the key that signed the
+   message was revoked.
+ - ``invalid_sig_action(Action.reject)``, is taken if the message signature doesn't
+   verify or is otherwise invalid.
+ - ``duplicate_sig_action(Action.reject)``, is taken if the message contains a signature
+   by the senders key that was previously sent to the mailing list. Signature hashes
+   are collected only if the ``[misc]collect_sig_hashes`` config option is set to yes.
+ 
+Other options set how Mailman-pgp handles the signature:
+
+ - ``strip_original_sig(False)``, whether to strip the original users signature
+   (if any), from the posting.
+ - ``sign_outgoing(False)``, whether outgoing postings should be signed by the
+   list key.