Erreur BLOCKEDLOG_HMAC_KEY (Dolibarr 24) : guide et solution

Après la mise à jour vers Dolibarr 24.0.0, la zone d'administration affiche ce message :

Configuration du module Journaux immuables

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 réaction typique est alarmante : « Ai-je cassé le registre immuable ? Vais-je devoir re-signer les milliers d'enregistrements historiques ? » La réponse est non : Dolibarr ne peut pas lire la clé de signature stockée dans la base de données, mais l'historique reste intact. C'est le cas que nous avons résolu en production.

Ce que cette erreur est et ce qu'elle signifie

L'erreur indique que l'ERP n'arrive pas à déchiffrer la clé avec laquelle le module Journaux immuables signe les nouveaux événements. Ce n'est pas une corruption de données : c'est une clé illisible.

Trois définitions rapides :

• Journaux immuables (blockedlog) : le module de Dolibarr qui enregistre une ligne par événement pertinent (factures, paiements, connexions…) dans llx_blockedlog.
• Signature en chaîne : chaque ligne porte une signature qui dépend de la ligne précédente ; si quelqu'un touche une ligne, les suivantes ne concordent plus et le système le détecte.
• Clé HMAC : une clé secrète que le module génère à son activation et qu'il stocke chiffrée dans llx_const sous le nom BLOCKEDLOG_HMAC_KEY.

La valeur n'est pas en clair : dolcrypt:AES-256-CTR:<IV>:<données base64>. Pour la déchiffrer, Dolibarr utilise la clé maîtresse de l'installation ($dolibarr_main_instance_unique_id du conf.php). Si cette clé n'est pas celle qui a chiffré la constante, la valeur ne peut plus être lue : exactement ce que dit le message.

V1 vs V2, la différence qui explique tout

	Format V1 (historique)	Format V2 (nouveaux)
Signature	SHA-256 enchaînée (dol_hash(..., '5'))	hash_hmac('sha256', ..., cléHMAC)
Utilise la clé HMAC ?	Non	Oui
Version	jusqu'à Dolibarr 20 environ	à partir de la v21, toujours créée en v24

Cette différence explique tout : l'historique est généralement en V1 et ses signatures ne dépendent pas de la clé HMAC, donc une clé remplacée ne les affecte pas. La clé est la nouvelle serrure : les données et les signatures V1 restent valides ; il ne manque qu'une clé pour les nouvelles signatures (V2).

Causes typiques

Cause	Comment la reconnaître ?	Solution
Mise à jour depuis une version avec un ancien schéma de chiffrement	L'erreur apparaît juste après la mise à jour ; ancien tms	Régénérer la clé
BDD restaurée depuis une autre installation (nouvel hébergement, migration)	Constante antérieure à l'hébergement actuel	Régénérer ou récupérer le conf d'origine
conf.php régénéré sans restaurer l'ID	Les deux conf.php diffèrent sur instance_unique_id	Restaurer l'ID d'origine
Multi-entreprises : deux lignes (entity 0 et 1)	La requête sur llx_const renvoie 2 lignes	Supprimer la corrompue

Dans notre cas, le instance_unique_id était identique avant et après la mise à jour et pourtant le déchiffrement renvoyait des octets invalides : la constante avait été enregistrée dans une autre vie de l'installation (un autre hébergement, ou une version avec un schéma de chiffrement différent).

Diagnostic en 2 étapes

Étape 1 : regardez la constante (1 minute). Exécutez :

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

• Une ligne : clé unique de l'installation (le cas normal).
• Deux lignes (entity 0 et ≥ 1) : le module lit ORDER BY entity DESC LIMIT 1 ; vérifiez celle avec l'entity la plus élevée.
• Préfixe de la value : dolcrypt:AES-256-CTR: → ancienne méthode ; <32 hex> → nouvelle méthode.

Étape 2 : vérifiez la chaîne historique (2 minutes). Parcourez les lignes de llx_blockedlog par rowid et vérifiez que chaque signature correspond à celle calculée par la fonction officielle buildKeyForSignature(). Dans notre cas : 2 580 enregistrements vérifiés, 2 580 OK.

La solution : régénérer la clé (l'historique est conservé)

Étape 1 — Sauvegarde (toujours).

CREATE TABLE llx_blockedlog_backup AS SELECT * FROM llx_blockedlog;

Étape 2 — Supprimer la constante.

DELETE FROM llx_const WHERE name = 'BLOCKEDLOG_HMAC_KEY';

S'il y a deux lignes par entité, supprimez uniquement la corrompue :

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

Étape 3 — Réactivez le module. Dans Administration → Modules → BlockedLog (Journaux immuables), décochez le module puis recochez-le. L'init() du module, ne trouvant pas la constante, génère une nouvelle clé chiffrée avec votre instance_unique_id.

Étape 4 — Vérifiez. Accédez à la configuration sans erreur, la liste affiche les lignes sous « Valider », et effectuez une action réelle : la nouvelle ligne est signée en V2 et s'enchaîne avec la dernière signature V1 sans aucune alerte.

Note : Dolibarr met la constante en cache par session. Demandez aux utilisateurs connectés de se reconnecter.

Ce qu'il ne faut pas faire (liste noire)

• Ne supprimez ni ne tronquez llx_blockedlog : vous détruisez la piste d'audit sans rien y gagner ; l'ancienne chaîne était valide.
• Ne changez pas instance_unique_id n'importe comment : cela casse les cookies, les clés API et tout le reste du chiffrement actuel.
• Ne re-signez pas avec un script « maison » : la vérification exige l'algorithme exact de chaque version ; une fausse chaîne est pire que le doute.
• Ne copiez pas la BDD vers un autre hébergement sans le conf.php : la constante voyage, mais la clé ne voyage pas.

Questions fréquentes

Ai-je perdu l'historique du registre immuable ? Non. Les signatures V1 ne dépendent pas de la clé HMAC ; l'historique reste intact et vérifiable.

Cela affecte-t-il les clés API, les jetons ou les cookies ? Si la cause est une restauration ou une migration, oui : les données chiffrées avec l'ancienne clé suivent le même schéma ; vérifiez que les clés API fonctionnent et que les utilisateurs peuvent se connecter. Si la cause est uniquement le schéma, non.

Comment éviter que cela ne se reproduise à la prochaine mise à jour ? Sauvegarde complète (BDD + conf.php, en notant l'instance_unique_id), mise à jour d'abord dans un environnement de test, puis une visite au module après la mise à jour, en vérifiant chaque entity en multi-entreprises.

Est-ce une faille de sécurité ? Ce n'est pas exploitable par des tiers : la clé ne peut pas être déchiffrée, donc son effet est de stopper l'enregistrement de nouveaux événements. Il vaut la peine de vérifier s'il y a eu des changements d'environnement non enregistrés et de contrôler les sauvegardes.

Où puis-je suivre cet incident ? Il existe une issue ouverte dans le tracker de Dolibarr avec l'analyse complète et un PR déjà intégré qui corrige la clé par entité, dans le miroir GitHub du dépôt officiel.

Résumé exécutif

• L'erreur « Failed to decode the crypted value of the parameter BLOCKEDLOG_HMAC_KEY » après une mise à jour vers Dolibarr 24 est un problème de clé de signature illisible, et non de données.
• L'historique est valide : 2 580/2 580 vérifiés dans le cas pris en charge.
• Solution à faible risque : sauvegarde → suppression de la constante dans llx_const → réactivation du module.
• La nouvelle clé ne signe que les nouveaux événements ; le registre précédent n'est pas touché.
• Prévention : sauvegarde toujours avec le conf.php inclus et un environnement de test pour les mises à jour.

Vous préférez ne pas avoir à vous en occuper ? Nous proposons un support expert Dolibarr et ERP dans le cloud pour PME avec un accompagnement à chaque mise à jour. Envisagez-vous de transférer votre gestion sur Dolibarr ? Ce questionnaire gratuit vous dit si la solution correspond à votre entreprise.