Commit 22b9065c authored by georg's avatar georg

Merge branch 'schleuder-version-3.5.0' into 'master'

Add docs about Schleuder version 3.5.0

Closes #47

See merge request !85
parents fdbff41d 4bf8dd1f
Pipeline #36744 passed with stages
in 58 seconds
---
layout: post
title: "Schleuder 3.5.0 released"
date: "2020-03-30"
---
This release ships new features, bug fixes and various UX-related improvements:
* The list options are enhanced, via:
* an option to include their public keys in the headers of outgoing emails (conforming with Autocrypt, [https://autocrypt.org/](https://autocrypt.org)),
* an option to control whether subscribers get a copy of mail they sent themselves,
* pseudoheaders are wrapped at 78 characters and a visual separator is added between the pseudoheaders block and the rest of the body,
* messages sent by Jenkins or sudo are not recognized as automated,
* the output of `x-resend` and friends is more precise,
* attaching the public key of a list works if using Thunderbird,
* better detection of the encoding of mails, which should reduce the amount of problematic mails causing errors,
* incoming mails encrypted to an absent key, using symmetric encryption or containing PGP-garbage are handled in a more graceful manner,
* notification mails sent to admins contain a List-Id header, which should help with filtering such messages.
Please see the [user-relevant changes]({{ "schleuder/docs/changes.html" | absolute_url }}) and the [changelog](https://0xacab.org/schleuder/schleuder/blob/master/CHANGELOG.md#350-2020-03-30) for details.
---
title: Changes from Schleuder 3.3 to 3.4
title: Changes from Schleuder 3.4 to 3.5
---
{: .note}
This list describes changes that users or list-admins of Schleuder should be aware of. For a more technical changelog, please see the [repository](https://0xacab.org/schleuder/schleuder).
{% include docs-head.md version=3.4 %}
{% include docs-head.md version=3.5 %}
User-relevant changes in version 3.4 compared to version 3.3:
User-relevant changes in version 3.5 compared to version 3.4:
* HTML is stripped from multipart/alternative messages if they contain keywords. This is to prevent those keywords from being visible to recipients of resend-messages, and thus leaking confidential information. Filtering the keywords from the HTML is not solidly feasible, so removing the HTML-part entirely is the only option. Generally we recommend to not use HTML with Email at all, as it brings a lot of problems and insecurities.
* The list options are enhanced, via:
* an option to include their public keys in the headers of outgoing emails (conforming with Autocrypt, [https://autocrypt.org/](https://autocrypt.org)),
* an option to control whether subscribers get a copy of mail they sent themselves.
* Pseudoheaders are wrapped at 78 characters.
* A visual separator is added to the end of the pseudoheaders block. This should help users of Apple Mail, which jams this block and the body together. Hopefully, this change makes it easier to dinstiguish both parts from each other.
* Messages sent by Jenkins or sudo are not recognized anymore as automated messages.
* The output of `x-resend` and friends is improved and more precise:
* Tell how many keys are in the keyring and how many are usable.
* Make it more clear what happens when resending an encrypted email fails (due to missing or too many matching keys), but falling back to unencrypted resend is allowed.
* Be more explicit that resending to other CC recipients has been aborted.
* Attaching the public key of a list works, if using `x-attach-listkey` via Thunderbird. Before the output was garbled and hardly usable.
* The detection of the encoding of incoming mails is improved. This should reduce the amount of mails which were problematic in this regard, and lead to errors.
* Incoming mails encrypted to an absent key, using symmetric encryption or containing PGP-garbage are handled in a more graceful manner: No exception is thrown, admins aren't notified (and annoyed), instead the sender is informed how to do better.
* Notification mails sent to admins contain a List-Id header. This should help with filtering such messages, which wasn't easy to do in a reliable way.
......@@ -2,7 +2,7 @@
title: Concept
---
{% include docs-head.md version=3.4 %}
{% include docs-head.md version=3.5 %}
Schleuder is an OpenPGP-enabled mailing list manager with resending capabilities. This document tries to explain what that means.
......
......@@ -2,7 +2,7 @@
title: Documentation for list-admins
---
{% include docs-head.md version=3.4 %}
{% include docs-head.md version=3.5 %}
{% include_relative _list_usage_basics.md %}
......
## Using a list
Everything you send to `foo@hostname` will be send to all subscribers, but they will see only certain headers and the body of your email. The selection of these headers can be configured for each list individually by the list-admins.
### Getting a list's public key
Each Schleuder-list replies with its public key to any email sent to `foo-sendkey@hostname`. E.g. to receive the key for our contact address write an email to `team-sendkey@schleuder.org`.
### Special keywords
Schleuder knows some special keywords that trigger different behaviour. You can e.g. subscribe someone, or resend an email to a non-subscriber using keywords. See a list of available keywords below.
Keywords require that:
* they start the line and begin with "x-",
* they are written into the beginning of the *first text-part* of the email (usually that's just the normal body of the email),
* possible arguments must be written *on the same line* as the keyword (exceptions are mentioned in the descriptions below),
* the email must be *encrypted and signed* by a list-member's key.
* the email must be formatted as a *plain text* message and not with HTML, RTF or similar formatting.
Keywords can be repeated within one email at will.
Letter case doesn't matter.
There are two types of keywords: those to enhance messages sent over the list ("list-keywords"), and those to request something from Schleuder ("request-keywords").
#### Security
To mitigate replay attacks of emails containing keywords, every email using a keyword **must** contain the special `x-list-name` keyword followed by the list's emailaddress. Example:
x-list-name: someone@example.org
: **You must always provide this keyword once per email.** Without it, no other keyword will be considered but you will receive an error message.
---
title: Changes from Schleuder 3.3 to 3.4
---
{: .note}
This list describes changes that users or list-admins of Schleuder should be aware of. For a more technical changelog, please see the [repository](https://0xacab.org/schleuder/schleuder).
{% include docs-head.md version=3.4 %}
User-relevant changes in version 3.4 compared to version 3.3:
* HTML is stripped from multipart/alternative messages if they contain keywords. This is to prevent those keywords from being visible to recipients of resend-messages, and thus leaking confidential information. Filtering the keywords from the HTML is not solidly feasible, so removing the HTML-part entirely is the only option. Generally we recommend to not use HTML with Email at all, as it brings a lot of problems and insecurities.
---
title: Concept
---
{% include docs-head.md version=3.4 %}
Schleuder is an OpenPGP-enabled mailing list manager with resending capabilities. This document tries to explain what that means.
## An email hub for groups
Schleuder enables subscribers to communicate encryptedly and pseudonymously. It takes care of all de- and encryption, stripping of headers, formatting conversions, etc.
But Schleuder can also receive and send emails to non-subscribers, which makes it a useful email hub for groups.
Incoming emails from non-subscribers ("outside people") are (re)encrypted and distributed among the subscribers, which can communicate internally as well as answer to the outside person via the list.
The outside person only sees an email address with a public key, but has no information about who is behind it.
Here's a simple picture of a message that is sent to a non-subscriber ("Zacharias"). It illustrates how Alice, Bob, Claire and David are invisible to Zacharias (click image to enlarge it).
[![resent-schema](schleuder-schema-resend-small.png 'Click to enlarge')](schleuder-schema-resend.png)
Additionally, it is possible to combine a list being used as a helpdesk to be combined with a Gitlab issue tracker. To learn more about that, have a look at the [project description](../../schleuder-gitlab-ticketing/).
### A helpful bot
Additionally, Schleuder can send out its own public key upon request by email. Anyone sending a message to `listname-sendkey@hostname` will receive a reply that contains the public key of that list.
And Schleuder can receive administrative commands by email. E.g. it is possible by email to add an OpenPGP-key to a list in order to reply encryptedly to an outside person.
## Technical details
### A "wanted machine-in-the-middle"
Basically Schleuder is a "wanted machine-in-the-middle".
Each list has its own keypair. Schleuder decrypts every incoming email and verifies its signature with the keys from the list's keyring. Then Schleuder loops over the list of subscribers, creates for each a stripped down copy of the message, encrypts it with the subscriber's key and signs it with its own key, and sends it out.
Schleuder inserts some lines of metadata into the top of the email, containing a (configurable) copy of some of the original headers and the result of the decryption and verification of the incoming email. Here's an example:
From: Bob <bob@example.net>
To: team@schleuder.org
Date: Tue, 6 Apr 2010 17:28:46 +0200
Enc: encrypted
Sig: Good signature from 12345678DEADBEEF Bob <bob@example.net>
The consequence of this approach is that you need to *really trust* the provider that runs Schleuder: they could store and decrypt all emails that pass the lists, if they wanted.
### Internal workings
Schleuder behaves like an email-filter: it reads email from standard-input, and reports errors to standard-error. If all goes well Schleuder closes the initial connection to the Mail Transport Agent (MTA) only after it sent out all outgoing emails.
In case of an error the MTA includes Schleuder's error message into a bounce-email that is sent back to the sender.
The keyrings for each list are standard GnuPG keyrings and sit in the filesystem under `$lists_dir/$hostname/$listname/` ($lists_dir is read from `schleuder.yml`, see [Configuration](#configuration)). They can be used manually using gpg2. Please be careful to maintain proper file permissions if you touch the files.
In the list-directory there's also a list specific log-file (might be missing if the log-level is high and no error occurred yet).
Other logging is sent to syslog. Where that ends up depends on the operating system and the system administration.
All other list-related data is stored in the SQL-database. Most data is unserialized, only some values are JSON-encoded.
---
title: Documentation
---
### Schleuder for&hellip;
* [subscribers](subscribers.html)
* [list-admins](list-admins.html)
* [server-admins](server-admins.html)
### Changed behaviour
Changes to the previous version of Schleuder are summarized in [changes](changes.html).
---
title: Documentation for list-admins
---
{% include docs-head.md version=3.4 %}
{% include_relative _list_usage_basics.md %}
#### Subscription and key management
These keywords must be send to `foo-request@hostname`. They are used to get information about the list, its subscribers and keys, or to change that information.
**x-list-subscriptions**
: List all subscriptions.
**x-subscribe:** person@example.org 0x12345678DEADBEEF12345678DEADBEEF12345678
: Subscribe the given address and assign it the given OpenPGP-fingerprint.
**x-unsubscribe:** person@example.org
: Unsubscribe the given address. It is not possible to unsubscribe the last admin of a list.
**x-set-fingerprint:** 0x12345678DEADBEEF12345678DEADBEEF12345678
: Assign the key with the given fingerprint to your subscription. It is not possible to set an empty fingerprint. To unset a fingerprint use `x-unset-fingerprint`.
**x-set-fingerprint:** person@example.org 0x12345678DEADBEEF12345678DEADBEEF12345678
: Assign the key with the given fingerprint to the given subscription. This variant of this command may only be used by list-admins. To unset a fingerprint use `x-unset-fingerprint`.
**x-unset-fingerprint:** person@example.org
: Remove the fingerprint associated with a given subscription.
**x-list-keys**
: Lists all public keys known to the list. To see only keys that match a given string, use `x-list-keys: something`.
**x-add-key:**
: Import the attachments or the rest of the email-body into the list's keyring. Only ascii-armored keys are supported.
**x-delete-key:** 0x12345678DEADBEEF12345678DEADBEEF12345678
: Delete the key with the given fingerprint from the list's keyring.
**x-get-key:** 0x12345678DEADBEEF12345678DEADBEEF12345678
: Export the key with the given fingerprint from the list's keyring.
**x-fetch-key:** 0x12345678DEADBEEF12345678DEADBEEF12345678
: Fetch the key with the given fingerprint from a keyserver and import it into the list's keyring. (This works only if a keyserver has been configured by the provider.)
This keyword must be send to the normal list-address: `foo@hostname`.
**x-attach-listkey:**
: Attachs the public key of the list. This might be useful for example after the setup of a new list, to distribute the public key of the list to all subscribers.
#### Other
These must also be sent to the request-address: <foo-request@hostname>.
**x-get-logfile:**
: Sends the logfile of the list.
**x-get-version:**
: Returns the version of schleuder.
**x-sign-this:**
: Sign the remaining contents of the email body or the attachments with the list's key. Use this e.g. to provide GnuPG-signatures for things you are publishing.
{% include participate.md %}
---
title: Projects and Plugins
---
These projects also belong to the schleuder-family:
* [schleuder-web]({{"/schleuder-web" | absolute_url}})
* [schleuder-cli]({{"/schleuder-cli" | absolute_url}})
* [schleuder-gitlab-ticketing]({{"/schleuder-gitlab-ticketing" | absolute_url}})
This diff is collapsed.
---
title: Documentation for subscribers
---
{% include docs-head.md version=3.4 %}
{% include_relative _list_usage_basics.md %}
#### Subscription and key management
The following keywords must be send to the request address of the list: `foo-request@hostname`.
x-set-fingerprint: 0x12345678DEADBEEF12345678DEADBEEF12345678
: Assign the key with the given fingerprint to your subscription. It is not possible to set an empty fingerprint. To unset your fingerprint use `x-unset-fingerprint`.
x-unset-fingerprint: person@example.org
: Remove the fingerprint associated with your subscription.
#### Resending
The resending-keywords must be included in messages sent to the normal list-address: `foo@hostname`.
**x-attach-listkey:**
: Attachs the public key of the list. Probably most useful in combination with x-resend.
**x-resend:** someone@example.org
: Send the message to the given address, encrypted if possible, otherwise in the clear.
**x-resend-encrypted-only:** someone@example.org
: Send the message to the given address only if it could be encrypted. Can be abbreviated to `x-resend-enc`.
**x-resend-unencrypted:** someone@example.org
: Send the message to the given address without encrypting it. You can use this keyword to make schleuder skip looking for a matching key for this address and enforce sending the email out in the clear.
**x-resend-cc:** someone@example.org anotherperson@example.org
: Send one message to all of the given addresses in Cc, so they get to know of each other (encrypted if possible, otherwise in the clear).
**x-resend-cc-encrypted-only:** someone@example.org
: Send one message to all of the given addresses in Cc, so they get to know of each other, only if it could be encrypted to all of those addresses. Can be abbreviated to `x-resend-cc-enc.`
**x-resend-cc-unencrypted:** someone@example.org
: Send one unencrypted message to all of the given addresses in Cc, so they get to know of each other. We skip looking for any key and will just send out the email in the clear.
### Contact list-owner
Write to `foo-owner@hostname` to contact the list-owner(s) even if you don't know who they are. Use the list's key to encrypt the email!
{% include participate.md %}
......@@ -4,6 +4,7 @@ title: Older documentation
Here are links to the documentation for older versions of Schleuder:
* [3.4](3.4/)
* [3.3](3.3/)
* [3.2](3.2/)
* [3.1](3.1/)
......
......@@ -2,7 +2,7 @@
title: Documentation for server-admins
---
{% include docs-head.md version=3.4 %}
{% include docs-head.md version=3.5 %}
## Setup Schleuder
......
......@@ -2,7 +2,7 @@
title: Documentation for subscribers
---
{% include docs-head.md version=3.4 %}
{% include docs-head.md version=3.5 %}
{% include_relative _list_usage_basics.md %}
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment