Validación de firmas MD5 para enlaces seguros de ONLYOFFICE Docs

Descripción general

ONLYOFFICE Docs utiliza enlaces seguros con firmas MD5 para proteger el acceso a archivos en caché. Estos enlaces contienen los parámetros md5 y expires y son generados internamente por el servicio de CoAuthoring y validados a través de NGINX.

Para validar o reproducir estos hashes MD5 (por ejemplo, para implementar su propio proxy o capa de seguridad), siga las instrucciones a continuación.

Generación de la firma MD5

La firma MD5 se calcula utilizando la siguiente fórmula:

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

Dónde:

<expires> es el valor numérico del parámetro de consulta expires en la URL;
<uri> es la ruta completa de la solicitud (sin dominio ni cadena de consulta), comenzando desde /cache/files/...;
<secret> es el secreto compartido utilizado por ONLYOFFICE Docs, generalmente configurado a través de la variable de entorno SECURE_LINK_SECRET o en los archivos de configuración.

Para generar el hash, siga estos pasos:

Concatenar <expires>, <uri> y <secret> en una sola cadena.
Calcular el MD5 binario (por ejemplo, md5($string, true) en PHP).
Codificarlo usando Base64.
Convertir la cadena Base64 a un formato seguro para URL mediante:
- reemplazar + con -;
- reemplazar / con _;
- eliminar el = final.

Configuración del secreto del enlace seguro

El secreto utilizado para generar la firma del enlace seguro se puede configurar de tres maneras:

Importante Los tres métodos de configuración deben usar el mismo valor secreto. Si el secreto en local.json difiere del de ds.conf, la validación del enlace fallará. Este es un problema común después de las actualizaciones: asegúrese de que los valores estén sincronizados.

Variable de entorno (solo Docker)

Establecer una variable de entorno al ejecutar el contenedor:
```
SECURE_LINK_SECRET=your_secret_here
```
Archivo de configuración local.json

Establecer el parámetro storage.fs.secretString en el archivo local.json, que se puede encontrar en la siguiente ruta:
- Para Windows - %ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json
- Para Linux - /etc/onlyoffice/documentserver/local.json
- Para Docker - /etc/onlyoffice/documentserver/local.json (dentro del contenedor Docker)
```
{   "storage": {     "fs": {       "secretString": "your_secret_here"     }   } }
```
Archivo de configuración de NGINX

Establecer el parámetro $secure_link_secret en el archivo ds.conf, que se puede encontrar en la siguiente ruta:
- 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 del contenedor Docker)
```
secure_link_md5 "$secure_link_expires$uri$secure_link_secret"; secure_link $arg_md5,$arg_expires;
```

Ejemplo

Consideremos el siguiente ejemplo:

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

Paso 1. Extraer los parámetros

Extraer los siguientes parámetros de la URL:

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

Paso 2. Validar MD5 usando PHP

El siguiente ejemplo en PHP demuestra cómo generar y validar la firma 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 la cadena:<expires><uri><secure_link_secret> $string_to_hash = $expires . $uri . $secure_link_secret; // Calcular el hash MD5 $md5_hash = md5($string_to_hash, true); // Codificar a Base64 (seguro para URL) $base64_hash = str_replace(   ['+', '/', '='],   ['-', '_', ''],   base64_encode($md5_hash) ); // Mostrar el resultado echo "Cadena a hashear: " . $string_to_hash . "\n"; echo "Hash MD5 generado: " . $base64_hash . "\n"; echo "Hash MD5 esperado: NS2_divLHhVBHdvvU9vbwA\n"; ?>

Paso 3. Comparar las firmas

La función calcula la siguiente firma MD5:

NS2_divLHhVBHdvvU9vbwA

Esto coincide con el parámetro md5 en la URL. Por lo tanto, la solicitud es válida y puede ser confirmada.

Problemas conocidos

Siempre use el URI, no la URL completa.
Asegúrese de que su secreto coincida con la configuración.
No use el parámetro urlExpires para el hashing. Este parámetro se define en default.json (no en local.json) y controla la configuración de la duración del enlace, no el valor utilizado en la fórmula MD5. Siempre use el valor real de expires de la cadena de consulta de la URL.
Asegúrese de que la codificación Base64 sea segura para URL.