Cryptographie financière — libsodium, Ed25519, chaînage

Kohinos signe et chaîne ses opérations monétaires (Flux, Operation) de manière vérifiable, locale et auditable. Le projet adopte libsodium comme bibliothèque cryptographique unique : primitives modernes (Ed25519, Curve25519, BLAKE2b), audit-friendly, performante sur Raspberry Pi, et compatible avec la roadmap offline-first (Reticulum / LoRa-mesh). Aucun mécanisme financier critique ne doit dépendre d'openssl_* ou d'une API maison.

Pourquoi libsodium

Diagramme — signature et vérification d'une opération

sequenceDiagram
    autonumber
    participant App as Application
    participant KeyStore as KeyStore
(env / Symfony secrets)
    participant Sodium as ext-sodium
    participant DB as MariaDB
    participant Audit as bin/console
kohinos:chain:verify

    Note over App,Sodium: 1. Émission d'une Operation
    App->>KeyStore: getPrivateKey(emitterId)
    KeyStore-->>App: ed25519_secret_key (32B)
    App->>DB: SELECT hash FROM operation WHERE id=preceding ORDER BY created_at DESC LIMIT 1
    DB-->>App: previousHash
    App->>Sodium: sodium_crypto_generichash(previousHash || payload)
    Sodium-->>App: hash (32B BLAKE2b)
    App->>Sodium: sodium_crypto_sign_detached(hash, secret_key)
    Sodium-->>App: signature (64B Ed25519)
    App->>DB: INSERT operation(hash, signature, public_key, ...)

    Note over Audit,DB: 2. Vérification a posteriori
    Audit->>DB: SELECT * FROM operation ORDER BY created_at
    loop pour chaque op
        Audit->>Sodium: recompute hash(prev || payload)
        Audit->>Sodium: sodium_crypto_sign_verify_detached(sig, hash, pubkey)
    end
    Audit-->>App: rapport: chaîne intacte / rompue à op #N
    

Primitives libsodium utilisées

Chaînage cryptographique des opérations

Chaque Operation (et symétriquement chaque Flux) porte deux champs critiques : hash et signature. Le hash chaîne l'opération à la précédente du même compte, ce qui forme un registre vérifiable de bout en bout (modèle inspiré d'un append-only ledger).

Définition du hash (proposition cible)

// Pseudo-spec — à confirmer / implémenter dans src/Service/Crypto/OperationHasher.php
hash(op) = BLAKE2b_256(
    previousHash(op.account)     // 32 B, ou 32 octets de zéros si genèse du compte
 || canonicalPayload(op)         // JSON canonique trié, UTF-8 NFC
 || op.accountId                 // UUID, 16 B
 || op.amount.toString()         // "1234.56" — toujours BigDecimal-string, jamais float
 || op.createdAt.toIso8601()
)

L'opérateur || est la concaténation binaire. Le payload canonique doit être strictement déterministe : clés JSON triées, pas d'espaces, encodage UTF-8 NFC, pour qu'un re-hash 5 ans plus tard donne le même résultat à l'octet près.

Définition de la signature

signature(op) = sodium_crypto_sign_detached(
    hash(op),                         // message = le hash chaîné
    op.emitter.ed25519_secret_key     // clé privée du compte émetteur (32 B seed + 32 B pubkey = 64 B)
)
// Vérification :
sodium_crypto_sign_verify_detached(
    op.signature,                     // 64 B
    op.hash,                          // 32 B
    op.emitter.ed25519_public_key     // 32 B, stocké dans la table account
)

Schéma BDD cible (à confirmer / migration à prévoir)

ALTER TABLE operation
  ADD COLUMN hash         BINARY(32)  NOT NULL,
  ADD COLUMN signature    BINARY(64)  NOT NULL,
  ADD COLUMN public_key   BINARY(32)  NOT NULL,
  ADD COLUMN previous_id  CHAR(36)    NULL,
  ADD CONSTRAINT fk_operation_previous FOREIGN KEY (previous_id) REFERENCES operation(id);

CREATE INDEX idx_operation_account_created ON operation(account_id, created_at);

Le champ actuel operation.hash est typé TEXT et contient un password_hash() bcrypt. C'est une dette technique : bcrypt n'est pas déterministe (sel aléatoire à chaque appel), donc impossible à re-vérifier sans stocker la chaîne d'entrée. La migration consistera à régénérer les hashes BLAKE2b sur l'historique en parallèle, à valider, puis à basculer.

Exemple d'implémentation (proposition)

<?php
declare(strict_types=1);

namespace App\Service\Crypto;

final class OperationHasher
{
    public function hash(Operation $op, ?string $previousHash): string
    {
        $payload = $this->canonicalize([
            'account'   => $op->getAccount()->getId()->toBinary(),
            'amount'    => $op->getMontant()->toString(),  // BigDecimal-string
            'type'      => $op->getType(),
            'reference' => $op->getReference(),
            'createdAt' => $op->getCreatedAt()->format(\DateTimeInterface::ATOM),
        ]);

        $material = ($previousHash ?? str_repeat("\0", 32)) . $payload;

        return sodium_crypto_generichash($material, '', SODIUM_CRYPTO_GENERICHASH_BYTES);
    }

    private function canonicalize(array $data): string
    {
        ksort($data);
        return json_encode($data, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_THROW_ON_ERROR);
    }
}

final class OperationSigner
{
    public function __construct(private readonly KeyStore $keys) {}

    public function sign(Operation $op, string $hash): string
    {
        $secret = $this->keys->getSecretKey($op->getEmitter());
        try {
            return sodium_crypto_sign_detached($hash, $secret);
        } finally {
            sodium_memzero($secret); // efface la clé de la mémoire
        }
    }

    public function verify(string $signature, string $hash, string $publicKey): bool
    {
        return sodium_crypto_sign_verify_detached($signature, $hash, $publicKey);
    }
}

Règles dures cryptographie

Politique de rotation des clés

Chiffrement IBAN au repos

Les IBAN des adhérents sont chiffrés au niveau colonne. L'implémentation actuelle (App\Service\IbanEncryptionService) utilise AES-256-CBC via OpenSSL avec un suffixe <ENC> et la clé ENCRYPT_KEY (base64, 32 octets) issue de l'environnement. Cible libsodium (à confirmer / refactor) :

<?php
declare(strict_types=1);

namespace App\Service;

final class IbanEncryptionService
{
    private const SUFFIX = '<SODIUM>';

    public function __construct(
        #[\SensitiveParameter] private readonly string $key   // 32 octets bruts
    ) {
        if (strlen($this->key) !== SODIUM_CRYPTO_SECRETBOX_KEYBYTES) {
            throw new \InvalidArgumentException('ENCRYPT_KEY must be 32 bytes.');
        }
    }

    public function encrypt(string $plain): string
    {
        if ($this->isEncrypted($plain)) {
            return $plain;
        }
        $nonce  = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
        $cipher = sodium_crypto_secretbox($plain, $nonce, $this->key);

        return base64_encode($nonce . $cipher) . self::SUFFIX;
    }

    public function decrypt(string $value): ?string
    {
        if (!$this->isEncrypted($value)) {
            return $value;
        }
        $raw    = base64_decode(str_replace(self::SUFFIX, '', $value), true);
        if ($raw === false || strlen($raw) < SODIUM_CRYPTO_SECRETBOX_NONCEBYTES) {
            return null;
        }
        $nonce  = substr($raw, 0, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
        $cipher = substr($raw, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);

        $plain  = sodium_crypto_secretbox_open($cipher, $nonce, $this->key);
        return $plain === false ? null : $plain;
    }

    public function isEncrypted(string $value): bool
    {
        return str_ends_with($value, self::SUFFIX);
    }
}

La migration est portée par la commande bin/console app:migrate-iban-encryption [--dry-run]. Elle doit, dans sa version libsodium : détecter les valeurs avec ancien suffixe <ENC>, déchiffrer en AES-CBC, rechiffrer en secretbox, et écrire avec le nouveau suffixe <SODIUM>. Idempotent et rejouable.

Audit & vérification de la chaîne

Une commande dédiée doit permettre de rejouer la chaîne complète et de signaler toute rupture (proposition d'API) :

# Vérifie la chaîne de toutes les opérations
php bin/console kohinos:chain:verify

# Sur un compte précis
php bin/console kohinos:chain:verify --account=<uuid>

# Vérifie aussi la signature Ed25519 (plus lent)
php bin/console kohinos:chain:verify --with-signatures

# Sortie JSON pour CI / monitoring
php bin/console kohinos:chain:verify --format=json > var/log/chain-audit.json

Pseudo-code de vérification :

foreach ($account->getOperationsOrderedByDate() as $op) {
    $expected = $hasher->hash($op, $previous?->getHash());
    if (!sodium_memcmp($expected, $op->getHash())) {
        $report->rupture($op, 'hash mismatch');
    }
    if ($withSignatures && !$signer->verify($op->getSignature(), $op->getHash(), $op->getPublicKey())) {
        $report->rupture($op, 'signature invalid');
    }
    $previous = $op;
}

Ce contrôle est complémentaire des invariants financiers : voir Invariants financiers pour la part "double-entry / somme nulle".

Roadmap offline / Reticulum

Kohinos est conçu pour pouvoir un jour fonctionner hors-Internet via un mesh radio bas-débit (LoRa) sur la pile Reticulum. Ce choix impose dès aujourd'hui :

• Curve25519 pour l'échange de clés et l'identification des nœuds — réutilisable directement par Reticulum.
• Ed25519 pour les signatures — compact (64 B), pas de RNG à la signature, déterministe, donc validable sur lien intermittent.
• BLAKE2b pour les hashes de chaînage — rapide même sur ARM Cortex-M, sortie 32 B compatible avec les MTU radio.
• Pas de dépendance HTTP/TLS dans le chemin critique de signature : tout est calculable et vérifiable localement.
• Format payload canonique dès maintenant : une opération signée doit pouvoir transiter par paquet LoRa et être re-vérifiée mois plus tard sur un autre nœud, à l'octet près.

Conséquence opérationnelle : aucune nouvelle dépendance crypto ne doit être introduite si elle n'est pas couverte par libsodium. C'est le seul moyen de garder l'option Reticulum ouverte sans réécriture massive.

Pour aller plus loin