Das Web-Frontend von 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. Das REST-Interface ist in „benno-rest“ umgesetzt und implementiert das Benno MailArchiv REST API.

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.

This interface generally has the following properties:

• The return values ​​of the function calls are passed in JSON format (e.g., the list of emails found in response to a search query is returned as a list of JSON objects).
• The return values ​​are encoded in UTF-8.
• 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.

The following graphic illustrates the architecture of Benno MailArchiv and the integration of the API into the 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.

Since the two contexts theoretically do not have to run on the same server, access to the backend is secured by a shared secret. Accordingly, a Benno MailArchiv server running the frontend only has access to the backend server if the shared secret is identical on both sides.

When using the Benno MailArchiv API , the following security aspects must be taken into account.

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.

Authentication using the shared secret is performed (as mentioned above) as 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.

Note: HTTP Basic Auth authentication is based on two factors: "Username" and "Password". The username should always be "benno2". The password is the shared secret stored on the server.

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, ü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.

Since an ID uniquely addresses a specific email in the archive, this ID, like the shared secret, should not be directly shared with the user! Knowing the ID allows access to the corresponding email in the archive.

Note: In the Benno MailArchiv web app, the actual IDs of the emails in the search results list are hidden from the user by being remapped to temporary IDs in a shadow table during the respective session. If a user sees the IDs of the emails in a search results list, these are worthless because they do not correspond to the original IDs of the archived emails. Therefore, any direct attempt to access an email with such a temporary ID will fail.

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 (/usr/share/doc/benno-web/contrib/benno-client) enthalten, der als einfaches Beispiel und für Testzwecke bei der implementierung eines eigenen Frontends dienen kann.