= User Interface Interaction with GnuPG
**Status: Draft, work in progress**

//Note: This is not a discussed concept but a draft by AndreHeinecke to get the discussion started.
It is initially written in German so most parts are still in German.
Apologies to non German speakers, we will translate this into English.//

This page should describe how User Interface Applications should integrate / interact
with ~GnuPG and what API should be offered to enable the implementation of
new [[EasyGpg2016/PubkeyDistributionConcept|OpenPGP-Key distribution]] and
trust concepts with little redundancy. The main focus is on Mail User Agents.

Design goals:
 * Reduce redundant implementations.
 * Comfortable use of ~GnuPG for developers.
 * Assist developers to provide a common and good User Experience.

<<TableOfContents(3)>>

== Summary of (new) library roles

* No direct process calls to ~GnuPG.
* Everything possible with ~GpgME in C.
* ~GpgMEpp and ~Q~GpgME with convenient API for C++ / Qt. No GUI, no localization.
* Libkleo with Qt Widgets for common tasks. Common UI Logic for Qt / KDE Frameworks applications.


//TODO: If we implement actions after some activity 
like proposed in the remark of
[[https://wiki.gnupg.org/EasyGpg2016/VisionAndStories|user story T3]],
which component will do the counting and how will applications taken notice?

== Aktueller Stand
Es gibt (Stand: Mai 2016) historisch gewachsen, verschiedene Arten GnuPG 
aus einer Anwendung heraus
anzusprechen. Im Endeffekt läuft alles auf Prozessaufrufe der GnuPG-Programme
hinaus. Die Unterscheidung "Prozessaufruf" bezieht sich
auf die Verwendung ohne weitere Bibliothek.

Die offizielle API von GnuPG ist ~GpgME,
für welches es Anbindung in vielen Programmiersprachen gibt,
siehe https://wiki.gnupg.org/APIs .
Ein großer Vorteil der
Verwendung von ~GpgME ist, neben der stabilen API, die weitreichende
Abstraktion von ~OpenPGP und S/~MIME (CMS).

Im GnuPG Projekt existiert zudem bereits das bestreben Benutzerinteraktion
möglichst zu vereinheitlichen, um einerseits eine technische Duplikation
ähnlicher Implementierungen zu vermeiden und andererseits, um sprachlich
und in der Darstellung über mehrere Anwendungen das gleiche Bild zu liefern.

Hierzu wurde 2008 das UI-Server-Protokoll eingeführt. Anwendungen
kommunizieren über einen Socket mit einer UI-Server-Anwendung, welche die
Nutzerinteraktion übernimmt. Dieses Protokoll hat sich bisher nicht
verbreitet. Die einzige bekannte Nutzung
gibt es durch die Windows-Plugins ~GpgEX und ~GpgOL der Gpg4win-Initiative.


=== Prozessaufruf
Version: 2.1.11

Mit speziellen Parametern wie {{{--status-fd --command-fd}}} bietet GnuPG ein
Kommandozeilenen-Interface, welches ein Format liefert, das grundsätzlich dafür
geeignet ist von anderer Anwendung verarbeitet zu werden.
Dafür gibt es jedoch keine Stabilitätsgarantien neue Versionen und kleine
Änderungen haben in der Vergangenheit häufig zu Problemen geführt.

gpg und insbesondere gpgsm bieten zudem einen Server Modus über den
verschiedene Operationen über ein Textprotokoll gesteuert werden können.

**Vorteile:**
* Einfacher Einstieg, da Kommandos bereits bekannt und weitreichend dokumentiert sind.
* Minimale Abhängigkeiten.

**Nachteile:**
* Jede Aktualisierung von GnuPG kann existierende Parser brechen.
* Eigene Parser-Implementationen nötig.
* Alle Details und Fehlerbehandlung sind schwierig komplett zu implementieren.
* Unterschiedliche Versionen von GnuPG können unterschiedliche Ausgaben haben.
* Verwendung des Server Modus von GnuPG und GpgSM muss selbst implementiert werden.

Beispielhafte Verwendung zum Importieren eines Zertifikats von einem
Zertifikatsserver:

(Eingaben markiert mit ">" Ausgaben markiert mit "<")

{{{
> gpg2 --status-fd=1 --command-fd=0 --search aheinecke@gnupg.org
< (1)     Andre Heinecke <aheinecke@gnupg.org>
<        Andre Heinecke <andre@heinecke.or.at>
<        Andre Heinecke <aheinecke@intevation.de>
<        Andre Heinecke <andre.heinecke@intevation.de>
<          3072 bit RSA key F462B6B1, created: 2015-12-08, expires: 2025-12-05
< [GNUPG:] GET_LINE keysearch.prompt
> 1
< [GNUPG:] GOT_IT
< [GNUPG:] IMPORT_OK 0 94A5C9A03C2FE5CA3B095D8E1FDF723CF462B6B1
< gpg: key F462B6B1: "Andre Heinecke <aheinecke@intevation.de>" not changed
< gpg: Total number processed: 1
< gpg:              unchanged: 1
< [GNUPG:] IMPORT_RES 1 0 0 0 1 0 0 0 0 0 0 0 0 0 0
}}}

Man erkennt, dass ein Parser nötig ist, der selbst Annahmen über das Verhalten von
GnuPG enthalten muss. Beispielsweise über die Bedeutung der einzelnen Spalten.
Kommt eine neue Spalte hinzu wie z.B. in gnupg-2.1 geschehen muss der entsprechende
Parser angepasst werden.

=== GpgME
Version: 1.6.0

GpgME ist eine unabhängige Bibliothek für GnuPG. Es stellt eine stabile
C-API bereit, über die andere Anwendungen GnuPG verwendenden können.
GpgME kann man sich als dabei als offiziellen Parser für GnuPG-Ausgaben vorstellen
der wenn nötig bei Änderungen in GnuPG angepasst wird.

Es abstrahiert zudem zwischen OpenPGP und S/MIME und stellt eine vergleichbare
API für die Anwendungen gpgsm und gpg zur Verfügung. Ausgaben der Anwendung
werden threadsicher verarbeitet und dann in C-Datenstrukturen bereitgestellt.

Datenquellen werden in GpgME ebenso abstrahiert und müssen nicht über Dateien oder
Input / Output Devices übergeben werden.

**Vorteile:**
* Stabile und dokumentierte Schnittstelle.
* Von der GnuPG-Initiative gepflegter Parser.
* Abwärtskompatible Erweiterungen.

**Nachteile:**
* Abhängigkeit zu einer Bibliothek.
* Initial höherer Einarbeitungsaufwand.

Beispielhafte Verwendung zum Importieren eines Zertifikats von einem Zertifikatsserver:

{{{
gpgme_key_t key;
gpgme_ctx_t ctx;
gpgme_protocol_t protocol = GPGME_PROTOCOL_OpenPGP;
gpgme_key_t keyarray[1];
gpgme_import_result_t impres;

init_gpgme (protocol);
gpgme_set_keylist_mode (ctx, GPGME_KEYLIST_MODE_EXTERN);
gpgme_op_keylist_start (ctx, "aheinecke@gnupg.org", 0);
gpgme_op_keylist_next (ctx, &key);
keyarray[0] = key;
gpgme_op_keylist_end (ctx);
gpgme_op_import_keys (ctx, keyarray);
impres = gpgme_op_import_result (ctx);
}}}

Das Beispiel ist so vereinfacht, dass keine Fehlerbehandlung stattfindet. Die
einzelnen Kommandos können Fehlercodes zurückgeben, die in libgpg-error definiert wurden.
Man sieht, dass die initiale Verwendung komplexer ist, als bei einem
einfachen Systemaufruf. Dies hat aber dafür den Vorteil, dass man klar
definierte C-Datenstrukturen hat. So könnte
die Anzahl der unveränderten Zertifikate mit {{{impres->unchanged}}} abgefragt werden
ohne wissen zu müssen, dass dies der 5. Ziffer in der IMPORT_RES Zeile entspricht.


=== Libkleo
Version: 5.2.1

Libkleo bezeichnet sich als "The KDE keymanagement Library". Sie bietet eine Abstraktion
von "Crypto Backends", womit zwischen GnuPG und Chiasmus abstrahiert wurde. Mit der
nächsten Version von Libkleo (5.3.0) wird die Chiasmus Unterstützung entfernt, da mit
KMail 5.2.0 die Unterstützung für Chiasmus bereits in KMail entfernt wurde und somit
keine bekannte Verwendung existierte. Der Nutzen der backend Abstraktion
entfällt somit zukünftig.

Mit dem QGpgME-Backend wird zudem eine API angeboten, welche die Implementationsdetails in
GpgME verbirgt, damit Qt-Entwickler eine komfortable, asynchrone
und Job-basierte API nutzen können.

**Vorteile:**
* Integration von Kleopatra UI Elementen in eigene Anwendungen.
* Einheitliche Benutzererfahrung über mehrere Anwendungen.
* Einfach zu verwendende Kryptographie API.

**Nachteile:**
* Abhängigkeit zu Qt UI und einigen KDE Bibliotheken (Frameworks).
* Keine volle Kontrolle über die Implementation.

Beispiel:
{{{
    Protocol *openpgp = Kleo::CryptoBackendFactory::instance()->openpgp();
    KeyListJob *job = openpgp->keyListJob(/*bool remote*/ true);
    connect(job, &KeyListJob::result, job, [job, openpgp](KeyListResult, std::vector<Key> keys, QString, Error)
    {
        openpgp->importFromKeyserverJob()->start(keys);
    });
    job->start(QStringList() << "aheinecke@gnupg.org");
}}}

In diesem Beispiel passiert die Suche und der Import in einem anderen Hintergrundthread
und ist somit direkt für die Verwendung in GUI Anwendungen geeignet.

=== Kleopatra über Prozessaufruf
Version Kleopatra 2.3.0

Kleopatra kann bereits über Kommandozeilenparameter angesprochen werden. Dies wird
beispielsweise von Kontact Mail (der alte Name ist "KMail") verwendet, um Zertifikatsdetails anzuzeigen oder die
Suche eines Zertifikats anzustoßen. Der Dateimanager Dolphin verwendet dies
zudem um die Integration ins Dateimenü von Kleopatra zu ermöglichen.

**Vorteile:**
* Kein eigener Code für Benutzerinterface nötig.
* Einfache Verwendung.
* Keine Abhängigkeiten zu Bibliotheken.
* Zustandslos.

**Nachteile:**
* Fremdes Benutzerinterface, Dialoge in eigenem Fenster.
* Bei komplexen Kommandos könnte ein Parsen der Ausgabe nötig werden.
* Kleopatra muss zusätzlich gestartet werden oder bereits laufen.
* Keine Abstraktion zwischen GPA und Kleopatra.
* Derzeit nicht für alle möglichen Operationen implementiert.

Beispielhafte Verwendung zum Importieren eines Zertifikats von einem
Zertifikatsserver:
{{{
kleopatra --search aheinecke@gnupg.org
}}}

Die weiteren Abläufe und der Import erfolgen dann interaktiv.

{{import-certificates.png}}

//Zertifikatssuchdialog von Kleopatra

Hierbei ist zu erkennen, welche Vorteile es hat eine bestehende Anwendung
zu verwenden: Im Falle, dass mehrere Zertifikate gefunden werden,
müsste ein solcher Dialog von anderen Anwendungen selbst implementiert werden. Kleopatra
erlaubt hier beispielsweise die Details eines Zertifikates anzuzeigen bevor
es importiert wird.


=== UI-Server
Version Kleopatra 2.3.0 bzw. GPA 0.9.9

Das
[[https://www.gnupg.org/documentation/manuals/gpgme/UI-Server-Protocol.html|UI-Server-Protokoll]]
ist ein Protokoll, über das GUI-Anwendungen
Unterfenster für kryptografische Operationen ansteuern können.

**Vorteile:**
* Kein eigener Code für Benutzerinterface nötig.
* Vereinheitlichung der Benutzerschnittstelle bei Nutzung durch mehrere
  Anwendungen.
* GUI-Verbesserungen können an einer Stelle vorgenommen werden, als
  mehrere Anwendungen zu haben, welche u.U. nur teilweise implementiert sind.
* Vorhandene Zertifikate werden gecached.

**Nachteile:**
* Komplexe Verwendung und Kommunikation da zustandsorientiert.
* Notwendigkeit einer plattformabhängigen Socket-Implementation (libassuan).
* Qt/QWidgets oder GTK-basiertes Benutzerinterface.
* GPA oder Kleopatra zusätzlich notwendig.
* GPA oder Kleopatra müssen zusätzlich gestartet werden oder bereits laufen.
* Fremdes Benutzerinterface, Dialoge in eigenem Fenster.
* Derzeit nicht für alle möglichen Operationen definiert.

Beispielhafte Verwendung zum Verschlüsseln / Signieren einer Mail (Import vom
Zertifikatsserver ist nicht im Protokoll definiert):

{{{
> SENDER --info -- testusera@example.com
< OK
> RECIPIENT testuserb@example.com
< OK
> PREP_ENCRYPT --expect-sign --protocol=OpenPGP
< OK
> INPUT FILE=/tmp/test
< OK
> OUTPUT FILE=/tmp/out
< OK
> ENCRYPT --protocol=OpenPGP
< OK
> INPUT FILE=/tmp/out
< OK
> OUTPUT FILE=/tmp/out.signed
< OK
> SIGN --protocol=OpenPGP
> BYE
}}}


{{recipientdialog.png}}

//Zertifikatsauswahldialog von GpgOL


=== Sprachanbindungen für GpgME (GpgMEpp, QGpgME)
Version 5.2.1

GpgME ist eine reine C-Bibliothek. Um diese komfortabler in anderen Programmiersprachen
verwenden zu können, gibt es verschiedene [[https://wiki.gnupg.org/APIs|Sprachanbindungen]].
Die für das EasyGPG-Projekt relevantesten sind QGpgME bzw. GpgMEpp, welche eine mit
Qt-Klassen integrierte API bzw. eine C++-API bereitstellen.

In der betrachteten Version befindet sich ein Großteil der QGpgME-API in libkleo.
Weitere QGpgME-Teile und GpgMEpp werden mit KF5GpgmePP als Teil von KDE-Applications veröffentlicht.

Im Rahmen der Aufträge
[[https://wiki.gnupg.org/Gpg4all2015|Gpg4all2015]]
und
[[https://wiki.gnupg.org/EasyGpg2016|EasyGpg2016]]
werden diese beiden
Bibliotheken in das GpgME-Repository überführt 
und die KDE-Abhängigkeiten aus QGpgME entfernt.
Zukünftig sollen diese beiden Sprachanbindungen 
als Teil von GpgME veröffentlicht werden.


=== Verwendete Anbindung in vorhandenen Mail User Agents

In der folgenden Liste sind einige Mail User Agents angeführt, deren Entwickler in Kontakt
mit der GnuPG-Initiative stehen und bei denen die Gründe für die Entscheidungen, wie sie GnuPG
verwenden, bekannt sind.

|=MUA                   |=Anbindung     |=Gründe|
|Thunderbird (Enigmail) |Prozessaufruf  |Enigmail ist ein JavaScript Plugin für Thunderbird und verteilt eine Version des Plugins für alle Plattformen und die Entwickler möchten keinen Binärcode bündeln. Enigmail verwendet GnuPG nur für OpenPGP und würde daher nicht von der CMS/OpenPGP Abstraktion profitieren. |
|Kontact Mail           |Libkleo        |Kontact Mail verwendet einen hybriden Ansatz, zur vollen Unterstützung aller Funktionen ist Kleopatra notwendig, die eigentlichen Operationen werden jedoch direkt über libkleo durchgeführt.  Kleopatra wird Beispielsweise zur Anzeige von Zertifikatsdetails und der Zertifikatssuche ausgeführt. |
|Claws Mail             |GpgME          |Der empfohlene Weg und Verwendung einer stabilen API, keine weiteren Abhängigkeiten gegen andere Software. Eigenes UI gewünscht. |
|GpgOL                  |~UIServer      |GpgOL selbst enthält keine GUI Bibliothek und ist durch die Outlook API in der Nutzerinteraktion limitiert. Daher werden Dialoge von Kleopatra bzw. GPA über das ~UIServer Protokoll aufgerufen. Zukunftswunsch der GpgOL Entwickler ist es auch nur eigenes UI in Outlook anzuzeigen.|
|Trojitá                |QGpgME         |Keine Abhängigkeiten gegen KDE Software Collection. Eigenes UI gewünscht.|
|Mailpile               |Prozessaufruf  |Wechsel auf GpgME ist geplant. Ursprüngliche Wahrnehmung war das eine weitere Schicht eher die Komplexität erhöht.|

Zukunftig wird die direkte Verwendung von GpgME auch keine Option in Engimail werden
da Unterstützung für binärcode (z.B. das dynamische nachladen von GpgME zur laufzeit)
in Mozilla Addons bereits
[[https://blog.mozilla.org/addons/2015/05/04/dropping-support-for-binary-components/|abgekündigt ist]].

// TODO: ggf. offizielle Quellen suchen und/oder nachfragen?



== Konzept: Schnittstellen für EasyGPG

Um GnuPG stabil anzusteuern ist die starke Empfehlung des GnuPG-Projektes
die GpgME Bibliothek zu verwenden, da nur diese Kompatibilität über viele
Versionen und eine stabile Programmschnittstelle garantiert. Die mittelfristigen
Vorteile der Verwendung von GpgME überwiegen stark die wahrgenommene Einfachheit
des direkten Prozessaufrufs.

Mit der Anwendung gpgme-tool steht bereits ein Werkzeug zur verfügung um GpgME über
Prozessaufrufe zu verwenden wenn das Laden von externen Bibliotheken, wie im Falle von
Enigmail keine Option ist.

Das ~UIServer Protokoll wird weiterhin erhalten bleiben, Anpassungen
für neue Zertifikatssuchen und Vertrauensmodelle sind hier jedoch nicht
nötig da dies für Anwendungen welche das ~UIServer Protokoll verwenden
transparent sein sollte.

Es können grob vier verschiedene Ebenen der Interaktion mit GnuPG
unterschieden werden, welche angeboten und weiterentwickelt werden:

=== 1. Prozessaufrufe von GnuPG-Anwendungen

Direkte Aufrufe von GnuPG-Anwendungen interaktiv auf der Kommandozeile
als auch mit Parametern für maschinenlesbare Ausgaben.

* Zielgruppe: Experten Anwender, Administratoren (einfache Automatisierung)

* Begründung: Da der Kern aller Anbindungen der Prozessaufruf von GnuPG ist, wird GnuPG entsprechend
erweitert, um alle benötigten Aktionen durchführen zu können. Die genaue Umsetzung
ist hierbei jedoch nicht klar definiert und es werden keine Garantien dazu
gegeben das die Ein und Ausgaben der Prozesse nicht geändert werden. Ein
MUA sollte diese daher nicht direkt verwenden.

* Voraussetzungen: Eine GnuPG-Installation.


=== 2. GpgME 

GpgME bleibt die zentrale Schnittstelle für Anwendungen zu GnuPG und wird
als solche weiterentwickelt.

* Zielgruppe: Alle Entwickler die nicht C++ Anwendungen Entwickeln.

* Begründung:
GpgME ist die Referenzimplementation zum programmatischen Arbeiten mit
GnuPG. GpgME wird bereits in verschiedenen MUA's verwendet. Höhere
Abstraktionsschichten (wie QGpgME) benötigen GpgME als Grundlage.

* Voraussetzungen:
Unterstützung für GnuPG-Prozessaufrufe.


=== 3. QGpgME / GpgMEpp

QGpgME wird in GpgME als Sprachanbindung integriert und bietet eine API,
die sich an den Anforderungen von Qt-Anwendungsentwicklern orientiert.
GpgMEpp ist ein reines C++ Binding das die C-API von GpgME Objektorientiert
und mit C++ Ressourenverwaltung anbietet.

* Zielgruppe: Entwickler von Qt/C++-Anwendungen, die ein eigenes Benutzerinterface
implementieren.

* Begründung: Um die Möglichkeit zu haben, ein integriertes Benutzerinterface anzuzeigen,
wird es weiterhin nötig sein, eine Programmschnittstelle zu bieten, die unabhängig vom
Benutzerinterface ist. Hierbei wird neu sein,
dass die GnuPG-Logik in QGpgME zentral bereitgestellt wird und diese Teile nicht
mehr in Libkleo enthalten sind. QGpgME verwendet selbst noch zusätzlich den
reinen C++-Wrapper GpgMEpp, der hauptsächlich dazu dient Ressourcenverwaltung
mit C++-Mechanismen zu automatisieren.

* Vorraussetzungen: GpgME



=== 4. Libkleo

UI-Elemente für andere Qt/KDE-Frameworks-Anwendungen.

* Zielgruppe: Entwickler von Qt/KDE-Frameworks-Anwendungen. Kleopatra Entwickler.

* Begründung:
Libkleo wird Qt/KDE-UI-Elemente enthalten, die sowohl
in Kleopatra als auch in anderen Qt/KDE-Anwendungen (beispielsweise
Kontact Mail) verwendet werden können. Der Backend-Code aus Libkleo wird
entfernt und nach QGpgME verschoben, um anderen Qt-Anwendungen
diese API bereitzustellen, ohne sich an KDE-Frameworks und Qt-Widgets
binden zu müssen. Libkleo wird zu einer reinen UI-Bibliothek für
KDE-Frameworks bzw. Qt-Anwendungen.


==  Mail User Agent Anpassungen für EasyGPG

Im Folgenden wird anhand der Leistungsbeschreibung untersucht,
welche API-Änderungen nötig sind, um die Ziele des EasyGPG-Auftrags
in MUAs umzusetzen. Dabei wird jeweils die API von GpgME
und von QGpgME gelistet. QGpgME, da dies die höchste Abstraktionsschicht
der GpgME-Bibliothek darstellt und diese API die Unterstützung
in GpgMEpp und GpgME impliziert.

Wenn neue Benutzerschnitstellen nötig sind, werden diese in Libkleo
als Referenzimplementation implementiert. Wo sinnvoll, wird Kleopatra
diese später auf der Kommandozeile zusätzlich direkt aufrufbar
machen.

=== Schlüsselerzeugung

==== Fall 1: Es sind weder Konto noch Schlüssel vorhanden

===== Schritt 1: Prüfung
Ob ein geeigneter geheimer Schlüssel vorhanden ist, kann mit einem
Prozessaufruf und mit GpgME bereits umgesetzt werden.
{{{
    GpgME: gpgme_op_keylist_start(gpgme_ctx_t ctx, const char *pattern, int secret_only);
    QGpgME: QGpgMEKeyListJob::start(const QStringList &patterns, bool secretOnly)
}}}
Da für den Falle der Eindeutigkeit keine Nutzerinteraktion erforderlich ist,
entfällt hier UI.

===== Schritt 2: Schlüsselerstellung (nur ein Konto)
Die Schlüsselerstellung ist für ein Konto mit bestehender API umsetzbar:
{{{
    GpgME: gpgme_op_genkey_start (gpgme_ctx_t ctx, const char *parms, gpgme_data_t pubkey, gpgme_data_t seckey);
    QGpgME: GpgMEKeyGenerationJob::generate_key(Context *ctx, const QString &parameters)
}}}

Hierbei wird in den Parametern (eine Liste von Key-Value-Paaren)
bei der Schlüsselerstellung ein neuer Parameter
eingeführt, der ~GnuPG mitteilt, dass dieser Schlüssel auf dem OpenPGP-Webkey
Service veröffentlicht werden soll (siehe folgender Abschnitt "Schlüsselverteilung").

//TODO: Wo wird gespeichert, welches das aktuelle Zertifikat für eine Email-Adresse
für "webkey" Verteilung ist? Wie wird das ermittelt, wenn in der Übergangsphase
mehrere gültig sind? In welcher Komponente ist die Logik für die Auswahl? BER//

==== Fall 2: Es sind ein oder mehrere Konten, aber kein Schlüssel vorhanden
===== Schritt 1: Prüfung
Die Prüfung kann wie in Fall 1 erfolgen.


===== Schritt 2: Schlüsselerstellung (mehrere Konten):
Die Schlüsselerstellung mit mehreren UID's ist momentan in der API von ~GnuPG
nicht vorgesehen und muss erweitert werden.

Dazu wird ~GnuPG erweitert, so dass es eine kommaseparierte Liste an
user-id's akzeptiert. In den Parametern wird ein
weiteres Feld "Aliases:" einführt, ein neues Feld dient hierbei
dazu Abwärtskompatibilität zu erhalten.
Die Liste wird RFC 822 Adresslisten entsprechen, wobei jeweils Name und
Mailbox als Bestandteile der User-ID übermittelt werden. Wird kein
Name sondern nur eine Mailbox übergeben wird der Name der Primary User-ID
verwendet.

Als Kryptografieparameter werden die Standardeinstellungen des ~GnuPG-Systems
verwendet.

Kleopatra wird ebenso die Kommandozeilenoption {{{--gen-key}}} neu anbieten und
eine Adressliste zur Übermittlung von Alias-Optionen unterstützen. Dies
wird einen vorausgefüllten Zertifikatserstellungsdialog von Kleopatra
öffnen. Löscht der Nutzer hier einen Alias, sorgt dies dafür,
dass das Alias-entsprechenden Konto nicht mit einem Schlüssel verbunden wird.
Andernfalls werden die Konten nach der Erstellung mit dem neu erstellten
Zertifikat verbunden. Der entsprechende Dialog wird in Libkleo implementiert um somit
direkt in KDE/Qt Anwendungen eingebaut werden zu können.

Im Rahmen der Schlüsselerstellung wird deutlich darauf hingewiesen, wo das
~GnuPG-Heimatverzeichnis zu finden ist.

===== Fall 3: Sowohl Konten als auch Schlüsselpaare sind vorhanden

Nach dem erstmaligen Start eines MUAs, der EasyGPG unterstützt, wird
für alle existierende Konten geprüft, ob Schlüssel vorhanden sind.
Die Prüfung kann wie in Fall 2 erfolgen.

Der entsprechende Dialog in Libkleo wird hierzu um den Keycache von Kleopatra und
die Möglichkeit einer Vorfilterung (z.B. nur nach Zertifikaten mit den richtigen
Verwendungsflaggen und dem OpenPGP-Protokoll erweitert.

Die Zuordnung der einzelnen Schlüssel erfolgt im MUA, da diese Zuordnung
nachträglich auch in der Konten Konfiguration änderbar sein sollte.


=== Schlüsselverteilung

//Siehe auch Entwurf des OpenPGP Webkey Service: 
[[https://tools.ietf.org/html/draft-koch-openpgp-webkey-service-00#section-4| Web Key Directory Update Protocol]]//

Die Schlüsselverteilung wird durch GnuPG durchgeführt. Dabei werden Mails, die vom
MUA im Prozess der Verteilung empfangen werden, anhand des Content-Type identifiziert
und an GnuPG zur weiteren Verarbeitung vollständig übergeben. ~GnuPG wiederum
übergibt dem MUA Mails, die automatisch versendet werden sollten.


=== Schlüsselimport

==== Fall 1: Gültigen öffentlichen Schlüssel anhängen
Ist ein gültiger öffentlicher Schlüssel angehängt, kann dies anhand des Content-Type
oder der Dateiendung von MUA's erkannt werden. Diese können den mit bestehender
API importieren.
Der Import erfolgt dabei im Hintergrund.

{{{
    GpgME: gpgme_error_t gpgme_op_import_start (gpgme_ctx_t ctx, gpgme_data_t keydata);
    QGpgME: QGpgMEImportJob::exec(const QByteArray &certData)
}}}

Vom Vertrauensmodell wird dieser Schlüssel so angesehen, als käme er von einem
öffentlichen Schlüsselserver.

==== Fall 2: Beim Empfang signierter E-Mails automatisch den Schlüssel herunterladen

Dieser Fall wird in ~GnuPG bereits durch die Konfigurationsoption {{{auto-key-retrieve}}}
abgebildet. GnuPG muss hier erweitert werden, um bei Aktivierung der Option
die verschiedenen Möglichkeiten des Schlüsselabrufs zu unterstützen. Dies könnte
beispielsweise dadurch erfolgen, dass sich die {{{auto-key-locate}}} Option auch auf
{{{auto-key-retrieve}}} auswirkt.

Eine Anzeige des Imports erscheint hier nicht wünschenswert, da die fehlschlagende
Signaturprüfung klarstellen sollte, dass kein öffentlicher Schlüssel gefunden wurde und
somit den Negativfall erkennbar macht.


==== Fall 3: Verfassen einer verschlüsselten Mail

Ist die {{{auto-key-locate}}} Option entsprechend für ~EasyGPG gesetzt, lässt sich
dieser Fall durch das Kommando {{{locate-key}}} abdecken. In ~GpgME wird
dies durch ein Keylisting mit der Kombination der Modi "extern" und "local"
implementiert. Für ~QGpgME wird hierzu neue ~API in Form eines ~LocateKeysJob implementiert:
{{{
    GpgME: gpgme_error_t gpgme_op_keylist_start (gpgme_ctx_t ctx, const char *pattern, int secret_only);
    QGpgME: GpgME::KeyListResult QGpgMELocateKeysJob::exec(const QStringList &patterns);
}}}

Bei Mehrdeutigkeiten wird UI zum Auflösen des Zertifikats benötigt. Implementierende
MUA sollten automatisch das Zertifikat mit dem höheren Vertrauen auswählen. Dennoch
kann es nötig sein die Entscheidung zur Zertifikatsauswahl abzufragen. In diesem Fall
kann der bereits im Abschnitt Schlüsselerzeugung (Fall 3) erwähnte Zertifikatsauswahldialog
verwendet werden.

Das Vertrauen in den Schlüssel soll durch eine Gültigkeitsanzeige dargestellt werden.
Wird das TOFU-Vertrauensmodell verwendet, sollen in diesem Dialog zusätzlich
entsprechende Informationen angezeigt werden.

Die Referenzimplementation in Libkleo wird die Anzeige der TOFU-Informationen
und einen Status-Indikator enthalten.

==== Fall 4: Öffentlicher Schlüssel aus lokaler Datei

Ist beim Versenden einer Mail für einen Empfänger kein Zertifikat vorhanden, soll
ein MUA dies erkenntlich machen. z.B. durch einen Fragezeichen oder X hinter der
Empfängeraddresse. In diesem Fall kann beispielsweise durch Klick auf den Status der Zertifikatsimportdialog
geöffnet werden.

{{{
    GpgME: gpgme_error_t gpgme_op_import_start (gpgme_ctx_t ctx, gpgme_data_t keydata);
    QGpgME: GpgME::ImportResult QGpgME::QGpgMEImportJob::exec(const QByteArray &keyData)
    Kleopatra: kleopatra --import
}}}

Kleopatra wird dabei den Dateidialog und das Resultat des Imports selbst
anzeigen.

==== Fall 5: Import über URL-Verlinkung

Da das Aufrufen über URL's außerhalb der MUAs passiert, ist hier kein Handlungsbedarf
für implementierende MUAs. Dies ist durch Plattformintegration der Gesamtlösung zu erreichen,
damit genutzte Dateibrowser für die Zertifikats-MIME-Typen bzw. Dateiendungen ein Öffnen mit
Kleopatra/GPA oder ein Öffnen mit ~GnuPG anbieten.

Im Rahmen des Gpg4all-Projektes wurde für Gpg4win die
Nutzung von Dateizuordnungen inklusive Registration von MIME-Typen in Windows hinzugefügt.
Unter GNU/Linux-Systemen ist der übliche Weg sich zu registrieren durch die Installation
von "Desktop"-Dateien. Dies wird von Kleopatra bereits ausgeführt.

~GnuPG sollte sich zusätzlich mit "Desktop"-Dateien im System für diese MIME-Typen
registrieren bzw. unter Windows dies bei der Installation des Basispaketes durchführen.

Sollte dies nicht im Hauptstrom von ~GnuPG integriert werden können, kann dies durch
eine Paketierung bzw. Paketierungsempfehlung gewährleistet werden.

Damit dieser Mechanismus funktioniert, muss der entsprechende Server jedoch
den korrekten Content-Type {{{application/pgp-keys}}} senden.


=== Schlüsselverwaltung

==== Wechsel von Vertrauensmodellen

Der Wechsel von Vertrauensmodellen wird über GpgConf ermöglicht. Kleopatra
stellt einen generischen Konfigurationsdialog der GpgConf-Optionen zur
Verfügung und ermöglicht so die Änderung.

{{{
    GpgME: gpgme_error_t gpgme_conf_opt_change (gpgme_conf_opt_t opt, int reset, gpgme_conf_arg_t arg);
    QGpgME: QGpgMENewCryptoConfigEntry::setStringValue(const QString &str)
}}}

Der Konfigurationsdialog für ~GnuPG von Kleopatra steht als Plugin zur Verfügung und
kann als {{{KCModule}}} geladen und in Qt-Anwendungen eingebunden werden.


==== Der Erstempfang von Mails unbekannter Adressen muss angezeigt werden.

Beim Erstempfang von unbekannten Adressen wird das Zertifikat automatisch heruntergeladen
(siehe Schlüsselimport, Fall 2). Kann kein vertrauenswürdiges Zertifikat gefunden werden, wird
sich dies auf die Gültigkeit der Signatur auswirken {{{gpgme_signature_t->validity}}}.

Auf der Kommandozeile werden die TOFU-Informationen durch eine Statuszeile
TOFU-Trust zurückgegeben.

Der MUA muss wie bisher die Resultate der Signaturprüfung auswerten und zur Anzeige
bringen.

==== Schlüsselsauswahl bei Mehrdeutigkeiten

//Siehe Fall 3 der Schlüsselerzeugung.//

==== Abgelaufene Schlüssel von Kommunikationspartnern müssen ersetzt werden.

Soll ein abgelaufener Schlüssel verwendet werden, wird durch ~GnuPG ein neues
{{{locate-key}}} durchgeführt ohne lokale Quellen zu berücksichtigen. Dazu wird
entweder eine neue Konfigurationsoption (bspw. {{{auto-key-refresh}}}) eingeführt
oder das Verhalten von {{{auto-key-retrieve}}} entsprechend geändert.

==== Abgelaufene eigene Schlüssel müssen ersetzt werden.

Ist der mit einem Konto verknüpfte Schlüssel abgelaufen oder droht innerhalb
der nächsten 10 Tage abzulaufen, wird eine neue Schlüsselerstellung durchgeführt
und die entsprechenden Konten mit dem neuen Schlüssel verknüpft (siehe Schlüsselerzeugung).

==== Backup der jeweilige MUA muss die Möglichkeit bieten Schlüssel auf einfache Weise zu sichern und wiederherzustellen.

Die Umsetzung dieser Anforderung wird dem jeweiligen MUA überlassen. Das
Wiederherstellen wird bei der sonst erfolgenden Zertifikatserstellung angeboten.
Zum Sichern wird auf den Ort des ~GnuPG-Heimatverzeichnisses hingewiesen. Das
komplette Verzeichnis sollte gesichert werden.