remail: Initial import

Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
This commit is contained in:
Thomas Gleixner 2019-09-22 22:38:59 +02:00
commit 60f6698e52
48 changed files with 5299 additions and 0 deletions

24
.gitignore vendored Normal file
View file

@ -0,0 +1,24 @@
# Normal rules
*.bz2
*.diff
*.gz
*.patch
*.orig
*.rej
*.tar
*.xz
# Editor artifacts
*~
\#*#
# Quilt's files
patches
series
.pc/
# Python artifacts
*.pyc
# Documentation artifacts
Documentation/output/

14
COPYING Normal file
View file

@ -0,0 +1,14 @@
remail is provided under:
SPDX-License-Identifier: GPL-2.0-only
Being under the terms of the GNU General Public License version 2 only,
according with:
LICENSES/GPL-2.0
In addition, other licenses may also apply. Please see:
Documentation/license-rules.rst
for more details.

20
Documentation/Makefile Normal file
View file

@ -0,0 +1,20 @@
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
SPHINXPROJ = remail
SOURCEDIR = .
BUILDDIR = output
# 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)

163
Documentation/conf.py Normal file
View file

@ -0,0 +1,163 @@
# -*- coding: utf-8 -*-
#
# remail documentation build configuration file, created by
# sphinx-quickstart on Tue May 15 16:12:59 2018.
#
# 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('.'))
import glob
# -- 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 = []
# Add any paths that contain templates here, relative to this directory.
templates_path = ['sphinx_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 = u'remail'
copyright = u'2018, Thomas Gleixner <tglx@linutronix.de>'
author = u'Thomas Gleixner <tglx@linutronix.de>'
# 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 = u''
# The full version, including alpha/beta/rc tags.
release = u''
# 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 = 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 = 'nature'
# 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 = ['sphinx_static']
# -- Options for HTMLHelp output ------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'remaildoc'
# -- 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, 'remail.tex', u'remail Documentation',
u'Thomas Gleixner \\textless{}tglx@linutronix.de\\textgreater{}', '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, 'remail', u'remail Documentation',
# [author], 1),
]
for f in glob.glob('man1/*.rst'):
src = f.replace('.rst', '')
dst = src.split('/')[1]
man_pages.append((src, dst, u'%s Documentation' % dst, [author], 1))
for f in glob.glob('man5/*.rst'):
src = f.replace('.rst', '')
dst = src.split('/')[1]
man_pages.append((src, dst, u'%s Documentation' % dst, [author], 5))
# -- 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, 'remail', u'remail Documentation',
author, 'remail', 'One line description of project.',
'Miscellaneous'),
]

View file

@ -0,0 +1,176 @@
.. SPDX-License-Identifier: GPL-2.0
.. _remail_configuration:
remail configuration guide
==========================
Introduction
------------
The configuration files are simple yaml files which only use the very basic
yaml components. The yaml file does not have a schema yet, but the
configuration parser is doing extensive verification.
See :ref:`remail_daemon_config_man` for a detailed explanation of the
configuration files and the configuration items.
The examples directory in Documentation contains a full dummy configuration
for two lists including fully documented yaml files.
Work directory
--------------
The work directory structure is fixed and is documented in the man page in
the section :ref:`config_dir_struct`.
A comfortable way to manage the configuration is git. The base
configuration directory and the actual list configuration directories are
in separate git trees so that they can be maintained by different people
with different permissions.
Key considerations
------------------
Private keys
^^^^^^^^^^^^
In order to encrypt incoming mail and to sign outgoing mail the list daemon
needs access to the private GPG and S/MIME keys of each list.
The keys must be stored without password.
This is not a security issue because if the keys would have passwords then
the password needs to be part of the configuration file.
If the list configuration or the list server is compromised all bets are
off. Having a password on the keys would not make any difference.
Public keys
^^^^^^^^^^^
The public GPG keys of the subscribers in the mailing list specific keyring
are always trusted by remail. The list administrator is responsible for
verifying the authenticity of the subscribers key, so extensive trust
management does not make sense and just complicates the handling.
remail does not try to update the keyring at any time. This is in the
responsibility of the list administrator. Automatic updates are not a
really good idea in the light of the recent attacks on the PGP
infrastructure.
The public S/MIME certificates are verified against the CA certificates
which are provided and managed by the remail base administrator as part of
the base configuration.
Key storage format
------------------
GPG
^^^
GPG keys are stored using the storage format of gnugp. Create and manage
the private keys and the subscriber keyrings with the GPG tool of your
choice.
S/MIME
^^^^^^
S/MIME .key and .crt files are stored in pem format and have to follow
the following naming convention.
Private keys (list keys):
email@address.domain.key
Public certificates (list and subscribers):
email@address.domain.crt
Using git for configuration management
--------------------------------------
As seen above the base configuration directory contains the private keys
for the lists. So the administrator has to ensure that the git repository
which is used to push the configuration to is properly protected. Also the
machine used for updating the base configuration repository should not be
accessible by unpriviledged users.
The incomplete list of things to avoid under all circumstances:
- Push the base configuration to a public hosted repository server like
github, gitlab etc.
- Keep the base configuration on an easy accessible machine if the data is
not sufficiently protected by encryption
- Keep the base configuration unencrypted on a backup medium.
The list configuration does not contain strictly secret information, but
the pure existance of an incident list and the list of involved people
might give a hint in which area the handled issue might be. So in general
it is recommended to hide a list configuration repository from public and
unpriviledged access as well, but in case of an leak the potential damage
is way smaller than the one of leaking the base configuration which
contains the private keys.
Base configuration
------------------
To configure the list daemon the following configuration files need to be
created or modified:
- remail.yaml
remail.yaml:
The main configuration file for the remail daemon. See
:ref:`remail_daemon_config_man` for a detailed information of the file.
List configuration
------------------
For each enabled mailing list the following configuration files need to be
created or modified:
- list.yaml
- template_welcome
- template_admin
list.yaml:
The list specific configuration file for the mailing list. It contains
the subscriber list. See :ref:`remail_daemon_config_man` for a detailed
information of the file.
template_admin:
The mail template for mail to the list admin(s).
template_welcome:
The mail template for mail to welcome new subscribers.
Public mail
-----------
Request or configure a user account for receiving list mail. This mail
account acts as a catch all for the list, the list-owner and list-bounce
addresses. If more than one mailing list is served by the list daemon then
the user mail account can receive all mails for the lists. remail finds the
appropriate mailing list for the various addresses.
remail does not retrieve mail from a public mail server as this is outside
the scope of remail and depends on the particular setup. remail expects the
incoming mails to be delivered into a maildir. Tools like getmail,
fetchmail can handle that as well as SMTP servers.
Local mail transport
--------------------
remail delivers the outgoing mail to the local SMTP server. The
configuration for the SMTP server to relay the mails to the public facing
machines is outside the scope of this documentation and depends on the SMTP
server variant you are using.

View file

@ -0,0 +1 @@

View file

@ -0,0 +1 @@

View file

@ -0,0 +1 @@

View file

@ -0,0 +1 @@

View file

@ -0,0 +1 @@

View file

@ -0,0 +1,41 @@
#
# Recrypting mailing list configuration file for list1
#
# The list subscribers
subscribers:
# Format:
# email address:
# name: Real name of the subscriber
# enabled: Subscriber is enabled (if omitted defaults to False)
# use_smime: True/False (Use S/MIME for encryption. If omitted defaults to False)
# fingerprint: GPG fingerprint (Not required when use_smime == True)
# gpg_plain: Plain text inline GPG encryption (If omitted defaults to False)
# aliases: List of alias addresses which are valid for posting (moderated list)
#
# Note: Use spaces for spacing not tabs
dev1@some.domain:
name: Developer One
enabled: True
use_smime: True
dev2@some.domain:
name: Developer Two
enabled: False
dev3@other.domain:
name: Developer Three
enabled: True
fingerprint: 40_CHARACTER_PGP_FINGERPRINT
aliases:
- dev3@dev3.domain
- hckr@dev3.domain
dev4@other.domain:
name: Developer Four
enabled: True
fingerprint: 40_CHARACTER_PGP_FINGERPRINT
gpg_plain: True

View file

@ -0,0 +1,6 @@
Subject: [LIST1] Remail failure report
User-Agent: Remail
Content-Type: text/plain
Content-Disposition: inline
The following problems have been encountered with the list list1:

View file

@ -0,0 +1,26 @@
Subject: Welcome to the list1 mailing-list
User-Agent: Remail
Content-Type: text/plain
Content-Disposition: inline
Dear $NAME!
This is an automated email from your friendly mailing-list update bot. This
email is sent to you because you got (re-)subscribed to the list1
mailing-list.
This email to you is signed either with the list's PGP key or the list's
S/MIME certificate depending on your encryption preference, so your
email-client should have already retrieved the PGP key or the S/MIME
certificate for you.
The list's email address is: list1@list.domain
To send email to the list, encrypt it either with the list's PGP key or the
list's S/MIME certificate. Note, that the subject line of the email is not
encrypted, so you should be careful about that.
If you have questions, please contact the list administrator by email. The
administrators email address is: list1-owner@list.domain

View file

@ -0,0 +1 @@

View file

@ -0,0 +1,41 @@
#
# Recrypting mailing list configuration file for list2
#
# The list subscribers
subscribers:
# Format:
# email address:
# name: Real name of the subscriber
# enabled: Subscriber is enabled (if omitted defaults to False)
# use_smime: True/False (Use S/MIME for encryption. If omitted defaults to False)
# fingerprint: GPG fingerprint (Not required when use_smime == True)
# gpg_plain: Plain text inline GPG encryption (If omitted defaults to False)
# aliases: List of alias addresses which are valid for posting (moderated list)
#
# Note: Use spaces for spacing not tabs
dev1@some.domain:
name: Developer One
enabled: True
use_smime: True
dev2@some.domain:
name: Developer Two
enabled: False
dev3@other.domain:
name: Developer Three
enabled: True
fingerprint: 40_CHARACTER_PGP_FINGERPRINT
aliases:
- dev3@dev3.domain
- hckr@dev3.domain
dev4@other.domain:
name: Developer Four
enabled: True
fingerprint: 40_CHARACTER_PGP_FINGERPRINT
gpg_plain: True

View file

@ -0,0 +1,6 @@
Subject: [LIST2] Remail failure report
User-Agent: Remail
Content-Type: text/plain
Content-Disposition: inline
The following problems have been encountered with the list list2:

View file

@ -0,0 +1,26 @@
Subject: Welcome to the list2 mailing-list
User-Agent: Remail
Content-Type: text/plain
Content-Disposition: inline
Dear $NAME!
This is an automated email from your friendly mailing-list update bot. This
email is sent to you because you got (re-)subscribed to the list2
mailing-list.
This email to you is signed either with the list's PGP key or the list's
S/MIME certificate depending on your encryption preference, so your
email-client should have already retrieved the PGP key or the S/MIME
certificate for you.
The list's email address is: list2@list.domain
To send email to the list, encrypt it either with the list's PGP key or the
list's S/MIME certificate. Note, that the subject line of the email is not
encrypted, so you should be careful about that.
If you have questions, please contact the list administrator by email. The
administrators email address is: list2-owner@list.domain

View file

@ -0,0 +1 @@

View file

@ -0,0 +1,116 @@
#
# Remail base configuration file for the remail list server
#
# Note: YAML requires spaces. Do not use TABs
#
# Enabled. If False all other items are ignored. Set to true to get it starting
enabled: True
# Set to True to enable SMTP delivery. Set only to False for testing or
# troubleshooting
use_smtp: True
# S/MIME
smime:
# Verify CA certs. Only disable for troubleshooting
verify: True
# GPG
gpg:
# Trust your keys always. That avoids manual fiddling with trust-db
always_trust: True
# List mail should always be signed with the lists key
sign: True
# The mailing lists
lists:
# The list name
list1:
# Set to True if the list is enabled
enabled: True
# Set to True if the list should be moderated
# If set, only subscribers can post to the list
# Non subscriber mails are forwarded to the list admins
moderated: True
archive:
use_maildir: True
# Set to true if the incoming mails should be archived
# locally in a mailbox/dir unmodified before decryption
archive_incoming: True
# Set to true if the incoming mails should be archived
# locally in a mailbox/dir after decrypting them
archive_plain: True
# The list account itself
listaccount:
list1@list.domain:
name: list1
fingerprint: 40_CHARACTER_PGP_FINGERPRINT
# The list admins
admins:
# Format:
# email address:
# name: Real name of the subscriber
# enabled: Subscriber is enabled (if omitted defaults to False)
# use_smime: True/False (Use S/MIME for encryption. If omitted defaults to False)
# fingerprint: GPG fingerprint (Not required when use_smime == True)
# gpg_plain: Plain text inline GPG encryption (If omitted defaults to False)
admin1@admin.domain:
name: Admin one
use_smime: True
enabled: True
admin2@admin2.domain:
name: Admin2
fingerprint: 40_CHARACTER_PGP_FINGERPRINT
gpg_plain: True
enabled: True
# The list name
list2:
# Set to True if the list is enabled
enabled: True
# Set to True if the list should be moderated
# If set, only subscribers can post to the list
# Non subscriber mails are forwarded to the list admins
moderated: True
archive:
use_maildir: True
# Set to true if the incoming mails should be archived
# locally in a mailbox/dir unmodified before decryption
archive_incoming: True
# Set to true if the incoming mails should be archived
# locally in a mailbox/dir after decrypting them
archive_plain: False
# The list account itself
listaccount:
list1@list.domain:
name: list1
fingerprint: 40_CHARACTER_PGP_FINGERPRINT
# The list admins
admins:
# Format:
# email address:
# name: Real name of the subscriber
# enabled: Subscriber is enabled (if omitted defaults to False)
# use_smime: True/False (Use S/MIME for encryption. If omitted defaults to False)
# fingerprint: GPG fingerprint (Not required when use_smime == True)
# gpg_plain: Plain text inline GPG encryption (If omitted defaults to False)
admin2@admin2.domain:
name: Admin2
fingerprint: 40_CHARACTER_PGP_FINGERPRINT
enabled: True
admin3@admin3.domain:
name: Admin three
enabled: False

80
Documentation/index.rst Normal file
View file

@ -0,0 +1,80 @@
.. SPDX-License-Identifier: GPL-2.0
.. remail documentation master file
Welcome to remail's documentation!
==================================
.. toctree::
:maxdepth: 3
:caption: Contents:
Introduction
------------
.. toctree::
:maxdepth: 3
introduction.rst
Licensing
---------
Describes the licensing rules for the remail source code.
.. toctree::
:maxdepth: 3
license-rules.rst
Installation
------------
Installation guidelines
.. toctree::
:maxdepth: 3
installation.rst
Configuration
-------------
Configuration guidelines
.. toctree::
:maxdepth: 3
configuration.rst
Operation
----------
Information about operation
.. toctree::
:maxdepth: 3
operation.rst
Usage
-----
Usage guidelines (man pages)
.. toctree::
:maxdepth: 3
man1/remail_daemon.rst
man1/remail_chkcfg.rst
man5/remail_daemon.config.rst
Indices and tables
==================
* :ref:`genindex`

View file

@ -0,0 +1,58 @@
.. SPDX-License-Identifier: GPL-2.0
.. _remail_installation:
remail installation guide
=========================
General
-------
The recommended installation procedure is via the package management system
of your distribution. Manual installation is surely possible and the
various bits and pieces including their default or recommended locations on
the target are documented in the packaging files.
By default the daemon is disabled as it requires configuration.
Protecting the system
---------------------
Run the list daemon on a machine which is not publicly accessible and
ensure that no untrusted users can access it. It can be run in a VM with
the sole purpose of running the encrypted mailing list. As the private keys
of the list are stored on that machine the setup requires deep
understanding of IT security. It's outside the scope of this documentation
to provide guidance on this.
Dependencies
------------
remail requires Python 3 and depends on the following python packages:
- python3-M2Crypto
- python3-gnupg
- python3-yaml
Note, that on Debian 10 python3-M2Crypto is not available, but can be
installed as a Debian package from the testing repository.
Further the systems needs to have:
- A mail transport agent which handles the transport of the mails to an
outgoing SMTP server.
- A mail retriever agent or some other mechanism which can fetch or
handle incoming mail and deliver it to remails maildir.
The initial deployment of the list daemon which was used to handle
development of mitigations for embargoed hardware security vulnerabilities
uses postfix and getmail, but that's only one of various possibilites.
As the choice of tools depends on the setup and the situation under which
the system is deployed, there is no documentation provided here. It's a
prerequisite that an administrator who wants to deploy remail is familiar
with these kind of tools.

View file

@ -0,0 +1,95 @@
.. SPDX-License-Identifier: GPL-2.0
.. _remail_introduction:
Introduction
============
remail is a very simplistic mailing list tool which provides encryption.
Why yet another mailing list tool?
----------------------------------
The handling of the embargoed hardware security issues made it necessary
to have a encrypted mailing list. Managing Cc lists manually and dealing
with the odd GPG integrations in the mail clients is just not a workable
solution.
There are only a few Open Source implementations of encrypted mailing lists
available. Some of them are abandoned projects. The alive ones have their
own set of shortcomings. One of them supports only S/MIME. The other
supports only PGP, but did not survive testing in a real world
deployment. Repairing ruby code and dis-tangling the thing from its weird
daemons and other over-engineered features was certainly not a project for
the weekend.
After thinking about it for a while, I recognized that for the purpose at
hand the tool can be very simplistic. Using existing tools like getmail and
SMTP servers plus the knowledge about the gory details of emails which I
gained by writing mail handling scripts in python for my daily work, made
it possible to implement it in a rather short time.
What it does
------------
remail reads mail from a maildir, decrypts it with the mailing list private
key and re-encrypts it for every enabled subscriber. The resulting mails are
delivered to the localhost's SMTP server.
remail supports S/MIME and PGP on both ends.
No MUA functionality and no complicated SMTP delivery mechanisms are
required. They all exist in well maintained tools already.
The list configuration is a simple yaml file and is maintained manually
with your favorite text editor. Building tools around that is not part of
this project and there are many existing ways to handle that conveniently.
The proven in use mechanism is to have the configuration files in git and
let the mailing list system either check for updates regularly or get some
external notification that a new configuration is available.
What it does not
----------------
It does not care about mail transport on the receiving side, no POP or IMAP
support as this can be handled by tools like getmail.
It does not care about complex mail transport on the sending side as this
can be handled by SMTP servers like postfix or exim.
It has no integration into SMTP server transports or filters because it
makes no sense to deploy such a sensitive mechanism on a public facing
machine.
It does not come with GUI and managenent tools. A crypto mailing list is
subscribers only for obvious reasons and not meant to handle a large amount
of subscribers. It's meant for secure communications of a small group of
people without having the hassle of keeping Cc lists up to date and
encrypting for every recipient.
How it works
------------
.. image:: remail.svg
The mailing list has the usual post, bounce and owner email addresses on a
public mail server. These addresses are aliased to a user account. The
mails are stored in the users inbox or forwarded to a protected machine.
The mailing list software runs on a protected and separated machine behind
firewalls and access barriers like any other sensitive application.
The mail is retrieved from the public facing machine by any of the existing
mechanisms, e.g. getmail, fetchmail or any MTA which can deliver mail to a
maildir. remail does not implement any transport on the incoming side as
there are good tools available which can handle the requirements of a
particular setup.
The list daemon retrieves the mails from the maildir and selects the
appropriate list via the 'To' header. It then decrypts the incoming mail,
re-encrypts it for each subscriber and delivers it to the local SMTP server
which takes care of relaying it to the public facing SMTP server.

View file

@ -0,0 +1,161 @@
.. SPDX-License-Identifier: GPL-2.0
.. _remail_licensing_rules:
remail licensing rules
======================
The remail project is provided under the terms of the GNU General Public
License version 2 only (GPL-2.0-only), as provided in LICENSES/GPL-2.0.
This documentation file provides a description of how each source file
should be annotated to make its license clear and unambiguous.
It doesn't replace the projects license.
The license described in the COPYING file applies to the project source
as a whole, though individual source files can have a different license
which is required to be compatible with the GPL-2.0-only::
GPL-2.0-or-later : GNU General Public License v2.0 or later
Aside from that, individual files can be provided under a dual license,
e.g. one of the compatible GPL variants and alternatively under a
permissive license like BSD, MIT etc.
The common way of expressing the license of a source file is to add the
matching boilerplate text into the top comment of the file. Due to
formatting, typos etc. these "boilerplates" are hard to validate for
tools which are used in the context of license compliance.
An alternative to boilerplate text is the use of Software Package Data
Exchange (SPDX) license identifiers in each source file. SPDX license
identifiers are machine parsable and precise shorthands for the license
under which the content of the file is contributed. SPDX license
identifiers are managed by the SPDX Workgroup at the Linux Foundation and
have been agreed on by partners throughout the industry, tool vendors, and
legal teams. For further information see https://spdx.org/
The remail prokect requires the precise SPDX identifier in all source
files. The valid identifiers used in the remail project are explained in
the section `License identifiers`_ and have been retrieved from the
official SPDX license list at https://spdx.org/licenses/ along with the
license texts.
License identifier syntax
-------------------------
1. Placement:
The SPDX license identifier in source files shall be added at the first
possible line in a file which can contain a comment. For the majority
or files this is the first line, except for executable scripts which
require the '#!PATH_TO_INTERPRETER' in the first line. For those
scripts the SPDX identifier goes into the second line.
|
2. Style:
The SPDX license identifier is added in form of a comment. The comment
style depends on the file type::
scripts: # SPDX-License-Identifier: <SPDX License Expression>
.py: # SPDX-License-Identifier: <SPDX License Expression>
.rst: .. SPDX-License-Identifier: <SPDX License Expression>
|
3. Syntax:
A <SPDX License Expression> is either an SPDX short form license
identifier found on the SPDX License List. When multiple licenses apply,
an expression consists of keywords "AND", "OR" separating
sub-expressions and surrounded by "(", ")" .
License identifiers for licenses like [L]GPL with the 'or later' option
are constructed by using a "-or-later" for indicating the 'or later'
option.::
# SPDX-License-Identifier: GPL-2.0-or-later
OR should be used if the file is dual licensed and only one license is
to be selected. For example::
# SPDX-License-Identifier: GPL-2.0-only OR BSD-3-Clause
AND should be used if the file has multiple licenses whose terms all
apply to use the file. For example, if code is inherited from another
project and permission has been given to put it in the remail project,
but the original license terms need to remain in effect::
# SPDX-License-Identifier: GPL-2.0-only AND MIT
License identifiers
-------------------
The licenses currently used, as well as the licenses for code added to the
project can be found in the LICENSES directory.
Whenever possible these licenses should be used as they are known to be
fully compatible and widely used.
The files in this directory contain the full license text and metatags.
The file names are identical to the SPDX license identifier which shall be
used for the license in source files.
Examples::
LICENSES/GPL-2.0
Contains the GPL version 2 license text and the required metatags:
Metatags:
The following meta tags must be available in a license file:
- Valid-License-Identifier:
One or more lines which declare which License Identifiers are valid
inside the project to reference this particular license text. Usually
this is a single valid identifier, but e.g. for licenses with the 'or
later' options two identifiers are valid.
- SPDX-URL:
The URL of the SPDX page which contains additional information related
to the license.
- Usage-Guidance:
Freeform text for usage advice. The text must include correct examples
for the SPDX license identifiers as they should be put into source
files according to the `License identifier syntax`_ guidelines.
- License-Text:
All text after this tag is treated as the original license text
File format examples::
Valid-License-Identifier: GPL-2.0-only
Valid-License-Identifier: GPL-2.0-or-later
SPDX-URL: https://spdx.org/licenses/GPL-2.0-only.html
Usage-Guide:
To use this license in source code, put one of the following SPDX
tag/value pairs into a comment according to the placement
guidelines in the licensing rules documentation.
For 'GNU General Public License (GPL) version 2 only' use:
SPDX-License-Identifier: GPL-2.0-only
For 'GNU General Public License (GPL) version 2 or any later version' use:
SPDX-License-Identifier: GPL-2.0-or-later
License-Text:
Full license text
|
All SPDX license identifiers must have a corresponding file in the LICENSE
subdirectory. This is required to allow tool verification and to have the
licenses ready to read and extract right from the source, which is
recommended by various FOSS organizations, e.g. the `FSFE REUSE initiative
<https://reuse.software/>`_.

View file

@ -0,0 +1,69 @@
.. SPDX-License-Identifier: GPL-2.0
.. _remail_chkcfg_man:
remail_chkcfg manual page
=========================
Synopsis
--------
**remail_chkcfg** [*options*] config_file
Description
-----------
:program:`remail_chkcfg`, A program to check and display show the
configuration of a crypto mailing list
It reads the configuration file, verifies for correctness and displays the
resulting aggregated configuration in simple form.
Options
-------
-h, --help
Show this help message and exit
-e, --enabled
Show a pretty printed tabular list of names and email addresses of all
enabled subscribers in a list specific configuration file. Implies -lnq.
-l, --list
Configuration file is a list specific configuration which contains only
the subscribers
-n, --nokeys
Do not check for GPG and S/MIME keys and certs
-q, --quiet
Quiet mode. Do not show the configuration. Only check for correctness
-v, --verbose
Enable verbose logging.
-V, --version
Display version information
Invocation
----------
The program expects a properly populated configuration directory at the
place where the config_file is. If the program is invoked from outside the
configuration directory the program changes into the configuration
directory according to the directory part of the config_file argument.
If the configuration file is the base configuration file the program
expects the list configuration files of the enabled lists to be available
in the lists subdirectory.
If it is invoked with a list specific configuration file it only checks and
shows this part. If not disabled it checks for the availability and validity
of the keys for each subscriber.
See also
--------
:manpage:`remail_daemon.config(5)`

View file

@ -0,0 +1,58 @@
.. SPDX-License-Identifier: GPL-2.0
.. _remail_daemon_man:
remail_daemon manual page
=========================
Synopsis
--------
**remail_daemon** [*options*] config_file
Description
-----------
:program:`remail_daemon`, The daemon for running an encrypted mailing
list. It reads the configuration file from the command line.
Options
-------
-h, --help
Show this help message and exit
-s syslog, --syslog
Use syslog for logging. Default is stderr
-v, --verbose
Enable verbose logging.
-V, --version
Display version information
Configuration file
------------------
remail_daemon reads the configuration file which was handed in on the
command line. The configuration file is a simple yaml file. Non-mandatory
configuration options which are not in the configuration file are set to
the default values.
See the configuration file man page for detailed information.
Work directory
--------------
remail daemon assumes that the configuration file is in the work directory
which has a defined layout and content. The directory structure is
documented in the full remail documentation along with hints how to manage
documentation.
See also
--------
:manpage:`remail_daemon.config(5)`

View file

</
@ -0,0 +1,430 @@
.. SPDX-License-Identifier: GPL-2.0
.. _remail_daemon_config_man:
remail_daemon.config manual page
================================
Synopsis
--------
remail.yaml
list.yaml
Description
-----------
This manual describes the configuration file format for the remail daemon.
The configuration files are using yaml syntax. There are two types of
configuration files:
1) Base configuration file
The default configuration file is located in the base configuration
directory which is also the base work directory.
2) List configuration file
Per mailing list configuration file.
Non-mandatory options are set to the builtin defaults if they are not
available in the configuration files.
.. _config_dir_struct:
Configuration directory structure
---------------------------------
The configuration directory structure is fixed and looks like this::
├── .certs
│   ├── cacert.pem
│   ├── list1@your.domain.key
│   ├── list2@your.domain.key
│   ├── admin1@some.domain.crt
│   ├── admin2@other.domain.crt
├── .git
├── .gnupg
│   ├── private-keys-v1.d
│   │   ├── XYXYXYXYXYXYXYXYXYXYXYXYXYXYXYXYXYXYXYX1.key
│   │   ├── YXYXYXYXYXYXYXYXYXYXYXYXYXYXYXYXYXYXYXY2.key
│   ├── pubring.kbx
├── lists
│   ├── list1
│   │   ├── .certs
│   │   │   ├── list1@your.domain.crt
│   │   │   ├── subscr1-1@subscr1.domain.crt
│   │   │   ├── subscr1-2@subscr2.domain.crt
│   │   │   ├── admin1@some.domain.crt
│   │   ├── .git
│   │   ├── .gnupg
│   │   │   └── pubring.kbx
│   │   ├── list.yaml
│   │   ├── template_admin
│   │   └── template_welcome
│   ├── list2
│   │   ├── .certs
│   │   │   ├── list2@your.domain.crt
│   │   │   ├── subscr2-1@subscr1.domain.crt
│   │   │   ├── subscr2-2@subscr2.domain.crt
│   │   │   ├── admin2@other.domain.crt
│   │   ├── .git
│   │   ├── .gnupg
│   │   │   └── pubring.kbx
│   │   ├── list.yaml
│   │   ├── template_admin
│   │   └── template_welcome
├── lock
├── maildir
│   ├── cur
│   ├── new
│   └── tmp
├── maildir.frozen
│   ├── cur
│   ├── new
│   └── tmp
└── remail.yaml
The base directory contains:
- The main configuration file (remail.yaml).
- The S/MIME directory (.certs).
.. warning:: It contains the private S/MIME keys of the lists.
- The GPG directory (.gnupg).
.. warning:: It contains the private GPG keys of the lists.
- The maildir directory to which the incoming mail gets delivered by a
MTA or MRA.
- The maildir.frozen directory to which unprocessed or failed mail
gets moved to.
- A lock file which can be used to protect a reload against a concurrent
configuration update.
- The lists directory under which the list specific configuration directories
are located.
The list directories contain:
- The list configuration file (list.yaml)
- The S/MIME directory (.certs). It contains the public S/MIME keys of the
list subscribers and of the list itself.
- The GPG directory (.gnupg). It contains the public GPG keys of the list
subscribers and of the list itself.
Base configuration items
------------------------
The structure of the base configuration file is::
.. code-block:: yaml
enabled: False
use_smtp: False
smime:
...
gpg:
...
lists:
list1:
enabled: True
moderated: True
archive:
...
listaccount:
...
admins:
ad1@min.domain:
...
adN@min.domain:
...
listN:
...
Base items:
^^^^^^^^^^^
.. code-block:: yaml
enabled: False
use_smtp: False
enabled:
Optional item to enable or disable the daemon. If the item is set to
False then no other options are evaluated and the daemon sleeps waiting
for termination or reconfiguration. If True, the rest or the options is
evaluated.
Optional item which defaults to False
use_smtp:
Set to True to enable mail delivery via SMTP to the SMTP server on
localhost. The SMTP server is responsible for relaying the mails to a
public mail server. remail does not implement any other transport for
outgoing mail and the target server is therefore not configurable.
If False the encrypted mails are delivered to stdout. That's mainly a
development option which is not meant for production use.
Optional time which defaults to False
S/MIME options:
^^^^^^^^^^^^^^^
.. code-block:: yaml
smime:
verify: True
sign: True
verify:
When handling S/MIME encrypted mail then the validity of the senders key
is by default verified against the CA certs. If set to False this
verification is disabled. Disable this only in extreme situations and
consider the consequences.
sign:
Sign the mails sent to S/MIME recipients with the lists key. Enabled by
default as this is the recommended way to send S/MIME mail. If disabled
then the public certificate of the list is not part of the welcome
message which is sent to new recipients.
GPG options:
^^^^^^^^^^^^
.. code-block:: yaml
gpg:
always_trust: True
sign: True
always_trust:
The public keyring of a list is managed by the list administrator. To
avoid having to manually tweak the trust DB, it's possible to force
trust mode on the keyring with this option. Defaults to True as the
trust establishment is the responsibility of the list administrator
anyway and setting this to True avoids a lot of pointless manual
operations.
sign:
Sign the mails sent to GPG recipients with the lists key. Enabled by
default as this is the recommended way to send GPG mail. If disabled then
the public key of the list is not part of the welcome message which is
sent to new recipients.
The mailing lists collection:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: yaml
lists:
listname:
...
listname:
lists:
The opening of the lists map.
The list base configuration:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The list base configuration for each list consists of the following items:
.. code-block:: yaml
listname:
enabled: True
moderated: True
archive:
...
listaccount:
...
admins:
...
The list base items:
""""""""""""""""""""
.. code-block:: yaml
listname:
enabled: True
moderated: True
enabled:
If False, the list configuration is disabled. No mail is delivered to this
list. If True, the list is enabled.
moderated:
Optional item to set the list to moderated. It True only subscribers
are allowed to post to the list either from their subscription address
or from one of the optional alias mail addresses which are associated
with a subscriber. Mails from non-subscribers are not delivered to the
list, they are delivered to the list administrator
The archive section:
""""""""""""""""""""
.. code-block:: yaml
archive:
use_maildir: True
archive_incoming: True
archive_plain: False
use_maildir:
If True, maildir is the storage format for enabled archives. If False,
mbox is used.
archive_incoming:
If True archive the incoming encrypted mails in the selected storage
format. The maildir folder name is archive_incoming/. The mbox name is
archive_incoming.mbox. These files/directories are located in the per
mailing list configuration/work directory.
archive_plain:
If True archive the decrypted mails in the selected storage format. The
mails are archived in two stores:
- archive_admin[.mbox] for mails which are directed to the list admins
either directly or through bounce catching, moderation etc.
- archive_list[.mbox] for mails which are delivered to the list
The list account section:
"""""""""""""""""""""""""
.. code-block:: yaml
listaccount:
list@mail.domain:
name: Clear text name
fingerprint: 40CHARACTERFINGERPRINT
The list account's e-mail address is the key item for the name and
fingerprint options.
name:
A clear text name for the list, e.g. incident-17 or whatever sensible
name is selected. This name is used in From mangling when a list post
is sent to the subscribers:
incident-17 for Joe Poster <list@mail.domain>
From rewriting is used to ensure that replies go only to the list and
not to some other place. The Reply-To field could be used as well but
that is not correctly handled by mail clients and users can force
reply to all nevertheless.
fingerprint:
The full 40 character PGP fingerprint of the list key.
.. _list_admin_section:
The list administrators section:
""""""""""""""""""""""""""""""""
.. code-block:: yaml
admins:
admin1@some.domain:
name: Clear text name
fingerprint: 40CHARACTERFINGERPRINT
enabled: True
use_smime: False
gpg_plain: False
admin2@other.domain:
name:
The real user name. Mandatory field
fingerprint:
The full 40 character PGP fingerprint of the administrators
key. Mandatory if the use_smime option is not set.
enabled:
Switch to enable/disable the account. Mandatory item.
use_smime:
Send S/MIME encrypted mail to the admin if True. Otherwise use
PGP. Optional, defaults to False.
gpg_plain:
If False send mail in the application/pgp-encrypted format. If True
use the plain/text embedded PGP variant if possible. The latter does
not work for mails with attachments but for normal plain/text
conversation this can be requested by a recipient because that's
better supported in some mail clients. Optional, defaults to False.
List configuration items
------------------------
The structure of a list specific configuration file is::
.. code-block:: yaml
subscribers:
subscriber1@some.domain:
...
subscriberN@other.domain:
...
The configuration of the subscribers is identical to the configuration of
:ref:`the list administrators section <list_admin_section>` above, but it
allows one additional field:
.. code-block:: yaml
subscribers:
subscriber1@some.domain:
...
aliases:
- subscr1@some.domain
- subscriber1@other.domain
aliases:
The optional aliases item is a list of alias email addresses for a
subscriber. List mail is always delivered to the subscriber e-mail
address, but people have often several e-mail addresses covered by
the same PGP key and post from various addresses. If the list is