Ana içeriğe geç

ONLYOFFICE Docs güvenli bağlantıları için MD5 imzalarını doğrulama

Genel bakış​

ONLYOFFICE Docs, önbellekteki dosyalara erişimi korumak için MD5 imzalı güvenli bağlantılar kullanır. Bu bağlantılar md5 ve expires parametrelerini içerir, CoAuthoring hizmeti tarafından dahili olarak oluşturulur ve NGINX aracılığıyla doğrulanır.

Bu MD5 karmalarını doğrulamak veya yeniden üretmek için (örneğin kendi proxy'nizi veya güvenlik katmanınızı uygularken) aşağıdaki yönergeleri izleyin.

MD5 imzası oluşturma​

MD5 imzası aşağıdaki formülle hesaplanır:

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

Burada:

  • <expires>, URL'deki expires sorgu parametresinin sayısal değeridir;
  • <uri>, alan adı ve sorgu dizesi olmadan, /cache/files/... ile başlayan tam istek yoludur;
  • <secret>, ONLYOFFICE Docs tarafından kullanılan ortak gizli anahtardır ve genellikle SECURE_LINK_SECRET ortam değişkeniyle veya yapılandırma dosyalarında ayarlanır.

Karmayı oluşturmak için şu adımları izleyin:

  1. <expires>, <uri> ve <secret> değerlerini tek bir dizede birleştirin.

  2. İkili MD5'i hesaplayın (örneğin PHP'de md5($string, true)).

  3. Sonucu Base64 ile kodlayın.

  4. Base64 dizesini URL için güvenli biçime dönüştürün:

    • + karakterini - ile değiştirin;
    • / karakterini _ ile değiştirin;
    • sondaki = karakterlerini kaldırın.

Güvenli bağlantı gizli anahtarını yapılandırma​

Güvenli bağlantı imzasını oluşturmak için kullanılan gizli anahtar üç şekilde ayarlanabilir:

Önemli

Her üç yapılandırma yönteminde de aynı gizli anahtar değeri kullanılmalıdır. local.json dosyasındaki gizli anahtar ds.conf dosyasındakinden farklıysa bağlantı doğrulaması başarısız olur. Bu, güncellemelerden sonra sık görülen bir sorundur, değerlerin eşleştiğinden emin olun.

  • Ortam değişkeni (yalnızca Docker)

    Kapsayıcıyı çalıştırırken bir ortam değişkeni ayarlayın:

    SECURE_LINK_SECRET=your_secret_here

  • local.json yapılandırma dosyası

    Aşağıdaki yolda bulunabilen local.json dosyasında storage.fs.secretString parametresini ayarlayın:

    • Windows için - %ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json
    • Linux için - /etc/onlyoffice/documentserver/local.json
    • Docker için - /etc/onlyoffice/documentserver/local.json (Docker kapsayıcısının içinde)
    {
      "storage": {
        "fs": {
          "secretString": "your_secret_here"
        }
      }
    }

  • NGINX yapılandırma dosyası

    Aşağıdaki yolda bulunabilen ds.conf dosyasında $secure_link_secret parametresini ayarlayın:

    • Windows için - %ProgramFiles%\ONLYOFFICE\DocumentServer\nginx\conf\ds.conf
    • Linux için - /etc/onlyoffice/documentserver/nginx/ds.conf
    • Docker için - /etc/onlyoffice/documentserver/nginx/ds.conf (Docker kapsayıcısının içinde)
    secure_link_md5 "$secure_link_expires$uri$secure_link_secret";
    secure_link $arg_md5,$arg_expires;

Örnek​

Aşağıdaki örneği ele alalım:

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. Adım. Parametreleri ayıklayın​

URL'den aşağıdaki parametreleri ayıklayın:

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

2. Adım. MD5'i PHP ile doğrulayın​

Aşağıdaki PHP örneği, MD5 imzasının nasıl oluşturulacağını ve doğrulanacağını gösterir:

<?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. Adım. İmzaları karşılaştırın​

İşlev aşağıdaki MD5 imzasını hesaplar:

NS2_divLHhVBHdvvU9vbwA

Bu, URL'deki md5 parametresiyle eşleşir. Dolayısıyla istek geçerlidir ve onaylanabilir.

Bilinen sorunlar​

  • Her zaman tam URL'yi değil, URI'yi kullanın.
  • Gizli anahtarınızın yapılandırmadakiyle eşleştiğinden emin olun.
  • Karma için urlExpires parametresini kullanmayın. Bu parametre default.json dosyasında (local.json dosyasında değil) tanımlıdır ve bağlantı ömrü yapılandırmasını denetler, MD5 formülünde kullanılan değeri değil. Her zaman URL sorgu dizesindeki gerçek expires değerini kullanın.
  • Base64 kodlamasının URL için güvenli olduğundan emin olun.