メインコンテンツまでスキップ

ONLYOFFICE Docsのセキュアリンクに対するMD5署名の検証

概要​

ONLYOFFICE Docsは、キャッシュされたファイルへのアクセスを保護するために、MD5署名付きのセキュアリンクを使用します。これらのリンクにはmd5パラメーターとexpiresパラメーターが含まれており、CoAuthoringサービスによって内部で生成され、NGINXを介して検証されます。

これらのMD5ハッシュを検証または再現するには（独自のプロキシやセキュリティレイヤーを実装する場合など）、以下の手順に従ってください。

MD5署名の生成​

MD5署名は、次の式を使用して計算されます：

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

ここで：

  • <expires>は、URLのexpiresクエリパラメーターの数値です；
  • <uri>は、/cache/files/...から始まる完全なリクエストパス（ドメインやクエリ文字列を含まない）です；
  • <secret>は、ONLYOFFICE Docsが使用する共有シークレットで、通常はSECURE_LINK_SECRET環境変数または設定ファイルで設定されます。

ハッシュを生成するには、次の手順に従います：

  1. <expires>、<uri>、<secret>を1つの文字列に連結します。

  2. バイナリMD5を計算します（例：PHPではmd5($string, true)）。

  3. Base64でエンコードします。

  4. 次の方法で、Base64文字列をURLセーフな形式に変換します：

    • +を-に置き換える；
    • /を_に置き換える；
    • 末尾の=を削除する。

セキュアリンクのシークレットの設定​

セキュアリンクの署名を生成するために使用するシークレットは、3つの方法で設定できます：

重要

3つの設定方法すべてで、同じシークレットの値を使用する必要があります。local.jsonのシークレットがds.confのシークレットと異なる場合、リンクの検証は失敗します。これはアップデート後によくある問題です。値が一致していることを確認してください。

  • 環境変数（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

ステップ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. PHPを使用してMD5を検証する​

次の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

これはURLのmd5パラメーターと一致します。したがって、このリクエストは有効であり、確認できます。

既知の問題​

  • 完全なURLではなく、常にURIを使用してください。
  • シークレットが設定と一致していることを確認してください。
  • ハッシュ化にurlExpiresパラメーターを使用しないでください。このパラメーターはdefault.json（local.jsonではない）で定義されており、リンクの有効期間の設定を制御するもので、MD5の式で使用される値ではありません。常にURLのクエリ文字列にある実際のexpiresの値を使用してください。
  • Base64エンコードがURLセーフであることを確認してください。