Zum Hauptinhalt springen

Validierung von MD5-Signaturen für sichere Links in ONLYOFFICE Docs

Überblick​

ONLYOFFICE Docs verwendet sichere Links mit MD5-Signaturen, um den Zugriff auf zwischengespeicherte Dateien zu schützen. Diese Links enthalten die Parameter md5 und expires, werden intern vom CoAuthoring-Dienst erzeugt und über NGINX validiert.

Um diese MD5-Hashes zu validieren oder nachzubilden (z. B. für die Implementierung eines eigenen Proxys oder einer eigenen Sicherheitsschicht), folgen Sie den nachstehenden Anweisungen.

MD5-Signatur erzeugen​

Die MD5-Signatur wird nach folgender Formel berechnet:

md5 = BASE64URL(MD5(<expires><uri><secret>))

Dabei gilt:

  • <expires> ist der numerische Wert des Abfrageparameters expires in der URL;
  • <uri> ist der vollständige Anfragepfad (ohne Domain und Abfragezeichenfolge), beginnend mit /cache/files/...;
  • <secret> ist das von ONLYOFFICE Docs verwendete gemeinsame Secret, das in der Regel über die Umgebungsvariable SECURE_LINK_SECRET oder in den Konfigurationsdateien festgelegt wird.

Um den Hash zu erzeugen, gehen Sie wie folgt vor:

  1. Verketten Sie <expires>, <uri> und <secret> zu einer einzigen Zeichenfolge.

  2. Berechnen Sie den binären MD5-Wert (z. B. md5($string, true) in PHP).

  3. Kodieren Sie ihn mit Base64.

  4. Wandeln Sie die Base64-Zeichenfolge in ein URL-sicheres Format um, indem Sie:

    • + durch - ersetzen;
    • / durch _ ersetzen;
    • abschließende = entfernen.

Secret für sichere Links konfigurieren​

Das Secret, mit dem die Signatur des sicheren Links erzeugt wird, kann auf drei Arten festgelegt werden:

Wichtig

Alle drei Konfigurationsmethoden müssen denselben Secret-Wert verwenden. Wenn sich das Secret in local.json von dem in ds.conf unterscheidet, schlägt die Linkvalidierung fehl. Dies ist ein häufiges Problem nach Updates — stellen Sie sicher, dass die Werte übereinstimmen.

  • Umgebungsvariable (nur Docker)

    Legen Sie beim Starten des Containers eine Umgebungsvariable fest:

    SECURE_LINK_SECRET=your_secret_here

  • Konfigurationsdatei local.json

    Legen Sie den Parameter storage.fs.secretString in der Datei local.json fest, die sich unter folgendem Pfad befindet:

    • Für Windows - %ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json
    • Für Linux - /etc/onlyoffice/documentserver/local.json
    • Für Docker - /etc/onlyoffice/documentserver/local.json (innerhalb des Docker-Containers)
    {
      "storage": {
        "fs": {
          "secretString": "your_secret_here"
        }
      }
    }

  • NGINX-Konfigurationsdatei

    Legen Sie den Parameter $secure_link_secret in der Datei ds.conf fest, die sich unter folgendem Pfad befindet:

    • Für Windows - %ProgramFiles%\ONLYOFFICE\DocumentServer\nginx\conf\ds.conf
    • Für Linux - /etc/onlyoffice/documentserver/nginx/ds.conf
    • Für Docker - /etc/onlyoffice/documentserver/nginx/ds.conf (innerhalb des Docker-Containers)
    secure_link_md5 "$secure_link_expires$uri$secure_link_secret";
    secure_link $arg_md5,$arg_expires;

Beispiel​

Betrachten wir folgendes Beispiel:

https://example.com/cache/files/data/31.172.71.235__172.18.0.2new.docx1749812378403_5169/output.docx/output.docx?md5=NS2_divLHhVBHdvvU9vbwA&expires=1749813362

Schritt 1. Parameter extrahieren​

Extrahieren Sie die folgenden Parameter aus der URL:

  • expires: "1749813362";
  • uri: "/cache/files/data/31.172.71.235__172.18.0.2new.docx1749812378403_5169/output.docx/output.docx";
  • secret: "eNk2pNcaoWYTkpR7YWxe".

Schritt 2. MD5 mit PHP validieren​

Das folgende PHP-Beispiel zeigt, wie die MD5-Signatur erzeugt und validiert wird:

<?php
$expires = "1749813362";
$uri = "/cache/files/data/31.172.71.235__172.18.0.2new.docx1749812378403_5169/output.docx/output.docx";
$secure_link_secret = "eNk2pNcaoWYTkpR7YWxe";
// Form the string:<expires><uri><secure_link_secret>
$string_to_hash = $expires . $uri . $secure_link_secret;
// Calculate MD5 hash
$md5_hash = md5($string_to_hash, true);
// Encode to Base64 (URL-safe)
$base64_hash = str_replace(
  ['+', '/', '='],
  ['-', '_', ''],
  base64_encode($md5_hash)
);
// Output the result
echo "String to hash: " . $string_to_hash . "\n";
echo "Generated MD5 hash: " . $base64_hash . "\n";
echo "Expected MD5 hash: NS2_divLHhVBHdvvU9vbwA\n";
?>

Schritt 3. Signaturen vergleichen​

Die Funktion berechnet folgende MD5-Signatur:

NS2_divLHhVBHdvvU9vbwA

Diese stimmt mit dem Parameter md5 in der URL überein. Die Anfrage ist daher gültig und kann bestätigt werden.

Bekannte Probleme​

  • Verwenden Sie immer die URI, nicht die vollständige URL.
  • Stellen Sie sicher, dass Ihr Secret mit der Konfiguration übereinstimmt.
  • Verwenden Sie den Parameter urlExpires nicht für das Hashing. Dieser Parameter ist in default.json (nicht in local.json) definiert und steuert die Konfiguration der Link-Lebensdauer, nicht den in der MD5-Formel verwendeten Wert. Verwenden Sie immer den tatsächlichen expires-Wert aus der Abfragezeichenfolge der URL.
  • Stellen Sie sicher, dass die Base64-Kodierung URL-sicher ist.