Pular para o conteúdo principal

Validando assinaturas MD5 para links seguros do ONLYOFFICE Docs

Visão geral​

O ONLYOFFICE Docs utiliza links seguros com assinaturas MD5 para proteger o acesso a arquivos em cache. Esses links contêm os parâmetros md5 e expires e são gerados internamente pelo serviço CoAuthoring e validados via NGINX.

Para validar ou reproduzir esses hashes MD5 (por exemplo, para implementar seu próprio proxy ou camada de segurança), siga as instruções abaixo.

Gerando assinatura MD5​

A assinatura MD5 é calculada usando a seguinte fórmula:

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

Onde:

  • <expires> é o valor numérico do parâmetro de consulta expires na URL;
  • <uri> é o caminho completo da solicitação (sem domínio ou string de consulta), começando com /cache/files/...;
  • <secret> é o segredo compartilhado usado pelo ONLYOFFICE Docs, normalmente definido via a variável de ambiente SECURE_LINK_SECRET ou nos arquivos de configuração.

Para gerar o hash, siga estas etapas:

  1. Concatene <expires>, <uri> e <secret> em uma única string.

  2. Calcule o MD5 binário (por exemplo, md5($string, true) em PHP).

  3. Codifique usando Base64.

  4. Converta a string Base64 para um formato seguro para URL:

    • substituindo + por -;
    • substituindo / por _;
    • removendo o = final.

Configurando o segredo do link seguro​

O segredo usado para gerar a assinatura do link seguro pode ser definido de três maneiras:

Importante

Todos os três métodos de configuração devem usar o mesmo valor de segredo. Se o segredo em local.json for diferente do que está em ds.conf, a validação do link falhará. Isso é um problema comum após atualizações — certifique-se de que os valores estejam sincronizados.

  • Variável de ambiente (somente Docker)

    Defina uma variável de ambiente ao executar o contêiner:

    SECURE_LINK_SECRET=your_secret_here

  • Arquivo de configuração local.json

    Defina o parâmetro storage.fs.secretString no arquivo local.json, que pode ser encontrado no seguinte caminho:

    • Para Windows - %ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json
    • Para Linux - /etc/onlyoffice/documentserver/local.json
    • Para Docker - /etc/onlyoffice/documentserver/local.json (dentro do contêiner Docker)
    {
      "storage": {
        "fs": {
          "secretString": "your_secret_here"
        }
      }
    }

  • Arquivo de configuração NGINX

    Defina o parâmetro $secure_link_secret no arquivo ds.conf, que pode ser encontrado no seguinte caminho:

    • Para Windows - %ProgramFiles%\ONLYOFFICE\DocumentServer\nginx\conf\ds.conf
    • Para Linux - /etc/onlyoffice/documentserver/nginx/ds.conf
    • Para Docker - /etc/onlyoffice/documentserver/nginx/ds.conf (dentro do contêiner Docker)
    secure_link_md5 "$secure_link_expires$uri$secure_link_secret";
    secure_link $arg_md5,$arg_expires;

Exemplo​

Vamos considerar o seguinte exemplo:

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

Passo 1. Extraia os parâmetros​

Extraia os seguintes parâmetros da URL:

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

Passo 2. Validar MD5 usando PHP​

O exemplo PHP a seguir demonstra como gerar e validar a assinatura 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";
// Formar a string:<expires><uri><secure_link_secret>
$string_to_hash = $expires . $uri . $secure_link_secret;
// Calcular hash MD5
$md5_hash = md5($string_to_hash, true);
// Codificar em Base64 (seguro para URL)
$base64_hash = str_replace(
  ['+', '/', '='],
  ['-', '_', ''],
  base64_encode($md5_hash)
);
// Exibir o resultado
echo "String to hash: " . $string_to_hash . "\n";
echo "Generated MD5 hash: " . $base64_hash . "\n";
echo "Expected MD5 hash: NS2_divLHhVBHdvvU9vbwA\n";
?>

Passo 3. Compare as assinaturas​

A função calcula a seguinte assinatura MD5:

NS2_divLHhVBHdvvU9vbwA

Isso corresponde ao parâmetro md5 na URL. Portanto, a solicitação é válida e pode ser confirmada.

Problemas conhecidos​

  • Sempre use o URI, não a URL completa.
  • Certifique-se de que seu segredo corresponda à configuração.
  • Não use o parâmetro urlExpires para hashing. Este parâmetro é definido em default.json (não em local.json) e controla a configuração de tempo de vida do link, não o valor usado na fórmula MD5. Sempre use o valor real expires da string de consulta da URL.
  • Garanta que a codificação Base64 seja segura para URL.