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

• Benno Web — веб-интерфейс для прямого взаимодействия с пользователем
• rest.php — оболочка для REST API с аутентификацией и контролем доступа.

Фронтенд для поиска в Benno MailArchiv не работает напрямую с индексом Lucene, а отправляет HTTP-запросы на REST-интерфейс, который выполняет поиск с помощью 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.

Этот интерфейс, как правило, обладает следующими свойствами:

• Возвращаемые значения вызовов функций передаются в формате JSON (например, список электронных писем, найденных в ответ на поисковый запрос, возвращается в виде списка объектов JSON).
• Возвращаемые значения закодированы в 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.

На следующем рисунке показана архитектура Benno MailArchiv и интеграция API в систему:

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.

Поскольку теоретически оба контекста не обязательно должны работать на одном сервере, доступ к бэкэнду обеспечивается общим секретным ключом. Соответственно, сервер Benno MailArchiv, на котором запущен фронтенд, имеет доступ к бэкэнд-серверу только в том случае, если общий секретный ключ идентичен с обеих сторон.

Benno MailArchiv API необходимо учитывать следующие аспекты безопасности.

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.

Аутентификация с использованием общего секрета выполняется (как указано выше) по протоколу 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.

Примечание: Аутентификация HTTP Basic Auth основана на двух факторах: «Имя пользователя» и «Пароль». Имя пользователя всегда должно быть «benno2». Пароль — это общий секретный ключ, хранящийся на сервере.

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.

Поскольку идентификатор однозначно идентифицирует конкретное электронное письмо в архиве, этот идентификатор, как и общий секретный ключ, не следует передавать пользователю напрямую! Знание идентификатора позволяет получить доступ к соответствующему электронному письму в архиве.

Примечание: В веб-приложении Benno MailArchiv фактические идентификаторы писем в списке результатов поиска скрыты от пользователя путем переназначения их временным идентификаторам в теневой таблице в течение соответствующей сессии. Если пользователь видит идентификаторы писем в списке результатов поиска, они бесполезны, поскольку не соответствуют исходным идентификаторам заархивированных писем. Поэтому любая прямая попытка доступа к письму с таким временным идентификатором завершится неудачей.

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.

Контейнер настраивается в конфигурационном файле benno.xml следующим образом:

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

Электронное письмо с идентификатором BennoID 2021:A430E04B02D18112964BF2956BB52A4DEF928266DB59E0E9A1E94FD52FD0E05E00 найти по пути 2021/A4/30/E0/4B02D18112964BF2956BB52A4DEF928266DB59E0E9A1E94FD52FD0E05E00.gz в каталоге репозитория /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.