验证 ONLYOFFICE 文档安全链接的 MD5 签名

概述

ONLYOFFICE 文档使用带有 MD5 签名的安全链接来保护对缓存文件的访问。这些链接包含 md5 和 expires 参数，由协同编辑服务内部生成，并通过 NGINX 进行验证。

要验证或重新生成这些 MD5 哈希值（例如，为了实现您自己的代理或安全层），请遵循以下说明。

生成 MD5 签名

MD5 签名使用以下公式计算：

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

其中：

• <expires> 是 URL 中 expires 查询参数的数值；
• <uri> 是完整的请求路径（不含域名或查询字符串），以 /cache/files/... 开头；
• <secret> 是 ONLYOFFICE 文档使用的共享密钥，通常通过 SECURE_LINK_SECRET 环境变量或在配置文件中设置。

要生成哈希值，请遵循以下步骤：

1. 将 <expires>、<uri> 和 <secret> 连接成一个字符串。
2. 计算二进制 MD5（例如，在 PHP 中使用 md5($string, true)）。
3. 使用 Base64 对其进行编码。

4. 通过以下方式将 Base64 字符串转换为 URL 安全格式：

   • 将 + 替换为 -；
   • 将 / 替换为 _；
   • 移除末尾的 =。

配置安全链接密钥

用于生成安全链接签名的密钥可以通过三种方式设置：

• 环境变量（仅限 Docker）

  在运行容器时设置环境变量：

  SECURE_LINK_SECRET=your_secret_here

• local.json 配置文件

  在 local.json 文件中设置 storage.fs.secretString 参数，该文件可在以下路径找到：

  • 对于 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 配置文件

  在 ds.conf 文件中设置 $secure_link_secret 参数，该文件可在以下路径找到：

  • 对于 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

<?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";
  
  // 组成字符串：<expires><uri><secure_link_secret>
  $string_to_hash = $expires . $uri . $secure_link_secret;
  
  // 计算 MD5 哈希值
  $md5_hash = md5($string_to_hash, true);
  
  // 编码为 Base64（URL 安全）
  $base64_hash = str_replace(
    ['+', '/', '='],
    ['-', '_', ''],
    base64_encode($md5_hash)
  );
  
  // 输出结果
  echo "String to hash: " . $string_to_hash . "\n";
  echo "Generated MD5 hash: " . $base64_hash . "\n";
  echo "Expected MD5 hash: NS2_divLHhVBHdvvU9vbwA\n";
  ?>

NS2_divLHhVBHdvvU9vbwA

已知问题

• 始终使用 URI，而不是完整的 URL。
• 确保您的密钥与配置一致。
• 不要使用 local.json 中的 urlExpires 进行哈希运算。请使用 URL 中的实际 expires 值。
• 确保 Base64 编码是 URL 安全的。