
PKGNAME:	ksm-gpgswitch-inka
VERSION:	0.5.0.1


INHALT

1.	Das Paket
1.1.	Beschreibung
1.2.	Die Dateien
1.3.	Lizenz

2.	Umgang mit dem Paket
2.1.	Voraussetzungen
2.2.	Installation/Deinstallation, Benutzer 'filter'
2.3.	Konfiguration
2.3.1.	Datei /etc/sudoers
2.3.2.	Eingehende Mail - Postfix/Sendmail
2.3.3.	Abgehende Mail - Postfix/Sendmail + Befehlsaufruf (z.B. Mutt)
2.3.4.	Abgehende Mail - Postfix + SMTP (z.B. Thunderbird)
2.3.5.	Dateien /usr/local/etc/gpguser.conf, ~/.gpgswitchrc und ~/.gpgkey
2.3.6.	Dateirechte
2.4.	Betrieb

------------------------------------------------------------------------------

1.	Das Paket

1.1.	Kurzbeschreibung

ksm-gpgswitch-inka ist eine Anwendung, welche es ermoeglicht, 1. durch Angabe
   von einfachen Schluesselwoertern im Betreff einer E-Mail die
   Verschluesselung abgehender E-Mail fuer jeden Empfaenger vornehmen zu
   lassen. Diese Schluesselwoerter muessen als allererste Zeichen im Betreff
   einer E-Mail stehen! Direkt anschliessend kann dann der normale Text des
   Betreffs eingegeben werden.
2. die Verschluesselung abgehender E-Mail fuer konfigurierte Empfaenger
   automatisch vornehmen zu lassen.

Eingehende E-Mail wird von ksm-gpgswitch-inka, falls verschluesselt und der
Empfaenger konfiguriert ist, automatisch entschluesselt. Eventuelle pgp/mime
kodierte Signaturen werden ueberprueft und das Ergebniss dieser Ueberpruefung
wird in Headern (Kopfzeilen) vermerkt.

In der lokalen Konfigurationsdatei kann angegeben werden, fuer welche
Empfaenger ausgehende E-Mail automatisch, ohne Angabe eines Schluesselworts,
a) verschluesselt oder
b) signiert und verschluesselt werden soll.

Diese Autoverschluesselung kann manuell durch Angabe eines entsprechenden
Schluesselworts im Betreff einer E-Mail gezielt fuer diese E-Mail verhindert
werden.

Auch kann in der Konfigurationsdatei angegeben werden, von welchen Absendern
hereinkommende E-Mails nicht angetastet werden sollen, von welchen Absendern
also die E-Mail durch ksm-gpgswitch-inka unveraendert hindurchgeleitet wird.

Generell gilt:
Schluesselwoerter im Betreff haben immer Vorrang vor der Autoverschluesselung.
Wird ein Schluesselwort (egal welches) angegeben, dann wird keine 
Autoverschluesselung mehr durchgefuehrt.

Wird trotzdem Verschluesselung gewuenscht, dann muss ein entsprechendes
Schluesselwort benutzt werden, welches die gewuenschten GPG-Aktionen kombiniert.

Die Dekodierung hereinkommender und lokal auszuliefernder E-Mail wird 
grundsaetzlich immer automatisch vorgenommen, falls nicht durch entsprechende
Eintraege in der ~/.gpgswitchrc verhindert und vorausgesetzt der User ist in
der Datei gpguser.conf eingetragen (Userkennung, Key-Id) und seine Passphrase
fuer gpg ist in seiner ~/.gpgkey hinterlegt.

Dies ist allerdings auch der Schwachpunkt von ksm-gpgswitch-inka. Die
Hinterlegung einer Passphrase in einer Datei birgt immer die Gefahr einer
Kompromittierung! Allerdings wird diese Gefahr von vielen Usern als gering
eingeschaetzt wenn man im Gegenzug dafuer den Komfort, den ksm-gpgswitch-inka
bietet, nutzen kann. Dies soll hier nicht verschwiegen werden - jeder muss
selbst entscheiden welches Risiko er eingehen will.

--- Unterstuetzte Verfahren ---
Verschluesseln:
  a) altes plain style Verfahren
  b) pgp/mime
Signieren:
  a) altes clearsigned Verfahren
  b) pgp/mime
Kombiniertes Signieren und Verschluesseln:
  a) pgp/mime
Entschluesseln:
  a) altes plain style Verfahren
  b) pgp/mime
Verifizieren:
  a) altes clearsigned Verfahren mit dem Mailer
  b) pgp/mime durch gpgswitch, Ergebnis der Verifizierung wird im 
     Header 'X--gpg: ' angezeigt
Kombiniertes Entschluesseln und Verifizieren:
  a) altes plain style Verfahren. gpgswitch entschluesselt, Verifizierung
     mit dem Mailer
  b) pgp/mime durch gpgswitch, Ergebnis der Verifizierung wird im 
     Header 'X--gpg: ' angezeigt)

Da fuer jeden lokalen Benutzer der GnuPG benutzt, ein eigener Eintrag in der
gpguser.conf angelegt werden kann und es fuer jeden Benutzer eine eigene
Konfigurationsdatei und eine eigene Passwortdatei im Home-Verzeichnis des
Users gibt, ist das System unbeschraenkt Multiuserfaehig. gpgswitch wird nur
fuer diese eingetragenen Benutzer aktiv.

Mails nehmen folgende Wege ueber gpgswitch:
Eingehende Mail:         postfix | procmail | gpgswitch -i | procmail
Abgehende Mail (Befehl): gpgswitch -o | sendmail
Abgehende Mail (SMTP):   postfix | gpgwrap -> gpgsu -> gpgswitch -s | sendmail
USER bei SMTP:           filter     root     <mailuser>

Getestet wurde ksm-gpgswitch-inka mit der Linux-Distribution Open SUSE 12.3.


1.2.	Die Dateien

GPL-2.0.txt	Die Gnu General Public License 2.0
README		Diese Datei
install.sh	(De)Installationsprogramm
pkg.inf		Paketinformationen
gpgwrap		Der Wrapper in /usr/local/bin/
gpgsu		Der Master in /usr/local/bin/
gpgswitch	Das Hauptprogramm in /usr/local/bin/
togglegpgswitch	Schaltprogramm um gpgswitch zu aktivieren/deaktivieren
installbyuser-gpgswitch	Programm, um Paket fuer neue Benutzer einzurichten
gpgkey		Vorlage fuer die lokale Passphrasendatei im Homeverzeichnis
		  jeden Benutzers (~/.gpgkey)
gpgswitchrc	Vorlage der lokalen Konfigurationsdatei jeden Benutzers
		  (~/.gpgswitchrc)
gpguser.conf	Diese Datei enthaelt den Loggin-Name und die E-Mail-Adresse
		  fuer jeden Benutzer, der mit ksm-gpgswitch-inka arbeiten will
<cmd>		Die Textvorlagen der Manpages in den Verz. help<sect>
<cmd>.<sect>.gz	Die Manpages der Kommandos


1.3.	Lizenz

Diese Software wird unter der Gnu General Public License 2.0 bzw.
unter der Gnu Lesser General Public License 2.1 vertrieben.
Welche Lizenz fuer ein Produkt jeweils zutrifft ist aus einem Vermerk im
Header des Sourcecodes des jeweiligen Programms ersichtlich.

------------------------------------------------------------------------------

2.	Umgang mit dem Paket

2.1.	Voraussetzungen

Es sind folgende Programme/Pakete erforderlich:
coreutils, util-linux, bash, gpg2, grep, postfix (oder sendmail), procmail,
sudo, ein Mail-Abruf-Programm (z.B. fetchmail).
Diese sind bei einer Linux-Standardinstallation i.d.R. bereits installiert.

Zusaetzlich wird das Paket ksm-lib-sh-inka (ab Version 0.2.0.1) benoetigt.
Dieses wird bei der Installation durch inka-pkgmanager automatisch installiert.

GnuPG und Postfix (oder Sendmail) mit Procmail als MDA (Mail Delivery Agent)
und das Mail-Abruf-Programm muessen korrekt eingerichtet sein.
Der Mailverkehr bei Benutzung dieser Programme muss funktionieren.

2.2.	Installation/Deinstallation, Benutzer 'filter'

Pruefen, ob die in der Voraussetzung genannten Pakete/Programme installiert
sind ggf. installieren und konfigurieren.
Dann mit inka-pkgmanager dieses Paket installieren. (Oder umgekehrt.)

Sollte die Installation abgebrochen worden sein, weil es mit dem Benutzer
'filter' Probleme gab, diesen manuell anlegen. Er muss der Gruppe 'nogroup'
angehoeren. Er sollte so wenig Rechte wie moeglich haben. Sein Home-Verzeichnis
sollte sich nicht unter /home befinden, sondern z.B. unter /var/spool/filter.
Er sollte sich nicht einloggen koennen.

Eine Deinstallation erfolgt ebenfalls mit inka-pkgmanager.
Die in der Konfiguration 2.3.1. bis 2.3.4. beschriebenen Aenderungen sollten
dann rueckgaengig gemacht werden!

Wenn der Benutzer 'filter' mit dem Installationsprogramm angelegt wurde und
nicht mehr benoetigt wird, folgende Befehle eingeben:
----------------------------------- START ------------------------------------
userdel filter
rm -r /var/spool/filter
rm /var/spool/mail/filter
------------------------------------ ENDE ------------------------------------


2.3.	Konfiguration

2.3.1.	Datei /etc/sudoers

Nach der Installation muss 'sudo' folgendermassen (in /etc/sudoers)
konfiguriert werden:
----------------------------------- START ------------------------------------
Defaults always_set_home
Defaults env_reset

# Allow user 'filter' to give gpgswitch master 'gpgsu' root privileges
filter	ALL=NOPASSWD:	/usr/local/bin/gpgsu
------------------------------------ ENDE ------------------------------------

Die beiden Zeilen mit 'Defaults' sind evtl. bereits vorhanden. (Wichtig beim
Deinstallieren des Pakets!)


2.3.2.	Eingehende Mail - Postfix/Sendmail

Damit gpgswitch eingehende Mail behandelt, muss es in den Mailtransport kurz
vor der lokalen Zustellung eingeklinkt werden.

Beispiel Postfix/Sendmail - eingehende, lokal auszuliefernde Mail:
Es kann fuer diese beiden MTAs (Mail Transport Agent) ein lokaler MDA
(Mail Delivery Agent) angegeben werden.
Da es sich sowieso anbietet 'procmail' als Mailfilter zu benutzen, muss
procmail als MDA angegeben werden. gpgswitch ist auf procmail abgestimmt.

In der globalen Konfigurationsdatei von procmail (/etc/procmailrc) sollte
dann als erste Regel eine Pipe ueber gpgswitch erstellt werden:

----------------------------------- START ------------------------------------
# Decrypt and verify pgp-encrypted msgs
:0 fhbrW:/tmp/gpgswitch.lock
| gpgswitch -i
------------------------------------ ENDE ------------------------------------

Achtung: Wenn in der /usr/local/etc/main-inka-sh.conf die Variable TEMPDIR
einen anderen Wert bekommen hat, muss in der zweiten Zeile anstatt '/tmp'
dieses andere Verzeichnis eingetragen werden!

Alle lokal auszuliefernde Mail wird nun erst einmal ueber gpgswitch mit dem
Kommando fuer eingehende E-Mail (-i) geleitet.


2.3.3.	Abgehende Mail - Postfix/Sendmail + Befehlsaufruf (z.B. Mutt)

Wenn der MUA (Mail User Agent, auch Mailer oder Mailprogramm) die Mail durch
einen Aufruf von 'sendmail' verschickt und dieser Aufruf konfiguriert werden
kann, kann gpgswitch fuer abgehende Mail mit diesem Aufruf eingeklinkt werden.

Beispiel Mutt - abgehende Mail:
In der Konfigurationsdatei /etc/Muttrc befindet sich eine (standardmaessig
auskommentierte) Variable "sendmail". Diese enthaelt defaultmaessig den hier
angegebenen Wert:
# set sendmail="/usr/sbin/sendmail -oem -oi"

Diese Variable muss durch Entfernen des Kommentarzeichens und Eintrag von
gpgswitch folgendermassen gesetzt werden:
set sendmail="/usr/local/bin/gpgswitch -o"

gpgswitch benutzt beim versenden von Mail immer 'sendmail' (Postfix enthaelt
dieses Kommando aus Kompatibilitaetsgruenden).


2.3.4.	Abgehende Mail - Postfix + SMTP (z.B. Thunderbird)

Wenn der MUA (Mail User Agent, auch Mailer oder Mailprogramm) die Mail per
SMTP verschickt, kann gpgswitch fuer abgehende Mail in Postfix in der Art
eines Filters eingeklinkt werden.

Beispiel Thunderbird - abgehende Mail:
Mailer wie Thunderbird versenden die Mail per SMTP. Postfix kann so
konfiguriert werden, dass gpgswitch in der Art eines "Content-Filter"
eingebunden wird. So ist es moeglich, auch solche per SMTP versendete Mail mit
gpgswitch zu bearbeiten. gpgswitch arbeitet nicht als Daemon, der ueber
bestimmte Ports angesprochen wird!

gpgswitch benutzt beim versenden von Mail immer 'sendmail' (Postfix enthaelt
dieses Kommando aus Kompatibilitaetsgruenden).

Folgende Eintraege sind in der Datei /etc/postfix/master.cf vorzunehmen.
Die Zeile mit dem Service 'smtp' in der Tabelle wird durch die Angaben in der
Zeile darunter wie folgt ergaenzt und am Ende der Tabelle wird der unten
gezeigte 2-zeilige Filter-Eintrag hinzugefuegt. (Jeweils Leerraum am
Zeilenanfang beachten!):

----------------------------------- START ------------------------------------
# ==========================================================================
# service type  private unpriv  chroot  wakeup  maxproc command + args
#               (yes)   (yes)   (yes)   (never) (100)
# ==========================================================================
smtp      inet  n       -       n       -       -       smtpd
	-o content_filter=filter:dummy


# ====================================================================
# Interfaces to non-Postfix software. Be sure to examine the manual
# pages of the non-Postfix software to find out what options it wants.
#
# ====================================================================


# ==========================================================================
filter    unix  -       n       n       -       1       pipe
  flags=Rq user=filter argv=/usr/local/bin/gpgwrap -f ${sender} -- ${recipient}
------------------------------------ ENDE ------------------------------------

Damit Postfix die neuen Tabellen einliest, je nach System entweder
'postfix reload' oder 'systemctl reload postfix.service' eingeben.


2.3.5.	Dateien /usr/local/etc/gpguser.conf, ~/.gpgswitchrc und ~/.gpgkey

Jeder Benutzer, dessen Benutzerkonto erst nach der Installation von
ksm-gpgswitch-inka angelegt wurde und der gpgswitch benutzen moechte, gibt
folgenden Befehl ein:
installbyuser-gpgswitch -i

Damit wird seine ~/.gpgswitchrc und ~/.gpgkey mit den Default-Werten angelegt.

Nach der Installation muss gpgswitch auf die Erfordernisse des Anwenders
eingestellt werden.

Es muss fuer alle Benutzer auf dem lokalen System, welche gpgswitch benutzen,
der User-Name (Login Name) und die Key-ID (die E-Mail Adresse, welche als
User-ID fuer GnuPG benutzt wird) in die Datei /usr/local/etc/gpguser.conf
eingetragen werden. Diese Eintragungen muessen, durch Semikolons getrennt,
zeilenweise (pro Benutzer eine Zeile) erstellt werden. (Keine weiteren Zeilen
einfuegen!)

Beispiel gpguser.conf:
fred;freddy@mydomain.tld

Jeder Benutzer, der gpgswitch benutzen will, muss noch:
1. Die Datei ~/.gpgswitchrc gegebenenfalls, wie unten beschrieben,
   konfigurieren.
2. In der Datei ~/.gpgkey seine Passphrase eintragen.
   (In der Passphrase keine Zeichen mit speziellen Bedeutungen in regulaeren
   Ausdruecken verwenden!)

In der lokalen Konfigurationsdatei ~/.gpgswitchrc koennen folgende Dinge nur
fuer den betreffenden Benutzer eingetragen/geaendert werden:

a) Der Standard-Zeichensatz (default charset).
b) Die Standard-Transport-Kodierung (default transfer encoding).
c) Die Keyphrases (die Schluesselwoerter, welche gpgswitch mit der
   Betreffzeile steuern).

Dann existieren drei Listen:
d) Liste 'gpg_user'-E-Mail-Adressen; abgehende Mail an diese Adressen
   wird automatisch (pgp/mime) verschluesselt.
e) Liste 'gpg_siguser'-E-Mail-Adressen; abgehende Mail an diese Adressen
   wird automatisch (pgp/mime) signiert und verschluesselt.

   (Falls eine Adresse in beiden Listen gleichzeitig eingetragen ist, hat die
   automatische Signierung und Verschluesselung vorrang.)

f) Liste 'gpg_exclude_user'-E-Mail-Adressen; hereinkommende Mail von diesen
   Adressen wird generell nicht entschluesselt oder verifiziert, d.h.
   gpgswitch laesst diese Mails unveraendert.


2.3.6.	Dateirechte

Alle Dateien muessen mit den unten gezeigten Dateirechten installiert werden.
(Sollte durch das Installationsprogramm install.sh geschehen.)

-rwx------ root   root    /usr/local/bin/gpgsu
-rwxr-xr-x root   root    /usr/local/bin/gpgswitch
-rwx------ filter nogroup /usr/local/bin/gpgwrap
-rwxr-xr-x root   root    /usr/local/bin/installbyuser-gpgswitch
-rwxr-xr-- root   root    /usr/local/bin/togglegpgswitch
-rw-r--r-- root   root    /usr/local/etc/gpguser.conf

/$HOME/<USER>/:
-rw------- <USER> <GROUP> .gpgkey
-rw------- <USER> <GROUP> .gpgswitchrc


2.4.	Betrieb

Nachdem alles konfiguriert wurde, kann gpgswitch mit dem Befehl
'togglegpgswitch [-e]' aktiviert werden. Dies muss nur einmal durchgeführt
werden. Durch wiederholten Aufruf von 'togglegpgswitch' kann gpgswitch
jederzeit (auch im laufenden Betrieb) an- und ausgeschaltet werden. Dieser
Befehl ist dem root vorbehalten.

Ist gpgswitch deaktiviert, werden alle E-Mails unveraendert durchgeleitet.

gpgswitch setzt in aktiviertem Zustand immer einen Received-Header.
Desweiteren setzt gpgswitch bei jeder von ihm durchgefuehrten Aktion einen
'X-gpgswitch-*: '-Header, welcher die Aktion beschreibt. Ausserdem wird die
Aktion per syslog im System-Logfile vermerkt.

Bei den Funktionen 'Verifizieren' und 'Entschluesseln-und-Verifizieren'
werden ausserdem noch Zeilen mit dem Header ('X--gpg: ') gesetzt, welche
ueber den Status des Verifiziervorgangs informieren.

Wichtig ist in dem Zusammenhang der Header 'X-gpgswitch-decrypted: ', welcher
anzeigt, dass eine E-Mail verschluesselt war, und von gpgswitch entschluesselt
wurde.

Um diese Informationen im Mailer zu erhalten, sollten die Header
'X-gpgswitch-decrypted: ' und 'X--gpg: ' angezeigt werden.

------------------------------------------------------------------------------

Viel Spass :-)

Juergen Kaesmann
E-Mail: juergen@kaesmann.us
HTTP : http://www.kaesmann.us
FTP  : ftp://ftp.kaesmann.us

Modifiziert von Ingo Kaesmann
HTTP: http://www.ingokaesmann.de

Berlin, den 06.09.2013
