Das REST-Interface ist in „benno-rest“ umgesetzt und implementiert das REST API.

• Benno Web - Web-UI für direkte Benutzer-Interaktion
• rest.php - REST API Wrapper mit Authentisierung und Zugriffssteuerung

Ein Frontend zur Suche in Benno MailArchiv arbeitet nicht direkt auf dem Lucene-Index, sondern setzt HTTP Requests an das REST-Interface ab, welches die Suche mit Hilfe von Lucene durchführt.

Die Konfiguration für der Pfade für Index und Repository wird aus der Datei „/etc/benno/benno.xml“ gelesen. Die Einstellungen für den integrierten HTTP Server des REST Interfaces werden in der Datei „/etc/benno/jetty.xml“ hinterlegt (siehe auch: Benno REST mit SSL-Verschlüsselung.

Dieses Interface weist generell die folgenden Eigenschaften auf:

• Die Rückgabewerte der Funktionsaufrufe werden im JSON-Format übergeben (bspw. wird die Liste der auf eine Suchanfrage hin gefundenen E-Mails als Liste von JSON-Objekten zurück gegeben).
• Die Rückgabewerte sind UTF-8 codiert.
• Die Rückgabe einer aus dem Archiv gelesenen bzw. angeforderten E-Mail kann sowohl im JSON Format (also als Array von JSON Objekten) oder im „raw“-Format (also RFC 822, bzw. RFC 2822, Plaintext) erfolgen.
• Anfragen über die API an den Benno MailArchiv Server sind aus Sicherheitsgründen nur möglich, wenn sich das aufrufende Programm gegenüber dem Server authentisiert. Die Authentisierung erfolgt mittels HTTP Basic Authentication. Details siehe bspw.: http://de.wikipedia.org/wiki/HTTP-Authentifizierung und weiter: http://tools.ietf.org/html/rfc2617
• Alle API-Calls gegenüber dem Benno MailArchiv Server sollten als HTTP POST-Requests ausgeführt werden.

Jeglicher Zugriff aus der Benutzerperspektive auf Benno MailArchiv erfolgt ausschließlich über die API. D.h.: Außerhalb der API sind keine Zugriffsmöglichkeiten auf Benno MailArchiv implementiert. Auch die Benno MailArchiv WebApp, also die reguläre GUI für den Anwender, greift ausschließlich über diese API auf Benno MailArchiv zu.

Nachstehende Grafik verdeutlicht die Architektur von Benno MailArchiv und die Einbettung der API in das System:

Wie das obige Schaubild aufzeigt, ist Benno MailArchiv in einer Multi-Tier-Architektur implementiert. Das Benno MailArchiv Backend (bzw. der „Core“-Kontext) ist logisch vom Frontend („User Interface“-Kontext bzw. der API) getrennt. Diese Architektur erlaubt es prinzipiell, die beiden Kontexte (bzw. Backend und Frontend) netzwerktransparent auf unterschiedlichen Servern zu betreiben.

Da die beiden Kontexte theoretisch nicht auf dem gleichen Server laufen müssen, ist ein Zugriff auf das Backend durch ein zu vergebendes Shared Secret abgesichert. Ein Benno MailArchiv Server, auf dem das Frontend läuft, hat demgemäß nur dann Zugriff auf den Backend Server, wenn das Shared Secret auf beiden Seiten identisch ist.

Bei der Verwendung der Benno MailArchiv API sind folgende Sicherheitsaspekte unbedingt zu bedenken.

Das Shared Secret ist der „Schlüssel“, um über das Frontend bzw. die API Zugriff auf das Backend des Benno MailArchiv Servers zu erhalten. Fällt das Shared Secret in falsche Hände, ist das Backend (und damit die Summe der archivierten E-Mails) nicht mehr wirksam vor Fremdzugriffen geschützt. Das Shared Secret selbstverständlich kann jederzeit einfach geändert werden.

Die Authentisierung mit dem Shared Secret erfolgt (wie oben erwähnt) als HTTP Basic Auth.

Wir warnen eindringlich davor, das Shared Secret in browser-basierten Web-Anwendungen im URL zu übergeben! Das Shared Secret ist hier unverschlüsselt sichtbar und kann so leicht in falsche Hände gelangen! In der ausgelieferten Konfiguration werden alle Requests über das Loopback-Device abgewickelt, so daß hier keine Daten über das Netzwerk geschickt werden. Falls das Setup jedoch eine Trennung von Frontend und REST-Backend vorsieht, muß die Kommunikation mit benno-rest verschlüsselt durchgeführt werden. Die SSL-Konfiguration des benno-rest Daemons ist hier beschrieben.

Wir empfehlen, die Authentisierung gegen das REST-API so zu gestalten, dass der Benutzer keinerlei Möglichkeiten hat, diese (bspw. über den URL usw.) einzusehen oder zu manipulieren. Die Implementierung sollte hier anhand eines Proxy oder eines ähnlichen Entwurfsmusters erfolgen. Konkret kann dieses z.B. sehr einfach durch einen vorgeschalteten HTTP-Server mit einem CGI-Script durchgeführt werden.

Hinweis: Die HTTP Basic Auth Authentifizierung basiert auf den beiden Faktoren „Username“ und „Password“. Als Username ist grundsätzlich „benno2“ zu verwenden. Das Passwort ist das auf dem Server hinterlegte Shared Secret.

Die API greift (im Gegensatz zur Benno MailArchiv WebApp!) uneingeschränkt auf alle E-Mails des Archivs zu. D.h., dass jede Suchanfrage Treffer unabhängig von etwaigen Benutzerberechtigungen, die in der WebApp eingerichtet sind, zurückliefert!

Mittels entsprechender Filterparameter kann eine Suchanfrage auf bestimmte E-Mails eingeschränkt werden (bspw. E-Mails eines bestimmten Benutzers). Die Filterparameter sind (soweit eine solche Filterung erfolgen soll) beim API Aufruf anzugeben.

Die API selbst greift nicht! auf die Benno MailArchiv Benutzerverwaltung der WebApp zurück! Die Durchsetzung der Filterung bzw. die Durchsetzung von Zugriffsbeschränkungen ist durch das aufrufende Programm, das diese API verwendet, selber zu implementieren!

Alle archivierten E-Mails haben eine eindeutige ID (BennoID), über die der direkte Zugriff auf die jeweilige E-Mail möglich ist. Ähnlich wie das Shared Secret stellt diese eindeutige ID einen sicherheitsrelevanten Aspekt dar.

Da eine ID eindeutig eine bestimmte E-Mail im Archiv adressiert, sollte diese ID ebenso wenig wie das Shared Secret direkt an den Benutzer weiter gegeben werden! Die Kenntnis der ID ermöglicht den Zugriff auf die zugehörige E-Mail im Archiv.

Hinweis: In der Benno MailArchiv WebApp werden die tatsächlichen IDs der E-Mails der Trefferliste vor dem Anwender verborgen, in dem sie in der jeweiligen Session in einer Schattentabelle auf temporäre IDs umgemapt werden. Sieht ein Anwender die IDs der E-Mails einer Trefferliste, so sind diese wertlos, da sie nicht den Original-IDs der archivierten Mails entsprechen. Ein direkter Zugriffsversuch auf eine Mail mit einer solchen temporären ID führt daher ins Leere.

Die BennoID setzt sich aus dem Bezeichner für die Box und der Checksumme der E-Mail zusammen. Beide Token werden per Doppelpunkt getrennt. Die BennoID wird als Pfad relativ zum Repo-Verzeichnis des Containers aufgelöst.

Der Container ist in der Konfigurationsdatei benno.xml wie folgt konfiguriert:

<yearlyfsbox>
  <fshexbennobox>
    <monthlyfsjournal/>
    <directory>/srv/benno/archive/repo</directory>
    <subdirs>3</subdirs>
    <dirlength>2</dirlength>
    <compression>gzip</compression>
  </fshexbennobox>
</yearlyfsbox>

In dieser Standardkonfiguration wird die Box als Jahreszahl (<yearlyfsbox />) abgebildet.¹⁾

Die Checksumme der BennoID wird in 3 Unterverzeichnisse (<subdirs />) mit einer Länge von 2 Zeichen (<dirlength />) unterteilt.

Eine E-Mail mit der BennoID 2021:A430E04B02D18112964BF2956BB52A4DEF928266DB59E0E9A1E94FD52FD0E05E00 ist im Pfad 2021/A4/30/E0/4B02D18112964BF2956BB52A4DEF928266DB59E0E9A1E94FD52FD0E05E00.gz unterhalb des Repo-Verzeichnisses /srv/benno/archive/repo zu finden.

Es ist dem Softwareentwickler bzw. Programmierer, der diese API verwendet, selbstverständlich frei gestellt, diese sicherheitsrelevanten Hinweise zu ignorieren, wir raten jedoch dazu, sie insbes. dann zu beachten, wenn die API zur Integration der Benno MailArchiv-Funktionen in Web-Anwendungen erfolgen soll, um eine nachhaltig sichere und unkompromittierbare Lösung zu entwickeln.

Das Web-Frontend implementiert einen Client für das Benno MailArchiv REST API. In diesem Paket ist zusätzlich ein in Perl implementierter Kommandozeilenclient (benno-client) enthalten, der als einfaches Beispiel und für Testzwecke bei der implementierung eines eigenen Frontends dienen kann.