Aller au contenu principal

Validation des signatures MD5 pour les liens sécurisés d'ONLYOFFICE Docs

Aperçu​

ONLYOFFICE Docs utilise des liens sécurisés avec des signatures MD5 pour protéger l'accès aux fichiers en cache. Ces liens contiennent les paramètres md5 et expires ; ils sont générés en interne par le service CoAuthoring et validés via NGINX.

Pour valider ou reproduire ces hachages MD5 (par exemple, pour mettre en place votre propre proxy ou couche de sécurité), suivez les instructions ci-dessous.

Génération de la signature MD5​

La signature MD5 est calculée selon la formule suivante :

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

Où :

  • <expires> est la valeur numérique du paramètre de requête expires de l'URL ;
  • <uri> est le chemin complet de la requête (sans domaine ni chaîne de requête), à partir de /cache/files/... ;
  • <secret> est le secret partagé utilisé par ONLYOFFICE Docs, généralement défini via la variable d'environnement SECURE_LINK_SECRET ou dans les fichiers de configuration.

Pour générer le hachage, procédez comme suit :

  1. Concaténez <expires>, <uri> et <secret> en une seule chaîne.

  2. Calculez le MD5 binaire (par exemple, md5($string, true) en PHP).

  3. Encodez-le en Base64.

  4. Convertissez la chaîne Base64 dans un format compatible avec les URL en :

    • remplaçant + par - ;
    • remplaçant / par _ ;
    • supprimant les = de fin.

Configuration du secret du lien sécurisé​

Le secret utilisé pour générer la signature du lien sécurisé peut être défini de trois façons :

Important

Les trois méthodes de configuration doivent utiliser la même valeur de secret. Si le secret dans local.json diffère de celui dans ds.conf, la validation du lien échouera. C'est un problème fréquent après les mises à jour — assurez-vous que les valeurs sont synchronisées.

  • Variable d'environnement (Docker uniquement)

    Définissez une variable d'environnement lors du lancement du conteneur :

    SECURE_LINK_SECRET=your_secret_here

  • Fichier de configuration local.json

    Définissez le paramètre storage.fs.secretString dans le fichier local.json, qui se trouve à l'emplacement suivant :

    • Pour Windows - %ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json
    • Pour Linux - /etc/onlyoffice/documentserver/local.json
    • Pour Docker - /etc/onlyoffice/documentserver/local.json (au sein du conteneur Docker)
    {
      "storage": {
        "fs": {
          "secretString": "your_secret_here"
        }
      }
    }

  • Fichier de configuration NGINX

    Définissez le paramètre $secure_link_secret dans le fichier ds.conf, qui se trouve à l'emplacement suivant :

    • Pour Windows - %ProgramFiles%\ONLYOFFICE\DocumentServer\nginx\conf\ds.conf
    • Pour Linux - /etc/onlyoffice/documentserver/nginx/ds.conf
    • Pour Docker - /etc/onlyoffice/documentserver/nginx/ds.conf (au sein du conteneur Docker)
    secure_link_md5 "$secure_link_expires$uri$secure_link_secret";
    secure_link $arg_md5,$arg_expires;

Exemple​

Prenons l'exemple suivant :

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

Étape 1. Extraire les paramètres​

Extrayez les paramètres suivants de l'URL :

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

Étape 2. Valider le MD5 avec PHP​

L'exemple PHP suivant montre comment générer et valider la signature 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";
?>

Étape 3. Comparer les signatures​

La fonction calcule la signature MD5 suivante :

NS2_divLHhVBHdvvU9vbwA

Elle correspond au paramètre md5 de l'URL. La requête est donc valide et peut être confirmée.

Problèmes connus​

  • Utilisez toujours l'URI, pas l'URL complète.
  • Assurez-vous que votre secret correspond à la configuration.
  • N'utilisez pas le paramètre urlExpires pour le hachage. Ce paramètre est défini dans default.json (et non dans local.json) et contrôle la configuration de la durée de vie des liens, pas la valeur utilisée dans la formule MD5. Utilisez toujours la valeur réelle de expires issue de la chaîne de requête de l'URL.
  • Assurez-vous que l'encodage Base64 est compatible avec les URL.