🔐 Signatures cryptographiques de blocs

Signez vos blocs pour garantir leur authenticité et non-répudiation

📦 Package NPM @sowasit/signer 📚 API Reference

Introduction

SoWasIt vous permet de signer cryptographiquement vos blocs pour garantir leur authenticité et leur non-répudiation. En utilisant une infrastructure à clés publiques (PKI) avec des algorithmes ECDSA P-256, vous pouvez prouver que c'est bien votre organisation qui a créé un bloc spécifique.

💡 Cas d'usage :

Conformité réglementaire (signature électronique qualifiée)
Preuve légale de création de données
Audit et traçabilité renforcée
Non-répudiation des transactions

Pourquoi faire signer un partenaire ?

Scénario concret : litige de livraison

TechCorp s'approvisionne auprès de SupplyPro et gère ses livraisons dans une chaîne SoWasIt. Voici ce qui se passe selon que SupplyPro signe ou non les blocs.

❌ Sans signature partenaire — le problème

Le 15 janvier, SupplyPro effectue une livraison. TechCorp enregistre elle-même un bloc : "Livraison reçue : 500 unités, réf. ABC-789". SupplyPro signe le bon de livraison papier comme d'habitude et repart.

Trois mois plus tard, SupplyPro envoie une facture pour 800 unités et prétend avoir livré ce chiffre. TechCorp montre ses blocs qui disent "500 unités"... mais SupplyPro rétorque que c'est TechCorp qui a créé ces blocs. Rien n'empêchait TechCorp de saisir 500 au lieu de 800 pour réduire sa facture. C'est parole contre parole.

Le problème : si c'est vous qui enregistrez les données à la place du partenaire, rien ne prouve que le partenaire était d'accord avec ce que vous avez écrit.

✅ Avec signature partenaire — la solution

SupplyPro génère sa paire de clés ECDSA via @sowasit/signer et l'enregistre auprès de TechCorp. Désormais, à chaque livraison, c'est le système de SupplyPro qui crée et signe lui-même le bloc : "Livraison confirmée : 500 unités, réf. ABC-789".

Trois mois plus tard, SupplyPro envoie quand même une facture pour 800 unités. TechCorp sort le bloc signé par SupplyPro lui-même attestant de 500 unités livrées. La signature cryptographique de SupplyPro est là, vérifiable et irrévocable. SupplyPro ne peut pas prétendre avoir livré 800 — c'est sa propre signature qui dit 500.

En cas de litige, TechCorp présente les blocs signés par SupplyPro. La preuve est cryptographiquement irréfutable et légalement opposable : SupplyPro a lui-même certifié le chiffre.

D'autres cas d'usage

Le même principe s'applique dans de nombreux secteurs :

Un transporteur signe les bons de livraison dans votre chaîne logistique
Un organisme de certification signe vos blocs d'audit qualité
Un prestataire signe ses rapports d'intervention dans votre GMAO
Un client signe sa validation de commande ou de réception
Un partenaire financier signe les confirmations de virement

En résumé : la vraie valeur des signatures vient du fait qu'un tiers de confiance — et non vous — appose sa signature sur les données. Cela transforme votre chaîne en preuve bilatérale, opposable aux deux parties.

Cycle de vie d'une clé

1️⃣ Génération de token d'enrôlement → Le propriétaire de la chaîne génère un token pour un partenaire

2️⃣ Génération de paire de clés → Le partenaire utilise le CLI pour créer ses clés ECDSA

3️⃣ Enregistrement de la clé publique → Le partenaire envoie sa clé publique à SoWasIt

4️⃣ Certification → Le partenaire imprime, signe et uploade le document de certification

5️⃣ Vérification → Le propriétaire de la chaîne vérifie le document du partenaire

6️⃣ Activation → Le propriétaire active la clé, le partenaire peut signer des blocs

7️⃣ Révocation (si nécessaire) → Le propriétaire révoque une clé compromise ou obsolète

Installation du CLI

Le package @sowasit/signer est disponible sur NPM et peut être utilisé comme outil CLI ou bibliothèque JavaScript/TypeScript.

Installation globale (CLI)

npm install -g @sowasit/signer

Installation locale (bibliothèque)

npm install @sowasit/signer

Démarrage rapide

1. Générer et enregistrer une paire de clés (Partenaire)

Récupérez d'abord un token d'enrôlement du propriétaire de la chaîne, puis :

signer add-key \
  --token YOUR_ENROLLMENT_TOKEN \
  --api-key YOUR_API_KEY \
  --passphrase your-secret-passphrase \
  --output ./keys \
  --client-name "Your Company Name" \
  --client-contact "admin@company.com"

Cette commande va :

Générer une paire de clés ECDSA P-256
Enregistrer la clé publique sur SoWasIt
Sauvegarder les clés localement dans ./keys/
Générer un document de certification à imprimer, signer et uploader

2. Compléter la certification (Partenaire)

⚠️ Étape obligatoire : Pour permettre au propriétaire de la chaîne d'activer votre clé, vous devez :

Imprimer le document de certification généré (sowasit.certification.txt)
Le signer et le tamponner (signature légale de votre entreprise)
Le scanner en PDF
L'uploader via l'API ou le dashboard

3. Créer un bloc signé (Partenaire)

Une fois que le propriétaire de la chaîne a activé votre clé (status = active), vous pouvez signer des blocs :

signer create-block \
  --chain ch_abc123 \
  --key ./keys/sowasit.private.pem \
  --key-id f1a2b3c4d5e6f7g8 \
  --api-key sk_your_api_key \
  --content-file ./data.json \
  --passphrase your-secret-passphrase

Référence CLI

`signer add-key`

Génère une nouvelle paire de clés et l'enregistre sur SoWasIt.

Option	Description	Required
`-t, --token`	Token d'enrôlement depuis SoWasIt	✓
`-k, --api-key`	Votre clé API SoWasIt	✓
`-o, --output`	Répertoire de sortie (défaut: ./keys)
`-p, --passphrase`	Phrase secrète pour chiffrer la clé privée	Recommandé
`--client-name`	Nom de votre entreprise
`--client-contact`	Email de contact

`signer sign`

Signe du contenu avec votre clé privée (sans créer de bloc).

signer sign \
  --key ./keys/sowasit.private.pem \
  --data ./content.json \
  --passphrase secret \
  --output ./signature.json

`signer create-block`

Crée un bloc signé directement sur SoWasIt.

signer create-block \
  --chain ch_abc123 \
  --key ./keys/sowasit.private.pem \
  --key-id f1a2b3c4 \
  --api-key sk_xxx \
  --content '{"order": "ORD-001", "status": "shipped"}' \
  --passphrase secret

Usage programmatique (JavaScript/TypeScript)

Générer une paire de clés

import { KeyManager } from '@sowasit/signer';

// Generate key pair
const keyPair = await KeyManager.generateKeyPair({
  passphrase: 'your-secret-passphrase'
});

// Save to disk
await KeyManager.saveKeyPair(keyPair, './keys', 'my-company');

console.log('Key ID:', keyPair.keyId);
console.log('Fingerprint:', keyPair.fingerprint);

Signer du contenu

import { KeyManager } from '@sowasit/signer';

const content = {
  transaction_id: 'TXN-001',
  amount: 1500.00,
  timestamp: Date.now()
};

const privateKey = await KeyManager.loadPrivateKey(
  './keys/my-company.private.pem',
  'your-passphrase'
);

const { signature, algorithm } = KeyManager.signContent(
  content,
  privateKey
);

console.log('Signature:', signature);

Créer un bloc signé

import { SoWasItClient } from '@sowasit/signer';
import fs from 'node:fs/promises';

const client = new SoWasItClient({
  apiKey: 'sk_your_api_key'
});

const content = {
  event: 'product_shipped',
  order_id: 'ORD-12345',
  timestamp: Date.now()
};

const privateKeyPem = await fs.readFile('./keys/my-company.private.pem', 'utf-8');

const response = await client.createSignedBlock(
  'ch_your_chain_id',
  content,
  privateKeyPem,
  'your_public_key_id',
  'your-passphrase'
);

console.log('Block created:', response.block);

Bonnes pratiques de sécurité

🔒 Protection des clés privées

Toujours utiliser une passphrase pour chiffrer votre clé privée
Ne jamais commiter les clés privées dans Git
Stocker les clés dans un gestionnaire de mots de passe ou un HSM
Les clés privées sont automatiquement sauvegardées avec les permissions 0600

🔄 Rotation des clés

Générez de nouvelles clés régulièrement (tous les 6-12 mois)
Utilisez le mécanisme de remplacement lors de la rotation
Révoquez les anciennes clés après migration

⚠️ En cas de compromission

Révoquez immédiatement la clé compromise
Générez une nouvelle paire de clés
Notifiez l'équipe SoWasIt si nécessaire

Endpoints API

POST /keys/enrollment-tokens

Génère un token d'enrôlement à usage unique (7 jours de validité).

curl -X POST https://api.sowasit.io/keys/enrollment-tokens \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "authorized_by": "admin@company.com"
    },
    "validity_days": 7
  }'

POST /keys/register

Enregistre une clé publique avec un token d'enrôlement.

curl -X POST https://api.sowasit.io/keys/register \
  -H "Content-Type: application/json" \
  -d '{
    "enrollment_token": "abc123...",
    "public_key": "-----BEGIN PUBLIC KEY-----\n...",
    "algorithm": "ECDSA-P-256",
    "client_info": {
      "name": "My Company SARL",
      "siret": "12345678901234",
      "contact": "admin@company.com"
    }
  }'

GET /keys

Liste toutes vos clés publiques.

curl https://api.sowasit.io/keys \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /keys/{keyId}/revoke

Révoque une clé publique.

curl -X POST https://api.sowasit.io/keys/abc123/revoke \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Key compromised"
  }'

Dépannage

❌ "Block signature is required: tenant has active public keys"

Votre tenant a des clés actives enregistrées, donc tous les blocs doivent être signés.

Solution : Utilisez signer create-block ou signez manuellement avec signer sign.

❌ "Invalid passphrase for encrypted private key"

Votre clé est chiffrée mais vous avez fourni la mauvaise passphrase ou aucune passphrase.

Solution : Fournissez la bonne passphrase avec --passphrase.

❌ "Invalid block signature"

La vérification de la signature a échoué.

Causes possibles :

Le contenu a été modifié après signature
Mauvaise clé privée utilisée
Format de signature invalide
L'ID de clé publique ne correspond pas à la clé qui a signé

❌ "Public key is not active"

La clé n'est pas encore activée ou a été révoquée.

Solution : Vérifiez le statut de la clé dans votre dashboard. Complétez la certification si nécessaire.

Support

Documentation complète : docs.sowasit.io
Package NPM : @sowasit/signer
Dashboard : dashboard.sowasit.io
Email : support@sowasit.io