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

• Benno Web - Interface utilisateur Web pour l'interaction directe avec l'utilisateur
• rest.php REST d'API avec authentification et contrôle d'accès

L'interface de recherche de Benno MailArchiv ne fonctionne pas directement sur l'index Lucene, mais envoie des requêtes HTTP à l'interface REST, qui effectue la recherche à l'aide de Lucene.

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.

Cette interface possède généralement les propriétés suivantes :

• Les valeurs de retour des appels de fonction sont transmises au format JSON (par exemple, la liste des adresses électroniques trouvées en réponse à une requête de recherche est renvoyée sous forme de liste d'objets JSON).
• Les valeurs de retour sont encodées en 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.

Le graphique suivant illustre l'architecture de Benno MailArchiv et l'intégration de l' API dans le système :

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.

Étant donné que les deux contextes n'ont théoriquement pas besoin de s'exécuter sur le même serveur, l'accès au serveur dorsal est sécurisé par un secret partagé. Par conséquent, un serveur Benno MailArchiv exécutant le frontend n'a accès au serveur dorsal que si le secret partagé est identique des deux côtés.

Benno MailArchiv API , les aspects de sécurité suivants doivent être pris en compte.

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.

L'authentification utilisant le secret partagé est effectuée (comme mentionné ci-dessus) comme une authentification HTTP de base.

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.

Remarque : L’authentification HTTP Basic Auth repose sur deux facteurs : « Nom d’utilisateur » et « Mot de passe ». Le nom d’utilisateur doit toujours être « benno2 ». Le mot de passe est le secret partagé stocké sur le serveur.

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.

Puisqu'un identifiant permet d'accéder de manière unique à un courriel spécifique dans les archives, cet identifiant, tout comme le secret partagé, ne doit pas être communiqué directement à l'utilisateur ! La connaissance de cet identifiant permet d'accéder au courriel correspondant dans les archives.

Remarque : Dans l’application web Benno MailArchiv, les identifiants réels des e-mails affichés dans les résultats de recherche sont masqués à l’utilisateur. Ils sont remplacés par des identifiants temporaires stockés dans une table fantôme durant la session. Si un utilisateur voit ces identifiants dans les résultats de recherche, ils sont inutilisables car ils ne correspondent pas aux identifiants originaux des e-mails archivés. Par conséquent, toute tentative d’accès direct à un e-mail à l’aide d’un tel identifiant temporaire échouera.

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.

Le conteneur est configuré dans le fichier de configuration benno.xml comme suit :

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

Un e-mail avec le BennoID 2021:A430E04B02D18112964BF2956BB52A4DEF928266DB59E0E9A1E94FD52FD0E05E00 être trouvé dans le chemin 2021/A4/30/E0/4B02D18112964BF2956BB52A4DEF928266DB59E0E9A1E94FD52FD0E05E00.gz sous le répertoire du dépôt /srv/benno/archive/repo .

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.