Error BLOCKEDLOG_HMAC_KEY en Dolibarr 24: guía y solución

Tras actualizar a Dolibarr 24.0.0, la zona de administración muestra este mensaje:

Configuración del módulo Registros inmutables

getClearHMACSecretKey Error: Failed to decode the crypted value of the parameter
BLOCKEDLOG_HMAC_KEY dolcrypt:AES-256-CTR:4de1c82c60feb73e:+evrXBA7Vk1H0qbHmiYaG2W1l6X+AZyTVSG0A88qPQJcvF3uZ8zdKM5tICSsbQ==
using the obfuscation key. A value was found in database but decoding failed.
May be you modified the SIREN used to get the obfuscation key from ping.dolibarr.org
(or old config key $dolibarr_main_instance_unique_id).

La reacción típica es alarmante: «¿he roto el registro inalterable? ¿Tendré que re-firmar los miles de registros históricos?». La respuesta es no: Dolibarr no puede leer la clave de firma guardada en la base de datos, pero el histórico sigue intacto. Es el caso que resolvimos en producción.

Qué es este error y qué significa

El error avisa de que el ERP no consigue descifrar la clave con la que el módulo de Registros inmutables firma los eventos nuevos. No es una corrupción de datos: es una clave ilegible.

Tres definiciones rápidas:

• Registros inmutables (blockedlog): el módulo de Dolibarr que guarda una línea por cada evento relevante (facturas, pagos, logins…) en llx_blockedlog.
• Firma en cadena: cada fila lleva una firma que depende de la fila anterior; si alguien toca una fila, las siguientes dejan de cuadrar y el sistema lo detecta.
• Clave HMAC: una clave secreta que el módulo genera al activarse y guarda cifrada en llx_const como BLOCKEDLOG_HMAC_KEY.

El valor no está en claro: dolcrypt:AES-256-CTR:<IV>:<datos base64>. Para descifrarlo, Dolibarr usa la clave maestra de la instalación ($dolibarr_main_instance_unique_id del conf.php). Si esa clave no es la misma con la que se cifró la constante, el valor ya no se lee: exactamente lo que dice el mensaje.

V1 vs V2, la diferencia que lo explica todo

	Formato V1 (histórico)	Formato V2 (nuevos)
Firma	SHA-256 encadenada (dol_hash(..., '5'))	hash_hmac('sha256', ..., claveHMAC)
¿Usa la clave HMAC?	No	Sí
Versión	hasta Dolibarr 20 aprox.	a partir de v21, creada siempre en v24

Esta diferencia lo explica todo: el histórico suele ser V1 y sus firmas no dependen de la clave HMAC, así que la clave rota no los afecta. La clave es la cerradura nueva: los datos y las firmas V1 siguen siendo legales; solo falta una llave para las firmas nuevas (V2).

Causas típicas

Causa	¿Cómo reconocerla?	Solución
Upgrade desde una versión con esquema de cifrado viejo	El error aparece justo después de actualizar; tms antiguo	Regenerar la clave
BD restaurada de otra instalación (hosting nuevo, migración)	Constante con fecha anterior al hosting actual	Regenerar o recuperar el conf original
conf.php regenerado sin restaurar el ID	Los dos conf.php difieren en instance_unique_id	Restaurar el ID original
Multi-empresa: dos filas (entity 0 y 1)	La consulta de llx_const devuelve 2 filas	Eliminar la corrupta

En nuestro caso el instance_unique_id era el mismo antes y después del upgrade y aun así el descifrado devolvía bytes inválidos: la constante se guardó en otra vida de la instalación (otro hosting o una versión con cifrado distinto).

Diagnóstico en 2 pasos

Paso 1: mira la constante (1 minuto). Ejecuta:

SELECT entity, value, tms FROM llx_const WHERE name = 'BLOCKEDLOG_HMAC_KEY';

• Una fila: clave única de la instalación (lo normal).
• Dos filas (entity 0 y ≥ 1): el módulo lee ORDER BY entity DESC LIMIT 1; revisa la de mayor entity.
• Prefijo del value: dolcrypt:AES-256-CTR: → método antiguo; con <32 hex> → método nuevo.

Paso 2: verifica la cadena histórica (2 minutos). Recorre las filas de llx_blockedlog por rowid y comprueba que cada firma coincide con la que calcula la función oficial buildKeyForSignature(). En nuestro caso: 2.580 registros verificados, 2.580 OK.

La solución: regenerar la clave (el histórico se conserva)

Paso 1 — Backup (siempre).

CREATE TABLE llx_blockedlog_backup AS SELECT * FROM llx_blockedlog;

Paso 2 — Borra la constante.

DELETE FROM llx_const WHERE name = 'BLOCKEDLOG_HMAC_KEY';

Si hay dos filas por entidad, elimina solo la corrupta:

DELETE FROM llx_const WHERE name='BLOCKEDLOG_HMAC_KEY' AND entity = 1;

Paso 3 — Reactiva el módulo. En Administración → Módulos → BlockedLog (Registros inmutables), desmarca el módulo y márcalo de nuevo. El init() del módulo, al no encontrar la constante, genera una clave nueva cifrada con tu instance_unique_id.

Paso 4 — Verifica. Entra en la configuración sin error, el listado muestra las filas en «Validar», y haz una acción real: la nueva línea se firma en V2 y encadena con la última firma V1 sin alertas.

Nota: Dolibarr cachea la constante por sesión. Pide re-login a los usuarios conectados.

Qué no hacer (lista negra)

• No borres ni trunques llx_blockedlog: destruyes auditoría sin ganar nada; la cadena antigua era válida.
• No cambies instance_unique_id a lo loco: rompe cookies, API keys y demás cifrados actuales.
• No re-firmes con un script «casero»: la verificación exige el algoritmo exacto de cada versión; una cadena falsa es peor que la duda.
• No copies la BD a otro hosting sin el conf.php: la constante viaja, pero la clave no.

Preguntas frecuentes

¿He perdido el histórico del registro inalterable? No. Las firmas V1 no dependen de la clave HMAC; el histórico queda intacto y verificable.

¿Afecta a las API keys, tokens o cookies? Si la causa es una restauración o migración, sí: los datos cifrados con la clave antigua tienen el mismo patrón; revisa que las API keys funcionen y que los usuarios puedan entrar. Si la causa es solo del esquema, no.

¿Cómo evito que vuelva a pasar en el próximo upgrade? Backup completo (BD + conf.php, anotando el instance_unique_id), upgrade primero en un entorno de test y una visita al módulo tras el upgrade, revisando cada entity en multi-empresa.

¿Es un fallo de seguridad? No es aprovechable por terceros: la clave no se puede descifrar, así que lo que hace es detener el registro de eventos nuevos. Conviene revisar si hubo cambios de entorno sin registrar y los backups.

¿Dónde puedo seguir esta incidencia? Hay una issue abierta en el tracker de Dolibarr con el análisis completo y un PR ya integrado que corrige la clave por entidad, en el espejo de GitHub del repositorio oficial.

Resumen ejecutivo

• El error «Failed to decode the crypted value of the parameter BLOCKEDLOG_HMAC_KEY» tras un upgrade a Dolibarr 24 es un problema de clave de firma ilegible, no de datos.
• El histórico es válido: verificado 2.580/2.580 en el caso atendido.
• Solución de bajo riesgo: backup → borrar la constante de llx_const → reactivar el módulo.
• La clave nueva solo firma eventos nuevos; el registro anterior no se toca.
• Prevención: backup siempre con el conf.php incluido y entorno de pruebas para los upgrades.

¿Prefieres no lidiar con esto? Ofrecemos soporte experto de Dolibarr y ERP en la nube para pymes con acompañamiento en cada actualización. ¿Valoras mover tu gestión a Dolibarr? Este cuestionario gratuito te dice si encaja con tu empresa.