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 por /cache/files/...;
<secret> é o segredo compartilhado usado pelo ONLYOFFICE Docs, normalmente configurado via a variável de ambiente SECURE_LINK_SECRET ou nos arquivos de configuração.

Para gerar o hash, siga estas etapas:

Concatene <expires>, <uri> e <secret> em uma única string.
Calcule o MD5 binário (por exemplo, md5($string, true) em PHP).
Codifique usando Base64.
Converta a string Base64 para um formato seguro para URL substituindo:
- + por -;
- / por _;
- removendo o = final.

Configurando o segredo do link seguro

O segredo usado para gerar a assinatura do link seguro pode ser configurado 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á. Este é um problema comum após atualizações — certifique-se de que os valores estejam sincronizados.

Variável de ambiente (apenas 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

Considere 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. Valide MD5 usando PHP

O exemplo em 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"; // Forme a string:<expires><uri><secure_link_secret> $string_to_hash = $expires . $uri . $secure_link_secret; // Calcule o hash MD5 $md5_hash = md5($string_to_hash, true); // Codifique para Base64 (seguro para URL) $base64_hash = str_replace(   ['+', '/', '='],   ['-', '_', ''],   base64_encode($md5_hash) ); // Exiba o resultado echo "String para hash: " . $string_to_hash . "\n"; echo "Hash MD5 gerado: " . $base64_hash . "\n"; echo "Hash MD5 esperado: 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.