diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Makefile | 20 | ||||
| -rw-r--r-- | docs/conf.py | 160 | ||||
| -rw-r--r-- | docs/config.rst | 133 | ||||
| -rw-r--r-- | docs/encryption.rst | 11 | ||||
| -rw-r--r-- | docs/index.rst | 21 | ||||
| -rw-r--r-- | docs/install.rst | 12 | ||||
| -rw-r--r-- | docs/keys.rst | 39 | ||||
| -rw-r--r-- | docs/signatures.rst | 29 |
8 files changed, 425 insertions, 0 deletions
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. |