Перейти к основному содержимому

Проверка MD5-подписей защищенных ссылок ONLYOFFICE Docs

Обзор​

ONLYOFFICE Docs использует защищенные ссылки с MD5-подписями, чтобы защитить доступ к кэшированным файлам. Такие ссылки содержат параметры md5 и expires, генерируются внутри сервиса CoAuthoring и проверяются с помощью NGINX.

Чтобы проверить или воспроизвести эти MD5-хэши (например, для реализации собственного прокси или уровня безопасности), следуйте приведенным ниже инструкциям.

Генерация MD5-подписи​

MD5-подпись вычисляется по следующей формуле:

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

Где:

  • <expires> — числовое значение параметра запроса expires в URL-адресе;
  • <uri> — полный путь запроса (без домена и строки запроса), начинающийся с /cache/files/...;
  • <secret> — общий секрет, используемый ONLYOFFICE Docs; обычно задается с помощью переменной окружения SECURE_LINK_SECRET или в файлах конфигурации.

Чтобы сгенерировать хэш, выполните следующие действия:

  1. Объедините <expires>, <uri> и <secret> в одну строку.

  2. Вычислите двоичный MD5-хэш (например, md5($string, true) в PHP).

  3. Закодируйте его в Base64.

  4. Преобразуйте строку Base64 в формат, безопасный для URL:

    • замените + на -;
    • замените / на _;
    • удалите завершающие символы =.

Настройка секрета защищенных ссылок​

Секрет, используемый для генерации подписи защищенной ссылки, можно задать тремя способами:

Важно

Во всех трех способах настройки должно использоваться одно и то же значение секрета. Если секрет в файле local.json отличается от секрета в файле ds.conf, проверка ссылок завершится ошибкой. Это частая проблема после обновлений — убедитесь, что значения совпадают.

  • Переменная окружения (только для Docker)

    Задайте переменную окружения при запуске контейнера:

    SECURE_LINK_SECRET=your_secret_here

  • Файл конфигурации local.json

    Задайте параметр storage.fs.secretString в файле local.json, который находится по следующему пути:

    • Для Windows — %ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json
    • Для Linux — /etc/onlyoffice/documentserver/local.json
    • Для Docker — /etc/onlyoffice/documentserver/local.json (внутри Docker-контейнера)
    {
      "storage": {
        "fs": {
          "secretString": "your_secret_here"
        }
      }
    }

  • Файл конфигурации NGINX

    Задайте параметр $secure_link_secret в файле ds.conf, который находится по следующему пути:

    • Для Windows — %ProgramFiles%\ONLYOFFICE\DocumentServer\nginx\conf\ds.conf
    • Для Linux — /etc/onlyoffice/documentserver/nginx/ds.conf
    • Для Docker — /etc/onlyoffice/documentserver/nginx/ds.conf (внутри Docker-контейнера)
    secure_link_md5 "$secure_link_expires$uri$secure_link_secret";
    secure_link $arg_md5,$arg_expires;

Пример​

Рассмотрим следующий пример:

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

Шаг 1. Извлеките параметры​

Извлеките из URL-адреса следующие параметры:

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

Шаг 2. Проверьте MD5 с помощью PHP​

В следующем примере на PHP показано, как сгенерировать и проверить 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";
?>

Шаг 3. Сравните подписи​

Функция вычисляет следующую MD5-подпись:

NS2_divLHhVBHdvvU9vbwA

Она совпадает с параметром md5 в URL-адресе. Следовательно, запрос действителен и может быть подтвержден.

Известные проблемы​

  • Всегда используйте URI, а не полный URL-адрес.
  • Убедитесь, что ваш секрет совпадает с указанным в конфигурации.
  • Не используйте для хэширования параметр urlExpires. Этот параметр задается в файле default.json (а не в local.json) и управляет настройкой срока действия ссылок, а не значением, используемым в формуле MD5. Всегда используйте фактическое значение expires из строки запроса URL-адреса.
  • Убедитесь, что кодировка Base64 безопасна для URL.