Passa al contenuto principale

Convalida delle firme MD5 per i link sicuri di ONLYOFFICE Docs

Panoramica​

ONLYOFFICE Docs utilizza link sicuri con firme MD5 per proteggere l'accesso ai file nella cache. Questi link contengono i parametri md5 ed expires, vengono generati internamente dal servizio CoAuthoring e convalidati tramite NGINX.

Per convalidare o riprodurre questi hash MD5 (ad esempio, per implementare un proxy o un livello di sicurezza personalizzato), segui le istruzioni riportate di seguito.

Generazione della firma MD5​

La firma MD5 viene calcolata con la seguente formula:

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

Dove:

  • <expires> è il valore numerico del parametro di query expires nell'URL;
  • <uri> è il percorso completo della richiesta (senza dominio né stringa di query), a partire da /cache/files/...;
  • <secret> è il secret condiviso utilizzato da ONLYOFFICE Docs, di solito impostato tramite la variabile d'ambiente SECURE_LINK_SECRET o nei file di configurazione.

Per generare l'hash, segui questi passaggi:

  1. Concatena <expires>, <uri> e <secret> in un'unica stringa.

  2. Calcola l'MD5 binario (ad esempio, md5($string, true) in PHP).

  3. Codificalo in Base64.

  4. Converti la stringa Base64 in un formato sicuro per gli URL:

    • sostituendo + con -;
    • sostituendo / con _;
    • rimuovendo i = finali.

Configurazione del secret del link sicuro​

Il secret utilizzato per generare la firma del link sicuro può essere impostato in tre modi:

Importante

Tutti e tre i metodi di configurazione devono usare lo stesso valore del secret. Se il secret in local.json è diverso da quello in ds.conf, la convalida del link non riuscirà. È un problema frequente dopo gli aggiornamenti: assicurati che i valori siano sincronizzati.

  • Variabile d'ambiente (solo Docker)

    Imposta una variabile d'ambiente all'avvio del container:

    SECURE_LINK_SECRET=your_secret_here

  • File di configurazione local.json

    Imposta il parametro storage.fs.secretString nel file local.json, che si trova nel seguente percorso:

    • Per Windows - %ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json
    • Per Linux - /etc/onlyoffice/documentserver/local.json
    • Per Docker - /etc/onlyoffice/documentserver/local.json (all'interno del container Docker)
    {
      "storage": {
        "fs": {
          "secretString": "your_secret_here"
        }
      }
    }

  • File di configurazione NGINX

    Imposta il parametro $secure_link_secret nel file ds.conf, che si trova nel seguente percorso:

    • Per Windows - %ProgramFiles%\ONLYOFFICE\DocumentServer\nginx\conf\ds.conf
    • Per Linux - /etc/onlyoffice/documentserver/nginx/ds.conf
    • Per Docker - /etc/onlyoffice/documentserver/nginx/ds.conf (all'interno del container Docker)
    secure_link_md5 "$secure_link_expires$uri$secure_link_secret";
    secure_link $arg_md5,$arg_expires;

Esempio​

Consideriamo il seguente esempio:

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

Passaggio 1. Estrarre i parametri​

Estrai i seguenti parametri dall'URL:

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

Passaggio 2. Convalidare l'MD5 con PHP​

Il seguente esempio PHP mostra come generare e convalidare la firma MD5:

<?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";
?>

Passaggio 3. Confrontare le firme​

La funzione calcola la seguente firma MD5:

NS2_divLHhVBHdvvU9vbwA

Questa corrisponde al parametro md5 nell'URL. Pertanto, la richiesta è valida e può essere confermata.

Problemi noti​

  • Usa sempre l'URI, non l'URL completo.
  • Assicurati che il tuo secret corrisponda alla configurazione.
  • Non usare il parametro urlExpires per l'hashing. Questo parametro è definito in default.json (non in local.json) e controlla la configurazione della durata dei link, non il valore usato nella formula MD5. Usa sempre il valore effettivo di expires dalla stringa di query dell'URL.
  • Assicurati che la codifica Base64 sia sicura per gli URL.